Dev Server

dawn dev is the local application loop: it starts Dawn's HTTP runtime, watches your app, regenerates types, and replaces the child runtime when source files change. Use this page to start and operate the server; use the linked protocol guides when you are building a client.

Starting the server

dawn dev

The server binds an ephemeral localhost port and prints a URL such as Dawn dev ready at http://127.0.0.1:43127. Select a stable port when another process needs a predictable address:

dawn dev --port 3001

The bind address is always 127.0.0.1.

Invoking a route

With the server running, invoke a route from another terminal:

echo '{"messages":[{"role":"user","content":"Hello"}]}' |
  dawn run '/research' --url http://127.0.0.1:3001

dawn run resolves the route to its <routeId>#<kind> assistant id, creates a thread id for the call, sends the input through Agent Protocol, and prints the final state.

Restart cycle

When a meaningful app file changes, Dawn regenerates types before it launches the replacement runtime. Ignored paths such as .dawn/, workspace/, and lockfiles do not trigger a restart; the restart log names the reason for changes that do.

The parent owns the app root, watcher, session, selected port, and stable URL across restarts; the child owns the HTTP listener and route graph. Each restart stops that child and its listener, then starts a fresh child on the same port. This is a child-process restart, not in-process HMR and not a parent-owned bound listener.

The replacement child reloads the app and dawn.config.ts, including store and runtime configuration. Configuration edits take effect on that restart; the parent does not keep the previously loaded configuration alive.

The default SQLite threads store and checkpointer preserve persisted threads and checkpoints across child restarts. Configured durable stores preserve data when the replacement child reconnects; an in-memory store does not survive the child-process restart. In-flight work gets a short shutdown grace window before the old child can be force-killed.

Logging

The ready line identifies the current URL, and each restart line identifies the changed file category. Set DAWN_DEV_SHUTDOWN_TIMEOUT_MS to change the grace window used while stopping a child runtime.

Agent Protocol endpoints

The HTTP contract moved to Agent Protocol.

SSE event types

Event table: Agent Protocol.

Thread lifecycle with curl

Agent Protocol has the copyable create, run, and state sequence.

One run at a time per thread

See Agent Protocol for run serialization and explicit cancellation.

Client disconnect

See Agent Protocol for the durable viewer-disconnect policy.

AG-UI endpoint

Browser clients use the separate AG-UI endpoint and lifecycle.

Tracing

See Observability for environment variables, trace setup, and interrupt-related trace behavior.

Middleware

See Middleware for execution-route behavior and Security Architecture for the management routes that require service-wide outer authentication.

Middleware is not the only in-runtime gate. Thread access is a second one on a different axis — the thread rather than the route — and it covers every thread endpoint, including the ones middleware never sees. Where both apply they compose as AND.

Related