Deploy and Host Craft Agents Server with Railway

Craft Agents is an open-source (Apache 2.0) agent workspace from Craft Docs, built on the Claude Agent SDK and Pi SDK. It connects agents to MCP servers, REST APIs and local tools, with sessions, skills, sources, permission modes and automations. This template runs the headless server, with a built-in web UI and a remote endpoint for the desktop app.

About Hosting Craft Agents Server

The headless server keeps agent sessions running independently of your laptop. The Craft Agents desktop app connects to it as a thin client, or you can use the built-in web UI in a browser. Session logic, tool execution and LLM calls all run on the server. Hosting it needs a persistent volume for workspaces, sessions, credentials and LLM connections, plus TLS for the WebSocket RPC channel. In this template, Railway's edge provides HTTPS/WSS, a volume holds state across redeploys, and the start command takes ownership of the volume and then drops to a non-root user, because the Claude Agent SDK won't run as root. Railway uses the /health endpoint for zero-surprise deploys.

Common Use Cases

Keep long-running agent sessions and automations alive 24/7, independent of your workstation
Reach the same workspaces and sessions from multiple machines through the desktop app or a browser
Run scheduled or event-driven automations (label changes, schedules, tool events) on always-on infrastructure
Give agents a stable cloud host for connecting to MCP servers, REST APIs and other services
Script against the server from CI/CD with the craft-cli WebSocket client

Dependencies for Craft Agents Server Hosting

Craft Agents server Docker image (Bun runtime, Node.js for helper workers)
Railway volume mounted at /home/craftagents/.craft-agent for persistent state
At least one LLM provider: Anthropic (API key or Claude Pro/Max), Google AI Studio, ChatGPT Plus/Pro, GitHub Copilot, OpenRouter, or any Anthropic/OpenAI-compatible endpoint

Deployment Dependencies

Source repository: https://github.com/craft-ai-agents/craft-agents-oss
Desktop app and documentation: https://agents.craft.do
Railway volumes: https://docs.railway.com/volumes
Railway healthchecks: https://docs.railway.com/deployments/healthchecks

Implementation Details

Port: the server listens on 9100 (CRAFT_RPC_PORT). Public networking targets 9100, and PORT=9100 tells Railway where to run the healthcheck.
TLS: handled at Railway's edge. The container serves plain WebSocket internally, so it starts with --allow-insecure-bind. Don't expose port 9100 through a TCP Proxy.
Browser connection: CRAFT_WEBUI_WS_URL=wss://${{RAILWAY_PUBLIC_DOMAIN}} points the web UI at the public WSS endpoint. Update it if you add a custom domain.
Server token: CRAFT_SERVER_TOKEN is generated for each deploy. Use it with the URL wss:// to connect the desktop app (add a remote workspace).
After deploying: log in to the web UI and add an LLM connection. API keys are stored on the volume, not in Railway variables.

Why Deploy Craft Agents Server on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Craft Agents Server on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.