Skip to main content
This guide walks through deploying the Hono API server to Railway with Docker, including Redis for persistent state management.

​
Prerequisites

  • A Railway account
  • The ouroborai monorepo cloned locally
  • An Arbitrum RPC URL (Alchemy, Infura, or public)
  • An Anthropic API key for the agent runner
  • A funded wallet private key (ETH for gas, USDC for x402 settlement)

​
Deployment

1

Create a Railway project

Log into Railway and create a new project. Select Deploy from GitHub repo and connect the ouroborai repository. Railway detects the Dockerfile in the project root automatically.If you prefer manual deployment, install the Railway CLI:
2

Configure environment variables

In the Railway dashboard, navigate to your service and open the Variables tab. Add the following required variables:
PRIVATE_KEY controls the agent’s on-chain wallet. Use a dedicated hot wallet with limited funds — never your primary wallet.
Add optional variables for full functionality:
3

Provision Redis (optional but recommended)

Redis enables persistent job queues, conversation threads, and x402 nonce tracking across server restarts. Without it, these stores fall back to in-memory and reset on each deploy.In Railway, click New Service and select Redis. Railway automatically injects REDIS_URL into your service environment.The API server uses these Redis key prefixes:
4

Review the Dockerfile

The project ships a multi-stage Dockerfile that builds all workspace packages and produces a minimal production image:
Build order matters because workspace packages have dependencies: sdk builds first, then adapters, skills, timeboost, and smart-account, and finally the api app.
@zerodev/*, permissionless, and tslib must be marked as external in the Bun build configuration to avoid bundling issues.
5

Deploy

Push to your connected branch (or trigger a deploy from the CLI):
Railway builds the Docker image, starts the container, and assigns a public URL.
6

Verify the deployment

Hit the health endpoint to confirm the server is running:
Expected response:
Also check the root endpoint for version and chain info:
7

Test the agent

Submit a prompt to verify end-to-end functionality:
You should receive a 202 response with a jobId and threadId. Poll the job status endpoint to retrieve the agent’s answer:

​
Troubleshooting

Railway needs the server to bind to 0.0.0.0, not localhost. The ouroborai API server already binds to 0.0.0.0 by default. Ensure the PORT environment variable matches what Railway expects (it injects this automatically).
If using Railway’s Redis add-on, ensure the REDIS_URL variable is linked to the correct service. The API server falls back to in-memory stores gracefully if Redis is unreachable, so the server will start even if Redis is misconfigured.
Verify that PAY_TO_ADDRESS is a valid Arbitrum One address and that the calling wallet has sufficient USDC. Set SKIP_PAYMENT=true for staging environments where you want to bypass payment verification.