---
title: 'dev'
description: 'Boot the full local runtime for the project and open a tunnel so cloud-hosted Studio can reach it'
position: 9
---

# stackbone dev

> The runtime `dev` boots is the default target of every verb that talks to an
> installation: with no `--agent` they reach it, and they fail fast with
> `dev_not_running` (exit `3`) when it is not up. See
> [target resolution](/docs/cli/reference/conventions#target-resolution).
> `--json` prints the [standard envelope](/docs/cli/reference/conventions#json-output).

Boot the full local runtime for the project and open a tunnel through
Stackbone's `frpc` relay (`*.tun.stackbone.ai`) so cloud-hosted Studio can reach
it. The emulator API listens on `http://127.0.0.1:4242` by default. The tunnel is
mandatory: it publishes a reachable URL for this session and yields the Studio
deeplink.

`dev` links a project someone handed you. `.stackbone/` is
gitignored, so a project cloned from someone else's repository arrives with no
link. `dev` lists the agents your organization owns, lets you pick one or create
a new one named after the folder, writes `.stackbone/project.json` and carries on
booting. Neither alternative fits this case.
[`stackbone init`](/docs/cli/reference/init) registers a _new_ agent and
scaffolds its own `package.json` over the project you received.
[`stackbone link`](/docs/cli/reference/link) registers a box you already
deployed, so it requires its URL, HMAC secret and image tag.

Non-interactive runs (`--json`, `--yes`, CI, no terminal) still fail rather than
guessing, and say what to do instead.

The project is a **workspace**: every `deep-agents/<name>/index.ts`, plus
every `workflows/<name>.workflow.ts`, discovered by convention (with an
explicit `stackbone.config.ts` override for workflows). Boot:

- stands up Postgres + **Redis** + MinIO (Postgres holds your data, Redis is the
  durable backend the workflow runtime replays from, MinIO is S3-compatible
  storage);
- applies the platform migrations and your own migrations under
  `.stackbone/migrations`;
- seeds the system secrets the runtime injects (including the resolved
  [model-provider credential](/docs/cli/guides/local-development#model-provider));
- generates the editor type files under `.stackbone/` (`agents.d.ts`,
  `workflows.d.ts`, `connect.d.ts`, `config.d.ts`) so your IDE knows the agent,
  workflow, connection and config shapes;
- serves the chat endpoints (`POST /openai/v1/chat/completions`,
  `POST /anthropic/v1/messages`) and the durable workflow routes
  (`POST /api/workflows/:name/start`, `/chat`);
- then, past the **boot gate**, compiles every agent and every durable workflow
  on your machine, in-process (no ports, no child processes).

Your code runs last, and only once the environment can support it. With no model
provider configured and no completed first run, the boot stops at the gate,
prints a Studio link and waits, leaving the emulator and tunnel up. See
[The first run](/docs/cli/guides/local-development#the-first-run).

Full reference: [Local development](/docs/cli/guides/local-development).

| Flag               | Type    | Default | Description                                                                                                                                                     |
| ------------------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--port`           | string  | `4242`  | Emulator API port. Coerced to an integer in the range 1–65535; invalid values exit with `error.code = "generic"`.                                               |
| `--listen`         | boolean | `false` | Bind the HTTP server to `0.0.0.0` (LAN-reachable). Default binds to `127.0.0.1` only.                                                                           |
| `--print-contract` | boolean | `false` | Print the JSON contract this CLI advertises (same payload as the emulator's `/api/contract`) and exit without booting.                                          |
| `--auto-migrate`   | boolean | on      | Generate and apply a migration when you edit `src/schema.ts` mid-session. Pass `--no-auto-migrate` to drive migrations yourself. Wins over `agent.yaml`.        |
| `--verbose`        | boolean | `false` | Global flag (available on every command). Streams every log line and container output; the default UI uses per-stage spinners, `--verbose` is the raw firehose. |

Pass neither `--auto-migrate` nor `--no-auto-migrate` and the session falls back
to `dev.autoMigrate` in [`agent.yaml`](/docs/cli/reference/agent-yaml), which itself
defaults to on. Either flag overrides that file for this session only.

To run two projects at once on the same machine, export
`STACKBONE_DEV_PORT_OFFSET` in the second shell and every port shifts together:
the API port, Postgres, Redis and MinIO. See
[Configuration → environment variables](/docs/cli/reference/configuration#environment-variables).

**JSON payload** (printed once the runtime is up)

```jsonc
{
  "schema_version": 1,
  "emulator_url": "http://127.0.0.1:4242",
  "agent_url": "http://127.0.0.1:4242" /* deep agents are served by the emulator itself */,
  "public_url": "https://<subdomain>.tun.stackbone.ai" /* or null */,
  "deeplink": "https://app.stackbone.ai/app/<orgSlug>/installations/<id>?stackbone-dev=..." /* or null when the tunnel handshake failed */,
  "local_dev_installation_id": "...",
  "gate": {
    "open": true /* false = your workflows and agents were NOT started */,
    "reason": "model-provider-env" /* also: model-provider-stored, first-run-completed, no-model-provider */,
  },
  "deep_agents": [
    "support",
    "billing",
  ] /* every serving agent name; empty while the gate is closed */,
  "services": {
    "postgres_url": "postgres://...",
    "s3_endpoint": "http://127.0.0.1:9004",
    "s3_bucket": "stackbone-dev",
  },
}
```

**Exit codes**: `0` ok (graceful Ctrl-C), `2` auth (not signed in), `3` no
project (cwd has no `.stackbone/project.json`), `4` not found (linked agent
disappeared upstream), `1` generic (Docker missing, port busy, an invalid
`--port`).