A work tracker built with TanStack Start and TanStack AI, deployed on Railway. Every task has a Run button. Press it and a Railway sandbox boots, Claude Code works the task inside it, and each step lands in the task's activity feed.
The sandbox work goes through TanStack AI's sandbox primitives: defineSandbox and defineWorkspace describe the sandbox, the @tanstack/ai-sandbox-railway provider creates it on Railway, withSandbox attaches it to a chat() call, and the @tanstack/ai-claude-code harness runs Claude Code inside it.
- Quick start
- How a run works
- Deploying on Railway
- Access and the API
- Developing locally
- Project structure
- Making it your own
Deploy: click Deploy on Railway above and enter an ANTHROPIC_API_KEY from the Anthropic Console. Railway provisions the app and Postgres, generates the access password, runs the migrations, and gives you a URL.
Give it a project token. Dispatch creates sandboxes with a Railway project token, which can only reach this project's environment:
- In the new project, open Settings → Tokens and create a token for the
productionenvironment. - Add it to the
Dispatch-Webservice as a variable namedRAILWAY_TOKEN, and deploy the change.
The app's Settings page links to the tokens page and shows what's still missing.
Then sign in with the DISPATCH_PASSWORD variable Railway generated, open a task, and press Run in Agent Sandbox.
Run locally (Node 24+, pnpm, Docker):
pnpm install
cp .env.example .env # add ANTHROPIC_API_KEY, RAILWAY_TOKEN, RAILWAY_ENVIRONMENT_ID
pnpm db:up # Postgres in Docker
pnpm db:migrate # create tables and seed the Default project
pnpm dev # http://localhost:3000flowchart LR
browser["Browser"] -- "Run" --> web["Dispatch-Web<br/>TanStack Start"]
web -- "chat() + withSandbox" --> sandbox["Railway sandbox<br/>Claude Code"]
sandbox -- "AG-UI events" --> web
web -- "activity rows" --> db[("Postgres")]
browser -- "polls the feed" --> web
- The sandbox is defined, not created.
src/server/sandbox.server.tsbuilds adefineSandboxfor each run:- the provider is
railwaySandbox(); - the workspace's
setupmakes sure theclaudeCLI is present; ANTHROPIC_API_KEYcomes fromcreateSecrets, so it's injected into the sandbox and never stored;- the lifecycle is
reuse: 'none'withdestroyOnComplete: true, so each run gets a fresh sandbox that's gone when the run ends.
- the provider is
chat()drives the run.src/server/runs.server.tscallschat({ adapter: claudeCodeText(model), outputSchema: RunReport, middleware: [withSandbox(sandbox), feed.middleware] }).withSandboxcreates the sandbox (in a few seconds on Railway) and hands it to the Claude Code harness, which runsclaudeinside it. Because ofoutputSchema, the agent finishes with a typed{ summary, outputs }report instead of prose to parse.- A middleware records the activity feed.
src/server/activity-feed.server.tsis adefineChatMiddleware:onChunkwrites messages and tool calls (with their output) to Postgres as they happen, and itssandbox.onFileCreate/onFileChangehooks collect the files the agent changed. The task page polls the feed while a run is active. - Runs end cleanly. A finished run moves the task to In Review with the agent's summary. Cancelling (with TanStack AI's
RUN_CANCEL_REASON) or failing puts it back in To do. Every run has a 15-minute limit. On a redeploy, the old server cancels its runs as it shuts down. If a server dies mid-run, the run's heartbeat goes stale; it's marked failed and its sandbox is destroyed.
The task is the chat() thread and each run is one execution of it. Runs are driven on the server, not streamed to a browser tab, so closing the tab doesn't stop the agent. TanStack AI also supports durable runs that survive a server restart by journaling inside the sandbox; Dispatch keeps runs short and simple instead.
The sandboxes are created in the app's own Railway environment, using RAILWAY_ENVIRONMENT_ID, which Railway sets on every deployment.
The template provisions two services:
| Service | Configuration |
|---|---|
| Dispatch-Web (this repo) | Build: Railpack (pnpm build)Start: node .output/server/index.mjsPre-deploy: node scripts/migrate.mjsHealth check: /api/healthA generated public domain |
| Postgres | Railway Postgres |
| Variable | Set by | Purpose |
|---|---|---|
DATABASE_URL |
Template: ${{Postgres.DATABASE_URL}} |
Postgres over the private network |
DISPATCH_PASSWORD |
Template: ${{secret(24)}} |
Access password for the app and the API |
SESSION_SECRET |
Template: ${{secret(32)}} |
Encrypts the session cookie |
ANTHROPIC_API_KEY |
You, on the deploy form | Claude Code runs on it inside each sandbox |
RAILWAY_TOKEN |
You, after deploy | A project token for this environment. Creates the sandboxes. (RAILWAY_API_TOKEN, an account or workspace token, also works but can reach everything you own.) |
RAILWAY_ENVIRONMENT_ID |
Railway | Where sandboxes are created |
DISPATCH_MODEL |
Optional | The model Claude Code uses (default sonnet) |
- Build. Railpack installs dependencies with pnpm and runs
pnpm build. Nitro writes a self-contained server to.output/. - Pre-deploy.
scripts/migrate.mjswaits for Postgres, applies the Drizzle migrations indrizzle/, and seeds the Default project on a fresh database. If it fails, the deploy stops and the previous version keeps serving. - Health check. The new deployment receives traffic only after
/api/healthcan reach the database.
.railway/railway.ts describes the same setup as infrastructure as code; apply it with railway config plan and railway config apply.
Everything except the landing page, /login and /api/health needs the access password:
- In the browser,
/loginexchanges it for an encrypted session cookie. Signed-in pages and server functions check it. - For the REST API, send it as a bearer token. The API doesn't accept the session cookie, so a cross-site form can't write with a signed-in visitor's cookie.
export AUTH="authorization: Bearer $DISPATCH_PASSWORD"
curl -s -H "$AUTH" $APP_URL/api/v1/projects
curl -s -X POST -H "$AUTH" -H 'content-type: application/json' \
$APP_URL/api/v1/projects/<projectId>/tasks -d '{"title": "Fetch the top HN stories"}'
curl -s -X POST -H "$AUTH" $APP_URL/api/v1/tasks/<taskId>/run # 202 { runId }
curl -s -H "$AUTH" $APP_URL/api/v1/tasks/<taskId> # task, feed, active run
curl -s -X DELETE -H "$AUTH" $APP_URL/api/v1/tasks/<taskId>/run # cancelThe UI and the API share one set of operations (src/server/ops.server.ts). Webhooks (Settings → Webhooks) POST task and run events to your URLs.
Without DISPATCH_PASSWORD, the app refuses access in production and runs open in local development. In production it also refuses to start sessions without a SESSION_SECRET of 32+ characters.
| Script | What it does |
|---|---|
pnpm dev |
Vite dev server on http://localhost:3000 |
pnpm build |
Production build to .output/ |
pnpm start |
Run the production build |
pnpm typecheck |
TypeScript checks |
pnpm db:up |
Start Postgres in Docker |
pnpm db:generate |
Generate a migration after editing src/server/schema.ts |
pnpm db:migrate |
Apply migrations and seed an empty database |
Runs need RAILWAY_TOKEN and RAILWAY_ENVIRONMENT_ID locally. Use the project token you created and the environment it belongs to (railway variables shows the id), and the sandboxes are created there.
.
├── .railway/railway.ts Railway infrastructure as code
├── drizzle/ generated SQL migrations (committed)
├── scripts/migrate.mjs pre-deploy: wait for Postgres, migrate, seed
└── src/
├── start.ts CSRF + REST API auth middleware
├── router.tsx router + per-request QueryClient
├── routes/ pages (/app/*), /login, /api/v1/*, /api/health
├── server/
│ ├── sandbox.server.ts defineSandbox: Railway provider, workspace, lifecycle
│ ├── runs.server.ts chat() + withSandbox + Claude Code, the typed run report
│ ├── activity-feed.server.ts chat middleware that records the activity feed
│ ├── tracker.functions.ts server functions for the UI
│ ├── auth.functions.ts sign-in server functions
│ ├── middleware.ts requireAuth function middleware
│ ├── ops.server.ts tracker operations shared by the UI and the API
│ ├── auth.server.ts password check and session cookie
│ ├── db.server.ts Postgres client (server-only)
│ └── schema.ts Drizzle schema
├── lib/
│ ├── queries.ts query options shared by loaders and components
│ └── seed-tasks.json the Default project's starter tasks
└── components/
- Give the agent a repo. Swap
source: { type: 'none' }insandbox.server.tsforgithubRepo({ repo: 'owner/name' })and Claude Code starts in a clone of it. - Use another harness. TanStack AI has Codex, OpenCode and other harness adapters. Change
claudeCodeText(...)inruns.server.tsand the matching secret insandbox.server.ts. - Limit what the agent can do. Add a
defineSandboxPolicyto the sandbox definition to deny commands. - Reach your other services. Pass
networkIsolation: 'PRIVATE'torailwaySandbox()and the sandbox joins the environment's private network. - Preview environments. A project token only works in the environment it was created for, so a PR environment needs its own
RAILWAY_TOKENbefore its runs work. - Scaling out. Runs are driven by the server that started them, and cancel only reaches runs on the same replica. Keep the
Dispatch-Webservice at one replica, or move run control to a queue.