# Quickstart

> Install the Helix CLI, log in, scaffold a project, build with Claude Code, and deploy your first app to Tray's cloud in one command.

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](/documentation/reference/cli/).

:::warning{title="Deployed apps are never public"}
A deployed Helix app sits behind login. Everyone who opens it has to be a user in your Tray or Helix organization who you have granted access to that project. There is no anonymous URL and no public mode. [Identity and roles](/documentation/guides/identity-and-roles/) covers who gets in and how you change it.
:::

## Shortcut: let Claude set up your environment

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

:::tip{title="One prompt does steps 0–1 for you"}
Copy the [environment setup prompt](/documentation/getting-started/environment-setup/) into a Claude Code session. Claude checks your machine, installs Node and the Helix CLI, and reports back, then you rejoin this guide at [step 2, Log in](#2-log-in).
:::

## Before you start

Check all four before the clock starts:

| Requirement | How to check |
|---|---|
| Node.js ≥ 24.18.0 | `node --version`. Below that, upgrade (with nvm: `nvm install 24`) |
| npm or pnpm | `npm --version` (npm ships with Node) |
| Claude Code, installed and signed in | Run `claude` in a terminal. Install from [claude.com/claude-code](https://claude.com/claude-code) |
| A Tray account | Your Tray contact provisions your [workspace](/documentation/concepts/projects-and-workspaces/). No Tray contact yet? [Request access at helix.tray.ai](https://helix.tray.ai) |

## 1. Install the CLI

```bash
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:

```bash
helix --version
which helix
```

You want v0.85.0 or greater. `which helix` prints a path inside your global npm bin directory.

If this fails, see [Setup and install](/documentation/troubleshooting/#setup-and-install).

## 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:

```bash
helix login
```

This opens your browser. Sign in to Helix as you normally would.

If this fails, see [Identity and access](/documentation/troubleshooting/#identity-and-access).

## 3. Create a project

```bash
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](/documentation/getting-started/project-structure/) explains every file.

`helix init` takes four flags:

| Flag | What it does |
|---|---|
| `--force` | Scaffold even when the target directory already has files in it |
| `--with-app` | Also scaffold a front-end app alongside the functions |
| `--project-id <id>` | Bind the new project to an existing project ID |
| `--workspace-id <id>` | Set the workspace up front, so deploys stop asking |

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

## 4. Build with Claude

Start the agent inside the project:

```bash
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](/documentation/getting-started/building-with-claude/) 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:

```bash
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](/documentation/concepts/projects-and-workspaces/) you're provisioned in. If you don't have a Tray contact yet, [request access at helix.tray.ai](https://helix.tray.ai). If you skip this step, the CLI prompts when a workspace is needed.

## 6. Run locally

```bash
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.

| Flag | What it does |
|---|---|
| `-p, --port <number>` | Serve on a port you choose |
| `--pretty-logs` | Formatted, readable log output (the default) |
| `--raw-logs` | Unformatted log output |

## 7. Deploy

```bash
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](/documentation/troubleshooting/#runtime-and-deploy).

## 8. Open the dashboard

Every project, its deployments, and its execution logs live in the [Helix dashboard](https://app.helix.tray.ai). Open your app there to check deployment status, read logs, and set who can open the app on its Access Control tab.

## Next steps

- [Building with Claude Code](/documentation/getting-started/building-with-claude/): let the agent do more of the work.
- [Project structure](/documentation/getting-started/project-structure/): what's inside the project you just created.
- [Troubleshooting](/documentation/troubleshooting/): fixes when a step doesn't go to plan.

---

Canonical: https://helix.tray.ai/documentation/getting-started/quickstart/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt