Local runtime server

The default dn command auto-starts a local runtime server. Use dn serve when you want that server running standalone — no interactive app attached — so multiple clients can share it, so CI can hit a stable endpoint, or so you can smoke-test the runtime path without the TUI.

The three entry points

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

Run it

dn serve --host 127.0.0.1 --port 8787 --working-dir .

Host and port default to 127.0.0.1:8787 when you don’t pass them (or via DREADNODE_RUNTIME_HOST and DREADNODE_RUNTIME_PORT).

Connect a client to it with --runtime-server:

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

Clients can also resolve the URL from DREADNODE_RUNTIME_URL instead of composing host and port.

Note

--runtime-server and --server are different. --runtime-server points at a local runtime process; --server points at the Dreadnode platform API URL.

Smoke test the local path

Start the server, check its health, send a one-shot prompt.

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’s the fastest way to verify CLI install, runtime startup, and one-shot prompt execution without platform authentication.

Let an agent inspect its runtime

Runtime agents have a read-only runtime_info tool, subject to their normal tool access rules. Ask “Which capabilities are loaded, and what is broken?” No runtime URL, token, or platform runtime ID is needed.

The result lists capability names and versions, loaded and enabled state, and recorded component statuses with diagnostic reasons. It includes failed loads, MCP servers, workers, and preflight checks across all capabilities. Diagnostics redact common credential patterns and omit raw configuration and environment data.

The calling agent’s identity and exposed tool names are reported separately: a loaded component does not imply that its tools are available to that agent. Each invocation reads current registry state, including reloads and component transitions. Existing agents keep their assigned tools until the next turn, so their tool list can differ from the latest runtime inventory.

A successful inspection does not mean every capability is healthy. Empty health records or an unavailable registry mean health is unknown. The tool reports recorded state rather than probing or repairing components; agents should describe which functionality is blocked or degraded and include the reported reason.

Connect to the platform from the local server

dn serve \
  --platform-server https://app.dreadnode.io \
  --api-key "$DREADNODE_API_KEY" \
  --organization acme \
  --workspace main

With those flags, the local runtime talks to the Dreadnode platform for anything it needs to resolve — secrets, projects, capability catalog, runtime records — while still running the agent loop locally.

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 for the server process
--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

Authentication

Set DREADNODE_RUNTIME_TOKEN on the server to require a bearer token from every HTTP and WebSocket client:

export DREADNODE_RUNTIME_TOKEN="$(openssl rand -hex 32)"
dn serve

Clients must send Authorization: Bearer <token> for every request. Unset, the server is open on the bound interface — keep it on 127.0.0.1 when running without a token.

Runtime server vs runtime record

They share a name but are different things:

• dn serve starts a local runtime server process — the thing a client’s interactive session talks to.
• dn runtime list / dn runtime get inspect workspace runtime records in the platform — the durable resource with sessions, bindings, and a sandbox behind it.

When a hosted runtime is what you want, see Managing runtimes.