---
title: "Deploy Open Hands (OpenHands)"
description: "Open Hands coding agent (OpenHands). Deployment with persistent data."
category: "AI/ML"
url: https://railway.com/deploy/openhands
---

# Deploy Open Hands (OpenHands)

Open Hands coding agent (OpenHands). Deployment with persistent data.

**[Deploy Open Hands (OpenHands) on Railway](https://railway.com/template/openhands)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/openhands/manifest.json

- **Creator:** Xav's Projects
- **Category:** AI/ML
- **Total deploys:** 54

## Template content

### OpenHands https://raw.githubusercontent.com/OpenHands/docs/main/openhands/static/img/logo.png

- **Source:** https://github.com/XavTo/OpenHands-Fork
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# Deploy and Host OpenHands on Railway

OpenHands (Open Hands) is an open-source coding agent with a web interface and terminal tools.

## About Hosting OpenHands

This fork runs OpenHands with a local process runtime inside one Railway service.
Docker-in-Docker and a Docker socket are not required. The instance is intended
for one trusted owner: agent actions can access files and environment variables
inside this container. It is not a multi-tenant sandbox service.

## Access and readiness

Copy `OPENHANDS_BASIC_AUTH_USER` and `OPENHANDS_BASIC_AUTH_PASSWORD` from Railway
variables to sign in. Basic Auth covers both the web app and the outer Socket.IO
transport. Configure Railway's healthcheck as `/health`, with the exact exemption
`OPENHANDS_BASIC_AUTH_EXEMPT_PATHS=/health`; application routes stay protected.

V1 agent callbacks use their own `X-Session-API-Key` validation. The two POST
callback routes delegate to that validation instead of requiring the browser's
Basic Auth credentials. A missing or invalid session key still fails.

The built-in MCP client and provider-secret lookups authenticate their requests to this protected app. The local process runtime receives its absolute workspace path under the persistent volume, so the agent can find the same files as its terminal.

## Models

Select a provider and model in OpenHands settings, then enter the provider API
key. A running web UI does not prove that model credentials or a coding task work.
Provider API usage is billed separately by that provider.

## Persistence and local networking

Mount the Railway volume at `/.openhands` and keep `OH_PERSISTENCE_DIR` and
`FILE_STORE_PATH` pointed there. V1 sandbox directories and conversation data use
this persistent storage. For legacy local-runtime sessions, set
`LOCAL_WORKSPACE_BASE=/.openhands/workspace` and
`SANDBOX_LOCAL_RUNTIME_URL=http://127.0.0.1`: the action process runs in the same
container, not at `host.docker.internal`.

The entrypoint and shell command use `exec`, allowing Railway's SIGTERM to reach
the server for its normal shutdown. Give it a 30-second deployment draining
period. Do not rotate the instance secret when replacing containers.

The initial validation reached about 0.66 GB of memory before a real model task.
Allow additional capacity for agent processes and builds; this observation is not
a load-test result. A 512 MB limit can be insufficient.


## Common Use Cases

- Ask an AI agent to write and execute code.
- Fix bugs and inspect a repository in a persistent workspace.
- Keep coding conversations and settings across container replacements.

## Dependencies for OpenHands Hosting

One Dockerfile service, a Railway volume mounted at `/.openhands`, and an LLM provider API key configured in OpenHands settings. Provider API usage is billed separately from Railway.

### Deployment Dependencies

- [OpenHands source](https://github.com/XavTo/OpenHands-Fork)
- [OpenHands documentation](https://docs.openhands.dev/)
- [Railway healthchecks](https://docs.railway.com/deployments/healthchecks)

## Why Deploy OpenHands on Railway?

Host the interface and its local process runtime in one project, with HTTPS, generated access credentials and persistent storage.


## 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/openhands