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. --json prints the standard envelope.

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 registers a new agent and scaffolds its own package.json over the project you received. stackbone 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);
• 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.

Full reference: 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, 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.

JSON payload (printed once the runtime is up)

{
  "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).