Overview
All workloads run as containers on one Docker host and share one Docker network. A Caddy reverse proxy is the only workload that publishes a port on the host. The application starts a separate sandbox container for the agent, and the proxy routes browser traffic to it. A typical request follows these steps:- A user signs in to the application through the proxy and starts a conversation.
- The application starts a sandbox container, or reuses one of the user’s running sandboxes.
- The agent in the sandbox calls the LLM provider, runs tools such as shell commands and file edits, and works with the user’s Git repositories.
- The sandbox sends conversation events back to the application, and the browser connects to the sandbox through the proxy to stream them.
- The application stores conversation data in PostgreSQL and on its file store volume.
Workloads
proxy
Routes all incoming HTTP requests to the other workloads by path. It’s the only workload that publishes a host port (9043 by default).
- Image:
caddy - Volumes: None
app
Serves the web UI and REST API, handles sign-in, and manages conversations. It starts, pauses, and resumes sandbox containers through the host’s Docker socket, and runs database migrations on startup.- Image:
ghcr.io/openhands/enterprise-server - Connects to:
db,redis, sandboxes, and your Git providers - Volumes:
app-filestorefor conversation history and files, and the encryption key. Also mounts the host’s Docker socket.
app container runs as root so it can use the Docker socket. Only app and worker mount the
Docker socket. Access to the Docker socket gives control of the Docker host. We recommend running
the stack on a host dedicated to OpenHands, and limiting who can sign in to that host.
Users sign in with an email and password that the application manages. Passwords are hashed with
Argon2id. The stack doesn’t include Keycloak or require an external identity provider. The first
user becomes the Super Admin and invites other users. See the
setup guide.
The application encrypts stored secrets, such as LLM API keys and Git provider tokens, with
AES-256-GCM before it writes them to the database. On the first start, it generates a random
encryption key and saves it on the app-filestore volume. To supply your own key instead, set
JWT_SECRET in .env.
worker
Runs background jobs, such as sandbox lifecycle management and the license usage report. It uses the Docker socket for sandbox lifecycle management, and runs with the same image, settings, and privileges asapp.
- Image:
ghcr.io/openhands/enterprise-server - Connects to:
db,redis, and the Docker socket - Volumes:
app-filestore, shared withapp. Also mounts the host’s Docker socket.
automation-server
Runs automations: scheduled or event-driven agent runs. Each run executes in a sandbox, the same as an interactive conversation. It authenticates toapp
with a shared service key.
- Image:
ghcr.io/openhands/automation - Connects to:
db(in a separateautomationsdatabase) andapp - Volumes:
automation-datafor uploaded automation packages and run files
canvas-server
Serves the Agent Canvas frontend as static files at/canvas. It runs with its own telemetry
turned off.
- Image:
ghcr.io/openhands/agent-canvas - Connects to: None
- Volumes: None
db
Stores application and automation data in PostgreSQL.- Image:
postgres - Volumes:
db-data
redis
Holds short-lived keys, such as cache entries and coordination state. It’s an ephemeral cache, so it doesn’t have a persistent volume.- Image:
redis - Volumes: None
Sandboxes
Run the agent. The application creates one container per sandbox, namedoh-agent-server-<id>.
Sandboxes aren’t defined in the Compose file. The application starts each one with these settings:
- No added privileges: Sandboxes don’t run in privileged mode and get no added Linux capabilities or devices.
- No host access: Sandboxes don’t mount the Docker socket or any host directory, and publish no host ports. The workspace lives inside the container until the sandbox is deleted.
- Per-user ownership: Each sandbox belongs to one user. Conversations only reuse sandboxes that belong to the same user.
- Per-sandbox credential: Each sandbox gets a random session API key when it’s created. The agent server in the sandbox requires this key on every request, and the application stores only a hash of it.
sudo inside the container, so it can install packages for
the task it’s working on. This gives it root inside the container only.
Sandboxes join the Compose network so the proxy can route to them. They send events to app and
call automation-server through the proxy. Like the other workloads, they can also reach db and
redis by name, so set your own secrets before the first start.
Sandboxes have outbound network access, so the agent can reach the LLM provider, Git providers,
and package registries. When you run docker compose down, the application pauses running
sandboxes. It resumes a sandbox when a user reopens one of its conversations.
- Image:
ghcr.io/openhands/agent-server - Volumes: None
Secrets and credentials
Set these values in.env in the repository directory before the first start:
The Compose file sets a default for each of these, so the stack starts without them.
Each user adds their own LLM API key and Git provider credentials in the application, which stores
them encrypted.
External connections
The agent can also reach any other address the Docker host can reach, such as package registries
and websites, while it works on a task.

