Quickstart

This quickstart takes you from an empty terminal to a deployed Helix app: install the CLI, log in, scaffold a project, build with Claude Code, and ship it. Each step is one or two commands, with a recovery link if something fails.

Already know the CLI? Jump to the CLI reference.

Shortcut: let Claude set up your environment

Already have Claude Code installed? You can skip the manual setup entirely.

Before you start

Check all four before the clock starts:

1. Install the CLI

npm install -g @trayai/helix-cli

Prefer pnpm? pnpm add -g @trayai/helix-cli. You can also run one-off commands without installing: npx @trayai/helix-cli <command>.

Verify the install:

helix --version
which helix        # macOS/Linux; on Windows use Get-Command helix (or "where helix" in cmd)

You want a recent version (minimum v1.0.0). which helix prints a path inside your global npm bin directory. On Windows there is no which: use Get-Command helix in PowerShell, or where helix in Command Prompt.

Helix ships often, so stay current rather than pinning to a version: check helix --version against npm view @trayai/helix-cli version, and run npm update -g @trayai/helix-cli to upgrade. The CLI and the SDK share a version, so update a project’s @trayai/helix-sdk to match whenever you upgrade the CLI.

If this fails, see Setup and install. On Windows, a “not recognized” error means your npm global bin directory isn’t on PATH, see Windows quick reference.

2. Log in

You can scaffold a project and build locally with Claude without logging in. Logging in is what lets you deploy, use authentications, and manage workspaces, so do it now.

Run this in a plain terminal, outside your Claude session:

helix login

This opens your browser. Sign in to Helix as you normally would, then run helix whoami to confirm the session landed. Your session is saved to ~/.tray.config (%USERPROFILE%\.tray.config on Windows) and persists machine-wide, so you log in once per machine, not once per terminal or per tool. Every coding agent on that machine inherits the session.

If the browser can’t open (a headless box, or a WSL or SSH session), run helix login --method chrome to read the session from a signed-in Chrome, or copy the printed sign-in URL into any browser.

On a locked-down corporate machine behind a VPN or a TLS-inspecting proxy, sign-in can succeed in the browser but the CLI then fails with Login failed: fetch failed.. The browser trusts your company’s root certificate, but Node doesn’t, so it rejects the CLI’s callback. Point Node at the system certificate store and proxy with NODE_OPTIONS, then log in again. --use-system-ca is the flag that matters: it makes Node trust the same corporate root certificate the browser already trusts.

On macOS or Linux (bash):

export NODE_OPTIONS="--use-env-proxy --use-system-ca"
helix login

On Windows (PowerShell):

$env:NODE_OPTIONS = "--use-env-proxy --use-system-ca"
helix login

In Windows Command Prompt, run set NODE_OPTIONS=--use-env-proxy --use-system-ca before helix login. To keep the setting across terminals, add NODE_OPTIONS as a permanent environment variable. If sign-in is still blocked, the machine is doing corporate certificate inspection, so check with your IT team.

If this fails, see Identity and access.

3. Create a project

helix init my-app
cd my-app
npm install

helix init scaffolds a complete project: helix.config.ts, sample functions, and the .mcp.json file Claude Code uses to discover the project’s tools. Project structure explains every file.

helix init takes four flags:

Pass . as the name to scaffold into the current directory: helix init .. If that directory isn’t empty, add --force.

4. Build with Claude

Using a different agent? Skip to Building with other coding agents to point it at the project, then rejoin at step 5. The rest of this guide is the same whichever agent you use.

Start the agent inside the project:

claude

The first time you run Claude here it asks two things: whether to trust the folder, and whether to use the Helix MCP server. Say yes to both. The MCP server is how Claude reads the project and drives the CLI, so the workflow doesn’t work without it.

Then ask it to write code, wire up an authenticated service, run the app locally, or deploy. Building with Claude Code covers the workflow and prompting patterns.

5. Choose a workspace

Helix apps live inside a Tray workspace. Select one before deploying or using authenticated services:

helix workspace select

helix workspace select lists the workspaces you can pick from and saves your choice. If you already know the ID, set it directly with helix workspace set <id>.

You have to be a member of the workspace you deploy into. Your Tray contact tells you which workspace you’re provisioned in. If you don’t have a Tray contact yet, request access at helix.tray.ai. If you skip this step, the CLI prompts when a workspace is needed.

Authentications belong to the workspace too. Once one is selected, run helix auth connect to pick from what’s already there, or helix auth connect --new to create a new authentication in the browser and connect it. Anyone with access to the workspace can use its authentications, so keep narrowly-scoped credentials in it. See connected services.

6. Run locally

helix dev

The dev server serves your app at http://localhost:3000, or the next free port if 3000 is taken. Read the startup output for the port it actually picked.

7. Deploy

helix deploy

The first deploy provisions the project. It asks which workspace to deploy into, then generates a project name and an AI-written description of what the app does. Every later deploy uploads a new artifact to the same project.

When it finishes, the CLI prints three things: the project ID, the live app URL (https://{project-id}.helix-app.ai), and a link to the project in the dashboard.

If this fails, see Runtime and deploy.

8. Open the dashboard

Every project, its deployments, and its execution logs live in the Helix dashboard. Open your app there to check deployment status, read logs, and set who can open the app on its Access Control tab.

You manage the project at app.helix.tray.ai (deployments, logs, and access), while the app itself answers at https://{project-id}.helix-app.ai behind login. A sign-in prompt at the app URL is expected, not a fault.

Windows quick reference

Every step above works on Windows. You have two ways to run it:

• Native Windows (PowerShell or Windows Terminal): follow the steps as written, applying the equivalents below.
• WSL2 (Ubuntu on Windows): install and run everything inside the Linux shell and follow this guide exactly as it stands, since from inside WSL you are effectively on Linux. Open your editor into the WSL environment (VS Code’s WSL extension, or Cursor’s remote support).

If helix is “not recognized” after install, your npm global bin directory isn’t on your PATH. Find it with npm config get prefix (native Windows installs usually land in %AppData%\npm), add that folder to your PATH (search “Edit environment variables for your account”), then open a new terminal. As a fallback, run any command without a global install: npx @trayai/helix-cli <command>.

Next steps

• Building with Claude Code: let the agent do more of the work.
• Building with other coding agents: use Cursor, VS Code, Codex, or another MCP client instead.
• Project structure: what’s inside the project you just created.
• Troubleshooting: fixes when a step doesn’t go to plan.