Deployment

Dawn does not host or run production traffic itself. It owns local development (dawn dev, dawn run, dawn test) and the build step that produces deployable artifacts (dawn build). Production runs on LangSmith or another runtime that consumes the generated LangGraph entry files. Use live-server scenario tests to catch protocol-shape issues before deployment.

The deployment path

1. 1

   Verify locally

   text

   dawn verify

   dawn verify runs four checks in one call: app contract, route discovery, typegen, and deps (missing packages and missing env vars). Pass --json for machine-readable output. The deps check is uniquely useful before a deploy — neither dawn check nor dawn typegen covers it.

   Optionally follow with scenario coverage:

   text

   dawn test

2. 2

   Confirm protocol parity

   Run scenarios against a live dev server by setting run.url per-scenario in your run.test.ts files (the command-level --url flag does not exist on dawn test). dawn dev exposes LangSmith-style protocol endpoints — /runs/wait and /runs/stream — so this catches request/response shape issues before deploy. Process boundaries, state persistence, and tool bindings are still re-materialized by dawn build for production, so this step is necessary but not sufficient.

   text

   dawn dev --port 3001 &
   # In your run.test.ts: set run: { url: "http://127.0.0.1:3001" } per scenario
   dawn test

3. 3

   Build the deployment artifact

   dawn build writes .dawn/build/langgraph.json along with per-route entry files under .dawn/build/<routeSlug>.ts. For agent routes, the generated entry imports your default agent() descriptor, materializes it as a LangGraph graph, and wires in every discovered route tool.

   text

   dawn build --clean

   A typical generated .dawn/build/langgraph.json looks like:

   json

   {
     "graphs": {
       "/hello/[tenant]#agent": "./.dawn/build/hello-tenant.ts:graph"
     },
     "dependencies": ["."],
     "env": ".env.example",
     "node_version": "22"
   }

   Notes:

   • Each assistant_id is <routeId>#<kind> — e.g. /hello/[tenant]#agent. Use this exact string as assistant_id in any client request.
   • dependencies: ["."] and node_version: "22" are required by LangSmith.
   • env resolves to .env.example when that file exists, else .env.
   • If you keep a hand-authored langgraph.json at the app root, dawn build shallow-merges it on top of the generated values.
4. 4

   Local middleware (optional)

   src/middleware.ts (default-exporting a function from defineMiddleware) runs before local /runs/wait and /runs/stream requests handled by dawn dev. Use it to gate access by header, populate request-scoped context, or reject(status, body) unauthorized callers during local development and live-server tests. dawn build does not currently materialize this middleware into the generated LangSmith entry files. See Middleware for the API.

5. 5

   Push to your LangSmith-connected remote

   LangSmith builds from the generated langgraph.json and route entry files, then provisions assistants keyed by the <routeId>#<kind> ids. From there, your agents and harnesses can hit the deployed endpoints using those assistant ids.

What Dawn does not do

Self-hosting

If you can't or won't use LangSmith, build with dawn build and feed .dawn/build/ to your own container. The generated entry files and langgraph.json are the canonical interface — the in-process dawn dev runtime is a reference for the same protocol surface (/runs/wait, /runs/stream, /healthz), but is not intended as a production runtime itself.

Troubleshooting

• Tests pass in-process but fail live-server — a tool or route isn't serializing cleanly. Check that inputs, outputs, and state are JSON-serializable (no Dates, Maps, classes).
• Assistant id not found — the request assistant_id doesn't match the <routeId>#<kind> keys in .dawn/build/langgraph.json. Inspect that file directly (cat .dawn/build/langgraph.json) or run dawn verify --json to confirm what was discovered.
• Type inference drifted — run dawn typegen locally and inspect .dawn/dawn.generated.d.ts. The generated file is ignored by the starter template, so regenerate it in CI/build steps unless your project chooses to commit .dawn/.

Related