Launch and Runtime

This page covers the local, session-oriented half of the CLI: the default app command and dreadnode serve.

The three runtime-related entry points

Command	Use it for
dn	launch the app
dn --print --prompt ...	run one-shot headless mode and exit
dn serve	host a local runtime server without opening the app

Default app command

Running dreadnode or dn with no subcommand starts the app.

dn
dn --model openai/gpt-4.1-mini --agent assistant
dn --resume 7c1e2d4f
dn --runtime-server http://127.0.0.1:8787

Use this mode when you want the interactive client.

Session launch flags

Flag	Meaning
--runtime-server <url>	connect to an already-running runtime server instead of auto-starting the default local one
--resume <session-id>	resume a previous session by ID or prefix
--model <id>	select the model at launch
--agent <name>	select the agent at launch
--capability <name>	enable a specific capability, repeatable
--capabilities-dir <path>	add an extra capability directory, repeatable
--prompt <text>	send an initial prompt
--system-prompt <text>	append extra system instructions
--print	execute --prompt, print the response, and exit

--print requires --prompt.

Headless print mode

Use --print when you want one-shot CLI behavior instead of the full app session.

dn --print --prompt "Summarize the last evaluation run" --model openai/gpt-4.1-mini
dn --print --prompt "List installed capabilities" --capability dreadairt

Note

--print still uses the same runtime and agent machinery as the app. It is not a separate control-plane subcommand.

Connect to an existing runtime server

Use --runtime-server when another process is already hosting the runtime.

dn --runtime-server http://127.0.0.1:8787
dn --runtime-server http://127.0.0.1:8787 --agent assistant --model openai/gpt-4.1-mini

This is different from --server, which means the platform API URL.

Host a local runtime server

Use dreadnode serve to run the runtime server without launching the app.

dn serve --host 127.0.0.1 --port 8787 --working-dir .
dn serve \
  --platform-server https://app.dreadnode.io \
  --api-key "$DREADNODE_API_KEY" \
  --organization acme \
  --workspace main

The runtime server exposes two different interaction surfaces:

• REST endpoints such as /api/runtime and /api/sessions for runtime metadata and session management
• an interactive WebSocket at /api/ws for hello, subscribe, turn.start, turn.cancel, prompt.respond, and ping

The runtime server no longer exposes /api/chat for interactive streaming. First-party interactive clients should use /api/ws.

The interactive WebSocket is runtime-scoped, not turn-scoped. One client connection can subscribe to multiple session streams, and each session stream carries its own ordered sequence numbers and stable turn_id values.

The runtime wire contract is currently schema_version=2. Reconnects should replay buffered events when the requested after_seq cursor is still in memory; otherwise the server emits transport.resync_required followed by a fresh session.snapshot so the client can rebuild state explicitly instead of guessing.

When the runtime is protected with DREADNODE_RUNTIME_TOKEN, both HTTP and WebSocket requests must send Authorization: Bearer <token>. The legacy name SANDBOX_AUTH_TOKEN is still honored for one release but emits a deprecation warning on startup; prefer the new name.

Local runtime smoke test

You can validate the local runtime path without platform login by starting a server, checking its health endpoint, and sending a one-shot prompt through it.

dn serve --host 127.0.0.1 --port 8787 --working-dir .
curl http://127.0.0.1:8787/api/health
dn --runtime-server http://127.0.0.1:8787 --print --prompt "hello"

If you omit --platform-server and --api-key, dn serve stays local-only. That makes this the fastest smoke test for CLI install, runtime startup, and one-shot prompt execution.

Serve flags

Flag	Meaning
--host <host>	bind host for the local runtime server
--port <port>	bind port for the local runtime server
--working-dir <path>	working directory before the server starts
--platform-server <url>	platform API URL used by the local runtime
--api-key <key>	platform API key used by the local runtime
--organization <slug>	default organization for runtime-originated platform calls
--workspace <slug>	default workspace for runtime-originated platform calls
--project <slug>	default project for runtime-originated platform calls
--verbose	enable verbose trace logging

If you omit --host or --port, the runtime falls back to DREADNODE_RUNTIME_HOST, DREADNODE_RUNTIME_PORT, and then 127.0.0.1:8787. The legacy names DREADNODE_SERVER_HOST / DREADNODE_SERVER_PORT are still accepted for one release with a deprecation warning on startup.

Clients (the TUI, dn --print, workers) can point at a non-default runtime via DREADNODE_RUNTIME_URL (full URL, e.g. http://127.0.0.1:8787) instead of composing from the host/port pair.

Runtime server vs runtime record

These are different:

• dn serve starts a local runtime server process
• dn runtime list and dn runtime get inspect runtime records in the platform

That distinction matters because many hosted workflows talk about runtimes in the control plane, but the default app command talks to an actual runtime server.

dn runtime list --profile staging --workspace lab
dn runtime get <runtime-id> --profile staging --workspace lab

See /cli/runtime-and-evaluations/ for the control-plane side.