OpenHands Enterprise — Backend Codebase
The source-available backend for OpenHands Enterprise, a self-hosted developer control center for coding agents and automations.
OpenHands Enterprise brings the power of autonomous coding agents to your organization with the governance, security, and compliance your enterprise demands.
OpenHands Enterprise allows you to run AI coding agents directly on your own servers or in your private cloud.
This is the source-available, commercially licensed backend codebase for OpenHands Enterprise. It provides a self-hosted developer control center for coding agents and automations, with additional enterprise features including authentication, billing, and integrations.
Warning
OpenHands Enterprise is commercially licensed under the Polyform Free Trial License. This is not an open source license. Usage is limited to 30 days per calendar year without a commercial license.
For commercial licensing and pricing inquiries, please contact us.
- Multi-use RBAC — Manage multiple users from a single platform
- Platform integrations — Invoke OpenHands directly from Slack, Jira, GitHub, GitLab, or Bitbucket
- Scalability — Run unlimited parallel agent conversations without local resource constraints
- Enterprise security — SAML authentication, RBAC, and centralized agent traces
- Usage Monitoring — Track and enforce budgets; monitor usage across all users
Choosing between OpenHands Agent Canvas and OpenHands Enterprise
The preferred method of installing OpenHands Enterprise is via our Replicated installer.
- Fist, read the Quick Start guide to understand system requirements for OpenHands Enterprise
- Then, register for a Trial account via the Replicated installer portal.
For a local evaluation or development, docker-compose.yml starts the whole stack (app, worker, automation service, Agent Canvas, PostgreSQL and a reverse proxy) from the released images. Docker with the Compose plugin is the only requirement.
./scripts/setup.shThe script runs docker compose up --wait, shows its output, and then prints the URL to open and the command to read the logs. It passes any options to docker compose, such as -f docker-compose.https.yml. You can also run docker compose up -d yourself.
Open http://localhost:9043; the first visit creates the admin account, then add an LLM under Settings. To decide who the admin is, set SUPER_ADMIN_EMAILS (shell or .env) to a comma-separated list of emails: only a listed email can create the admin account, and listed users get the Super Admin role whenever they sign in. Data is kept in named volumes, so it survives docker compose down; run docker compose down -v to reset everything. docker compose down, stop and restart app pause the running sandboxes, and a paused sandbox resumes when you open its conversation. If you change APP_PORT or access it through another hostname, set WEB_HOST, WEB_URL and AGENT_CANVAS_LOCK_TO_CLOUD to match (see the comments in docker-compose.yml).
For managed per-user usage and budgets, opt in to the LiteLLM Compose overlay. The guide covers existing-user migration and notes from an existing-account Okta sign-in test.
To test your local changes, build app and worker from your checkout instead of pulling the release image:
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --buildOr put COMPOSE_FILE=docker-compose.yml:docker-compose.build.yml in .env and run docker compose up -d --build.
To run other published versions, set any of these (shell or .env):
| Variable | Default | Example |
|---|---|---|
APP_IMAGE |
ghcr.io/openhands/enterprise-server:<release> |
ghcr.io/openhands/enterprise-server:main (latest main), :pr-<n>, :sha-<sha> |
AUTOMATION_IMAGE |
ghcr.io/openhands/automation:<version> |
ghcr.io/openhands/automation:main |
AGENT_CANVAS_IMAGE |
ghcr.io/openhands/agent-canvas:<version> |
ghcr.io/openhands/agent-canvas:main |
For moving tags such as main, add --pull always to docker compose up. After upgrading from an older checkout, run docker compose down first so the proxy picks up the new routing.
The stack runs on Podman with no changes to docker-compose.yml. Use podman compose in place of docker compose, and set DOCKER_SOCKET (shell or .env) to the Podman socket for your setup:
| Podman setup | DOCKER_SOCKET |
Run |
|---|---|---|
macOS (podman machine) |
Leave it unset | podman compose up -d |
| Linux, rootless | $XDG_RUNTIME_DIR/podman/podman.sock, usually /run/user/<uid>/podman/podman.sock |
podman compose up -d |
| Linux, rootful | /run/podman/podman.sock |
sudo podman compose up -d |
For example, with rootless Podman on Linux:
echo "DOCKER_SOCKET=$XDG_RUNTIME_DIR/podman/podman.sock" >> .env
podman compose up -dpodman compose runs Docker Compose against the Podman API socket, so both must be set up. On macOS, we recommend giving the Podman machine 8 GB of memory.
If you need help from OpenHands support, run this from the repository root and send us the archive it creates:
./scripts/support-bundle.shIt collects the logs of every container in the stack, including the sandboxes, and the state of the stack. If you start the stack with -f options, pass the same options to the script. Keys, secrets and passwords in the compose config are masked. Docker deletes the logs of a container when it removes the container, for example on docker compose down or an upgrade, so run the script before you do either.
- Documentation: https://docs.openhands.dev/enterprise
- Website: https://www.openhands.dev/enterprise
Important
Contributions from outside, non-OpenHands maintainers are currently not accepted.
If you are interested in collaborating with us or contributing to OpenHands Enterprise, please reach out to discuss a Contributor License Agreement (CLA). You can contact us through our website or Slack community.
See the Development guide for setup instructions, the repository layout, and development workflows. Python dependencies are managed with uv.