Deploy and Host OpenCode on Railway

OpenCode is an open-source AI coding agent. This template runs its 2.x server: an HTTP API plus a web UI that an AI agent (or you) can use to start coding sessions, run shell commands, edit files and commit to git on a Railway volume. It deploys with no manual step, the login is generated for you, and a free model answers without any provider key.

About Hosting OpenCode

This template runs one container: the official ghcr.io/anomalyco/opencode image (OpenCode 2.x, pinned by digest) wrapped for Railway (bon5co/opencode-2-railway). The upstream image is a bare Alpine binary with no git, bash or curl; the wrapper adds bash, git, curl, jq, ssh, ripgrep, python3, pip, uv, node and npm so a session can clone, run and commit.

HTTP Basic authentication is on from the first boot. The username is always opencode (OpenCode 2 ignores OPENCODE_SERVER_USERNAME) and the password is the OPENCODE_SERVER_PASSWORD variable, a 32-character alphanumeric secret generated at deploy time and stable across redeploys. Every API route and /openapi.json answer 401 without credentials. The web UI shell at / is static and public (it is also the healthcheck); on its own it shows only a "Connect to a server" form and no data. A human signs in with a one-time pairing link (see the contract) or with the "Use password" option. The server refuses to start when the password is empty.

Everything that must survive a redeploy lives on the volume at /data: sessions, provider credentials and config under /data/home, and the default workspace at /data/workspace. The boot script logs the uid and whether /data is writable, then prints the contract below to the deploy log on every boot.

The provider opencode offers free models (for example big-pickle) that answer with no API key; they call OpenCode's hosted inference, so the container needs outbound internet. To use your own model, store a provider key through the API after deploy.

Agent contract

Public URL: https:// (variable OPENCODE_URL)
Private URL: http://opencode.railway.internal:8080 (variable OPENCODE_PRIVATE_URL)
Credentials: username opencode (fixed), password in variable OPENCODE_SERVER_PASSWORD
Auth: HTTP Basic (curl -u "opencode:$OPENCODE_SERVER_PASSWORD")
Health: GET / returns 200 without credentials; /api/* and /openapi.json return 401 without them
API reference: GET /openapi.json; create a session with POST /api/session, prompt with POST /api/session/{id}/prompt, read replies from GET /api/session/{id}/message (newest first, an idle entry marks the end of the turn)
Human sign-in link: POST /api/pair (with credentials) returns {"code":...} valid 5 minutes, single use; open $OPENCODE_URL/auth/connect/<code> in a browser to land in the web UI signed in
Add a provider key: POST /api/integration//connect/key with {"key":"..."}

AUTH="opencode:$OPENCODE_SERVER_PASSWORD"
SID=$(curl -sf -u "$AUTH" -X POST "$OPENCODE_URL/api/session" \
  -H 'content-type: application/json' -d '{}' | jq -r .data.id)
curl -sf -u "$AUTH" -X POST "$OPENCODE_URL/api/session/$SID/prompt" \
  -H 'content-type: application/json' -d '{"text":"Reply with exactly: PONG"}' &gt;/dev/null
for i in $(seq 40); do
  R=$(curl -sf -u "$AUTH" "$OPENCODE_URL/api/session/$SID/message")
  [ "$(echo "$R" | jq -r '.data[0].type')" = idle ] &amp;&amp; break; sleep 2
done
echo "$R" | jq -r '[.data[] | select(.type=="assistant")][0].content[] | select(.type=="text") | .text'

Notes: GET /api/credential returns stored provider keys in clear text to an authenticated client, so treat the password as the root secret. GET /auth/connect/{code} redeems a single-use pairing code without credentials; codes come from POST /api/pair, which needs the password. The default build agent allows all tools; only reads of .env files ask for approval (answer at POST /api/session/{id}/permission/{requestID}/reply). Full guide: AGENTS.md.

Why Deploy OpenCode 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 OpenCode 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.

No manual step — the login is generated and the volume is preconfigured; the deploy form can be submitted empty.
Secure by default — a 32-character generated password, 401 on every API route without it, and no start without one.
Sessions survive redeploys — history, credentials and the git workspace sit on the /data volume.
Works with no provider key — a free hosted model answers on the first request.

Common Use Cases

Remote coding agent for AI agents — let an orchestrating agent start and read OpenCode sessions over HTTP.
Always-on coding sandbox — run builds, scripts and git operations from your phone or browser against a persistent workspace.
Shared agent server — one authenticated OpenCode endpoint for a team, reachable over the private network from other services.

Dependencies for OpenCode Hosting

A volume mounted at /data (included in this template).

Deployment Dependencies

OpenCode — the upstream coding agent (docs)
bon5co/opencode-2-railway — wrapper image this template deploys