Deploy and Host Sandbox on Railway

Sandbox is an all-in-one environment for AI agents that combines browser automation, shell execution, file operations, MCP services, Jupyter, and VSCode Server in a single Docker container. It provides a shared workspace and unified APIs, allowing agents to browse websites, execute code, manipulate files, use development tools, and interact with MCP services from one environment.

About Hosting Sandbox

Hosting Sandbox on Railway requires a single Docker-based service using the ghcr.io/agent-infra/sandbox:latest image. The application listens on port 8080 and binds to 0.0.0.0, allowing Railway to route public HTTP traffic to the container.

A Railway Volume is required at /home/gem/workspace to persist files created, downloaded, or modified by agents. The shared workspace is accessible to the browser, shell, file operations, Jupyter, and VSCode Server. Sandbox also supports API-key authentication through SANDBOX_API_KEY, which protects its API and associated services.

Railway provides the public networking and HTTPS layer, so a separate reverse proxy or TLS configuration is not required. The Sandbox API, browser interface, VSCode Server, and MCP services are exposed through the same port.

Common Use Cases

AI Agent Sandbox: Give autonomous agents browser, shell, file, code execution, and MCP capabilities inside a persistent isolated environment.
Browser Automation: Allow agents to navigate websites, interact with pages, take screenshots, download files, and combine browser activity with shell and file operations.
AI Development Environment: Provide agents with VSCode Server, Jupyter, terminal access, persistent files, and MCP tools for building and testing software.

Dependencies for Sandbox Hosting

Sandbox Docker Image: ghcr.io/agent-infra/sandbox:latest
Railway Volume: Required at /home/gem/workspace for persistent workspace data.
Sandbox API Key: Required for the recommended authenticated deployment.
Railway Public Networking: Required to expose the Sandbox HTTP API and web interfaces on port 8080.

Deployment Dependencies

Implementation Details

Docker

Deploy the published Sandbox Docker image:

ghcr.io/agent-infra/sandbox:latest

The application listens on port 8080 and binds to all interfaces:

PORT=8080
HOST=0.0.0.0

No custom build command is required because Sandbox is distributed as a prebuilt Docker image.

The upstream deployment uses an unconfined seccomp profile for the sandbox runtime. Sandbox documentation specifies seccomp=unconfined for its Docker deployment, so the Railway service should preserve the required runtime security configuration where supported.

Public Networking

Setting	Value
Proxy Type	HTTP Proxy
Target Port	`8080`
Application Port	`8080`
Bind Address	`0.0.0.0`
HTTPS	Railway-managed

After deployment, open:

Sandbox → Settings → Networking → Generate Domain

The generated Railway domain provides access to the Sandbox HTTP services.

The same port exposes the documented interfaces:

/v1/docs
/vnc/index.html?autoconnect=true
/code-server/
/mcp

The API documentation is available through /v1/docs, while the VNC browser, VSCode Server, and MCP services are also served through port 8080.

Environment Variables

Variable	Required	Description
`PORT`	Yes	Internal HTTP server port. Set to `8080`.
`HOST`	Yes	Bind address. Set to `0.0.0.0`.
`SANDBOX_API_KEY`	Yes	Authentication key for Sandbox services.
`WORKSPACE`	Yes	Persistent agent workspace directory.
`TZ`	Yes	Container timezone.

Configure the Railway Raw Editor with:

PORT=8080
HOST=0.0.0.0
SANDBOX_API_KEY=${{secret(32)}}
WORKSPACE=/home/gem/workspace
TZ=UTC

SANDBOX_API_KEY should be kept secret. Sandbox supports API-key authentication through the X-AIO-API-Key header, Bearer authentication, and the api_key query parameter.

Persistent Storage

A Railway Volume is required because the Sandbox workspace contains persistent files used by agents and development tools.

Open:

Sandbox Service → Settings → Volumes → Add Volume

Configure:

Volume Name: workspace
Mount Path: /home/gem/workspace

The application must use the same path:

WORKSPACE=/home/gem/workspace

The shared workspace allows files downloaded through browser automation to be accessed by shell and file operations, while Jupyter and development tools can work with the same files.

Without the volume, workspace data stored inside the container may be lost when the service is recreated or redeployed.

Database

Sandbox does not require a separate PostgreSQL, MySQL, Redis, or other database service for the documented deployment.

The persistent data requirement is the workspace volume:

/home/gem/workspace

No additional database service should be added to the Railway template unless a future Sandbox release documents one as required.

Build & Start

No custom build or start commands are required.

Railway should deploy:

ghcr.io/agent-infra/sandbox:latest

using the Docker image's default startup configuration.

Configure the service to expose port 8080.

Do not use Docker Compose commands such as docker compose up as the Railway start command.

Accessing the Application

After deployment:

Open the Sandbox service.
Go to Settings → Networking.
Select Generate Domain.
Open the generated HTTPS domain.

Useful endpoints include:

API Documentation

https://YOUR_RAILWAY_DOMAIN/v1/docs

VNC Browser

https://YOUR_RAILWAY_DOMAIN/vnc/index.html?autoconnect=true

VSCode Server

https://YOUR_RAILWAY_DOMAIN/code-server/

MCP Services

https://YOUR_RAILWAY_DOMAIN/mcp

All of these interfaces are provided through the Sandbox service on port 8080.

API Authentication

With SANDBOX_API_KEY enabled, clients must authenticate when accessing protected Sandbox services.

The Sandbox SDK can be configured to connect to the generated Railway domain. Python, TypeScript/JavaScript, and Go SDKs are available for integrating Sandbox into AI-agent applications.

MCP Integration

Sandbox includes MCP services for:

Browser automation
File operations
Shell execution
Markitdown document processing

The MCP interface is available under:

/mcp

This allows compatible AI agents and MCP clients to use Sandbox as a unified execution environment.

Troubleshooting

Application is inaccessible

Verify:

PORT=8080
HOST=0.0.0.0

and ensure Railway's HTTP proxy targets port 8080.

Workspace files disappear

Verify that a Railway Volume is mounted at:

/home/gem/workspace

and that:

WORKSPACE=/home/gem/workspace

matches the mount path.

API authentication fails

Verify that the client is using the configured SANDBOX_API_KEY and one of the supported authentication methods.

Browser or sandbox execution fails

Sandbox's upstream Docker configuration uses an unconfined seccomp profile. Verify that the Railway runtime configuration provides the required security settings for the container.

No database is available

No database is required by the documented Sandbox deployment. Persistent workspace data is stored on the Railway Volume.

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