# Local development commands

> Run your project locally with helix dev, pick a port and a log format, and see how local storage and auth differ from production.

`helix dev` runs your project on your machine with hot reload, serving on `http://localhost:3000` by default. It's the only local-development command in the CLI: everything else you'd do while building (adding functions, testing routes, reading logs) happens in your editor, in Claude, or with an HTTP client.

## helix dev

```bash
helix dev
```

Starts the local dev server and watches your files, reloading as you save. Stop it with `Ctrl+C`.

| Flag | What it does |
|---|---|
| `-p, --port <number>` | Serve on this port instead of 3000 |
| `--pretty-logs` | Format logs for humans. This is the default |
| `--raw-logs` | Print raw OpenTelemetry JSON instead of formatted logs |
| `--config <path>` | Config file to use instead of `./helix.config.ts`, selecting the workspace and auth aliases the dev server resolves against. The `HELIX_CONFIG` environment variable has the same effect |

```bash
helix dev --port 4000
helix dev --raw-logs
helix dev --config helix.production.config.ts
```

Use `--raw-logs` when you want the full structured record: trace and span IDs, severity, and every attribute, exactly as the platform receives it. `--pretty-logs` shows the same records formatted to read at a glance.

## Testing routes locally

Send requests to the dev server with any HTTP client:

```bash
curl http://localhost:3000/api/v1/users
```

## How local differs from production

Local runs are close to production but not identical. Two differences matter while you're building:

**Key-value storage is in memory.** Local KV lives in the dev server's process and resets every time you restart `helix dev`. Data you write locally does not persist between runs, and it never reaches the deployed project. To read and write the project's provisioned, persistent KV, set the project ID first with `helix project set <id>`. See the [key-value store guide](/documentation/guides/key-value-store/).

**Authentications resolve differently.** How the local dev server resolves an auth alias to a credential is not the same path a deployed function takes. Aliases that work locally can behave differently once deployed, so test authenticated calls against a real deploy before you rely on them.

**Scheduled functions don't run locally.** `helix dev` warns about files in `functions/_scheduled/` at startup; their crons fire only in production. A local scheduler is planned. See the [scheduled functions guide](/documentation/guides/scheduled-functions/).

:::note{title="The full list isn't documented yet"}
These are the known local-versus-production differences. If you hit another, tell your Tray contact so we can document it.
:::

---

Canonical: https://helix.tray.ai/documentation/reference/cli/dev/
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