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.

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.