---
title: "Deploy Sandbox"
description: "All-in-one AI agent sandbox with browser, shell, MCP, and VSCode."
category: "AI/ML"
url: https://railway.com/deploy/sandbox-1
---

# Deploy Sandbox

All-in-one AI agent sandbox with browser, shell, MCP, and VSCode.

**[Deploy Sandbox on Railway](https://railway.com/template/sandbox-1)**

- **Creator:** Muhammad Bilal
- **Category:** AI/ML
- **Total deploys:** 2

## Template content

### Sandbox

- **Image:** ghcr.io/agent-infra/sandbox:latest
- **Public domain:** Yes

## Documentation

# 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

* [Sandbox GitHub Repository](https://github.com/agent-infra/sandbox?utm_source=chatgpt.com)
* [Sandbox Website](https://sandbox.agent-infra.com/?utm_source=chatgpt.com)
* [Sandbox API Documentation](https://sandbox.agent-infra.com/api?utm_source=chatgpt.com)
* [Sandbox Cloud Deployment Guide](https://sandbox.agent-infra.com/guide/start/cloud-deployment?utm_source=chatgpt.com)
* [Sandbox Docker Image](https://ghcr.io/agent-infra/sandbox?utm_source=chatgpt.com)

### Implementation Details

## Docker

Deploy the published Sandbox Docker image:

```docker
ghcr.io/agent-infra/sandbox:latest
```

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

```env
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:

```text
/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:

```env
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:

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

The application must use the same path:

```env
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:

```text
/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:

```text
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:

1. Open the Sandbox service.
2. Go to **Settings → Networking**.
3. Select **Generate Domain**.
4. Open the generated HTTPS domain.

Useful endpoints include:

**API Documentation**

```text
https://YOUR_RAILWAY_DOMAIN/v1/docs
```

**VNC Browser**

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

**VSCode Server**

```text
https://YOUR_RAILWAY_DOMAIN/code-server/
```

**MCP Services**

```text
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:

```text
/mcp
```

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

### Troubleshooting

**Application is inaccessible**

Verify:

```env
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:

```text
/home/gem/workspace
```

and that:

```env
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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/sandbox-1