railway-sandbox-mcp

A small MCP bridge that lets ChatGPT drive Railway Sandboxes as an isolated development/execution environment.

Architecture

Both long-running Railway services are deployed from this GitHub repository through Railway's GitHub integration:

Railway service	GitHub branch	Railway root directory	Config-as-code file	Purpose
sandbox-mcp	main	/	/railway.json	Node MCP server backed by the Railway Sandbox SDK
tunnel-client	main	/tunnel-client	/tunnel-client/railway.json	OpenAI Secure MCP Tunnel client

The tunnel-client Dockerfile inherits the official ghcr.io/openai/tunnel-client:latest image and only wraps its entrypoint so the upstream health/readiness server binds to Railway's injected PORT. Railway owns the deployment lifecycle while OpenAI remains the upstream image provider.

ChatGPT
  |
  v
OpenAI Secure MCP Tunnel
  ^
  | outbound HTTPS
  |
tunnel-client (Railway)
  |
  | Railway private network
  v
sandbox-mcp:8080/mcp (Railway)
  |
  v
Railway Sandbox SDK
  |
  v
Ephemeral isolated Linux sandboxes with outbound Internet

Neither Railway service needs a public domain.

Config as code

Deployment behavior is committed to this repository:

• /railway.json defines the MCP service builder, watch paths, start command, health check, and restart policy.
• /tunnel-client/railway.json defines the tunnel-client Docker build, watch paths, readiness check, and restart policy.
• /tunnel-client/Dockerfile selects the official OpenAI tunnel-client image and adapts its health listener to Railway's injected PORT.
• /.github/workflows/ci.yml validates the Node service and Railway config files and builds the tunnel-client image on pushes and pull requests.

Railway configuration committed in code overrides equivalent dashboard build/deploy values for each deployment.

One-time Railway service wiring

Source association, trigger branch, and the custom config-file path are Railway service metadata rather than fields inside railway.json, so configure these once in Railway:

sandbox-mcp

• Source repository: erwinkn/railway-sandbox-mcp
• Branch: main
• Root directory: /
• Config file path: /railway.json
• GitHub autodeploy: enabled
• Wait for CI: enabled

tunnel-client

• Source repository: erwinkn/railway-sandbox-mcp
• Branch: main
• Root directory: /tunnel-client
• Config file path: /tunnel-client/railway.json
• GitHub autodeploy: enabled
• Wait for CI: enabled
• No custom start command; inherit the repository Dockerfile entrypoint

The service-specific watch paths mean MCP-only changes do not rebuild the tunnel client, and tunnel-only changes do not rebuild the MCP server.

Required environment variables

sandbox-mcp

• RAILWAY_API_TOKEN: Railway API token with access to the environment where Sandboxes are enabled.
• RAILWAY_ENVIRONMENT_ID: injected automatically by Railway.

tunnel-client

• MCP_SERVER_URL=http://sandbox-mcp.railway.internal:8080/mcp
• CONTROL_PLANE_TUNNEL_ID=tunnel_...
• CONTROL_PLANE_API_KEY=...: restricted OpenAI runtime key with Tunnel Read + Use permissions.
• LOG_LEVEL=info
• LOG_FORMAT=json

tunnel-client exposes /healthz, /readyz, and /metrics on Railway's injected port. Railway uses /readyz as the deployment health check, so a successful tunnel-client deployment verifies both tunnel startup and downstream MCP readiness.

Deployment flow

A push to main runs GitHub Actions. With Railway's Wait for CI enabled, Railway waits for CI to pass, then autodeploys only the services whose watch patterns match the changed files.

MCP tools

• sandbox_create
• sandbox_list
• sandbox_get
• sandbox_exec
• sandbox_read_file
• sandbox_list_files
• sandbox_write_file
• sandbox_write_files
• sandbox_checkpoint
• sandbox_destroy