Installation, onboarding, and authentication¶

This guide walks you through the Cortex Code Desktop interface and shows you how to connect it to your Snowflake account so you can start asking questions, exploring data, and building workflows in plain English.

Onboarding and sign in¶

On first launch, Cortex Code Desktop guides you through a four-step setup flow — welcome → connect → mode → theme. A progress indicator at the top of the window shows which step you’re on, and you can use Back to revisit an earlier step. If you already have a ~/.snowflake/connections.toml file (for example, from Cortex Code CLI), your existing connections are detected automatically.

Step-by-step¶

1. Welcome. Launch Cortex Code Desktop. The Welcome screen introduces Cortex Code. Click Next to begin setup.

2. Connect to Snowflake. If existing connections are detected (from a connections.toml file), they appear in a list with a status dot. Select one, use the edit (pencil) icon to modify it, or click the chevron to expand its connection details. Click Add connection to create a new one. Click Next to continue, or Skip to set up later.

When adding a connection, fill in the form. The panel includes inline instructions for finding your account identifier and login name in Snowsight (app.snowflake.com → your avatar → Connect a tool to Snowflake):

• Account identifier — for example, myorg-myaccount (see Find your account identifier).
• Connection name — a friendly label, auto-generated from the account identifier.
• Username — your Snowflake login name.
• Authentication method — Local OAuth (recommended), External browser (SSO), or Password.

Click Sign in to store the connection and authenticate. For OAuth or SSO, complete sign-in in your browser when prompted.

3. Choose a mode. Pick how Cortex Code starts up:

   • Agent — optimized for parallel agent sessions across multiple workspaces.
   • Editor — optimized for working with your files while keeping agent sessions on the side.

   You can switch between Agent and Editor modes at any time. Click Next.

4. Choose your theme. Select Light or Dark (you can change it later in Settings), then click Get Started to launch the main app.

Find your account identifier¶

1. Sign in at app.snowflake.com.
2. Click your avatar in the bottom-left corner and select Connect a tool to Snowflake.
3. Copy the account identifier (orgname-accountname) and your login name. You can also read the account identifier from the URL: https://app.snowflake.com/orgname/accountname/.

Manage connections after setup¶

You can add, edit, or switch connections at any time from within the app:

Open the connection menu: Click the connection name in the top navigation bar to reveal a dropdown with connection management options:

• Manage Snowflake Connections — Opens the connection manager dialog where you can switch between connections, add new ones, or edit/delete existing ones.
• View Snowflake Connections — Shows your connections.toml file for quick reference.
• Refresh Snowflake Connections — Reloads connections from disk (useful after manually editing the config file).
• Change Role — Switch your active Snowflake role without disconnecting.
• Default Warehouse — Choose the warehouse new sessions use. Cortex Code persists the choice to your Snowflake user with ALTER USER SET DEFAULT_WAREHOUSE and updates your connections.toml locally, so subsequent connections use the selected warehouse without setting it each session.
• Private Mode — Toggle private mode for sensitive work.

Manage Connections dialog: Select Manage Snowflake Connections to open this dialog. Use the radio buttons to switch between connections, the edit (pencil) icon to modify a connection, or the trash icon to delete one. Click Add Connection to create a new connection.

Edit or add a connection: Clicking the edit icon or Add Connection opens the Edit Connection dialog. This form works the same as the onboarding form — fill in your Account Identifier, Connection Name, Username, and Authentication Method, then click Save.

Default warehouse¶

Cortex Code Desktop lets you set a default warehouse for your active connection at any time. The warehouse is persisted server-side on your Snowflake account so it applies across all sessions and devices.

Set or change the default warehouse¶

1. Click your connection name in the top navigation bar to open the connection dropdown.
2. Select Set Default Warehouse.
3. Choose a warehouse from the list and confirm.

The selected warehouse becomes active immediately and is used for all subsequent queries in this and future sessions.

UI walkthrough¶

The Cortex Code Desktop interface has four key areas:

1. Top Navigation Bar: Shows your active Snowflake connection, a global Search, and the Agent/Editor toggle on the right that switches how the assistant operates.
2. Left Sidebar: Create a New Session, open Automations, and browse your Projects. Each project corresponds to a working directory on your computer.
3. Main Chat Area: The central area where your conversation with the assistant happens — messages, tool runs, code, SQL results, charts, and file diffs all appear here. The input bar sits at the bottom: type your messages, use / to invoke skills and @ to add context, and pick your mode (Agent or Editor), model, and approval preferences. On a new session it also shows starter prompt chips.
4. Right Toolbar: A vertical strip of quick-access icons for the in-app browser, SQL, Snowflake objects, the file explorer, source control, and more.

Authentication methods¶

Cortex Code Desktop supports several ways to sign in to Snowflake. Pick the one that fits your account.

Local OAuth (recommended)¶

Opens your browser to sign in securely. Tokens are cached in your operating system’s keychain so you don’t have to sign in every time. This is the default and recommended option.

[my-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "oauth_authorization_code"
client_store_temporary_credential = true

External Browser (SSO)¶

Sign in through your organization’s Identity Provider (Okta, Azure AD, etc.). Requires that SSO is configured for your Snowflake account.

[my-sso-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "externalbrowser"
client_store_temporary_credential = true

Password¶

Traditional username and password. If your account has MFA enabled, you’ll be prompted in your authenticator app on sign-in.

Key Pair (JWT)¶

Authenticate with an RSA key pair. Common for service accounts and automated workflows. Configure this by editing your connections.toml directly.

[my-keypair-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "snowflake_jwt"
private_key_path = "~/.ssh/snowflake_rsa_key.p8"

Connection file reference¶

Cortex Code Desktop reads connection settings from ~/.snowflake/connections.toml. You can edit this file directly, set defaults like warehouse and role, and define multiple named connections.

# ~/.snowflake/connections.toml
default_connection_name = "dev"

[dev]
account = "myorg-myaccount"
user = "myuser"
authenticator = "oauth_authorization_code"
client_store_temporary_credential = true
warehouse = "COMPUTE_WH"
role = "MY_ROLE"
database = "MY_DB"
schema = "PUBLIC"

[prod]
account = "myorg-prodaccount"
user = "myuser"
authenticator = "externalbrowser"
client_store_temporary_credential = true

Common fields¶

Credential security¶

Cortex Code Desktop stores authentication tokens using your operating system’s built-in encryption:

• macOS: Keychain
• Windows: Data Protection API (DPAPI)
• Linux: System secret service (libsecret / GNOME Keyring)

This lets the app reconnect automatically on subsequent launches without asking you to sign in again.

Troubleshooting¶

Connection test failures¶

Browser doesn’t open for OAuth/SSO¶

• Make sure you have a default browser configured.
• Use the fallback link displayed in the app to sign in manually.

Re-run onboarding¶

Open the command palette and run Reset Onboarding to see the setup flow again on the next launch.

Best practices¶

• Use OAuth or SSO for the most secure sign-in experience — no passwords stored on disk.
• Enable credential caching (client_store_temporary_credential = true) so you don’t re-sign-in every launch.
• Set a default warehouse (during setup, from the connection menu, or in connections.toml) to avoid errors when running queries.
• Name connections descriptively (for example, prod-analytics, dev-sandbox) so they’re easy to pick from the dropdown.