How do I run OpenHands locally (open source) with Docker and keep the agent sandboxed?

Running OpenHands locally with Docker is the fastest way to get a real cloud-coding agent platform into your own environment while keeping every action isolated in a sandbox you control.

Quick Answer:
To run OpenHands locally with Docker and keep the agent sandboxed, you deploy the open source stack into a containerized runtime (Docker or Docker Compose), then configure agents to execute only inside that sandboxed environment with scoped credentials and mounted volumes. This lets you delegate real coding tasks while preserving strict isolation, auditability, and a clear blast radius.

Why This Matters

If agents can touch your repos, they’re part of your production surface. Running OpenHands locally in Docker gives you a secure, auditable runtime on your own hardware or VPC, instead of a black-box SaaS. You can keep source code, secrets, and build artifacts inside containers you control, while still getting fully autonomous code changes, tests, and upgrades.

Key Benefits:

• Safe autonomy: Agents run in containerized sandboxes with a clear blast radius and scoped credentials.
• Local control: Everything lives in your environment—no source code or runtime state needs to leave your machine or VPC.
• Deterministic operations: You can inspect what the agent did, reproduce runs, and re-run tasks systematically when you change configs or models.

Core Concepts & Key Points

Concept	Definition	Why it's important
Containerized sandbox runtime	OpenHands agents run in isolated Docker containers (or Kubernetes pods) with controlled file-system access, network, and credentials.	Prevents agents from breaking out of their scope and gives you a defined blast radius for every run.
Local, self-hosted deployment	Running the open source OpenHands stack on your own machine, server, or private cloud via Docker.	Keeps code, logs, and artifacts inside your environment for compliance, privacy, and governance.
Model-agnostic configuration	Plugging your own LLM providers (Anthropic, OpenAI, Bedrock, etc.) into OpenHands without being tied to a single vendor.	Lets you optimize for cost, latency, or capability and switch providers without redeploying the platform.

How It Works (Step-by-Step)

At a high level, you’ll: (1) prepare your local environment, (2) launch OpenHands in Docker, and (3) configure agent sandboxes and access controls. Once that’s in place, you can delegate real coding tasks from your terminal, Web GUI, or SDK while keeping everything isolated.

1. Prepare your local environment

1. Install Docker (and optionally Docker Compose)

   • Install Docker Desktop (macOS/Windows) or docker engine (Linux).
   • Ensure docker ps runs without errors.
   • If using Docker Compose, confirm docker compose version works.

2. Choose where the agent will operate

   • Decide which repos the agent should access. A common pattern:
     • /workspace/openhands-config – config, secrets, and compose files.
     • /workspace/repos/... – repositories the agent will work on.
   • Plan how these will be mounted into containers (read/write vs read-only).

3. Set up LLM provider credentials (BYOK)

   • Export provider keys as env vars, e.g.:
     • ANTHROPIC_API_KEY, OPENAI_API_KEY, or your preferred LLM.
   • Store them in an .env or Docker secrets file; avoid baking secrets into images.

2. Launch OpenHands locally with Docker

The exact repo and compose files may evolve, but the pattern stays consistent: one “controller”/API container, plus one or more “agent” containers that handle execution.

1. Clone the OpenHands repo

   git clone https://github.com/All-Hands-AI/OpenHands.git
   cd OpenHands
   

2. Review Docker / Compose configuration
   Look for a docker-compose.yml or similar deployment manifest. Typical services:

   • openhands-api or server: orchestrates agents, exposes HTTP API / Web GUI.
   • openhands-agent or worker: sandbox container used to run agent steps (git, tests, linters, etc.).
   • Optional: database / message broker if used by your version.

3. Create an environment file Example .env:

   OPENHANDS_ENV=local
   LLM_PROVIDER=anthropic           # or openai, bedrock, etc.
   ANTHROPIC_API_KEY=your_key_here  # or OPENAI_API_KEY=...
   # Agent filesystem root inside the container
   WORKSPACE_DIR=/workspace
   

4. Start the stack

   docker compose up -d
   

   This:

   • Starts the OpenHands controller + Web GUI.
   • Spins up one or more agent containers.
   • Mounts your local repos into the agent’s /workspace (or equivalent).

5. Access the Web GUI or CLI

   • Web GUI: open http://localhost:<port> (commonly 3000/8080 depending on config).
   • CLI/Terminal mode: use the provided openhands CLI or curl/SDK to submit tasks.

3. Keep the agent fully sandboxed

The sandbox is defined by your Docker configuration and OpenHands’ runtime design: every agent runs in a containerized environment you control, with explicit mounts and credentials.

1. Mount only what the agent needs In docker-compose.yml, you might see a service like:

   services:
     openhands-agent:
       image: openhands/agent:latest
       volumes:
         - /workspace/repos/my-service:/workspace/my-service:rw
         - /workspace/repos/shared-libs:/workspace/shared-libs:ro
       environment:
         - WORKSPACE_DIR=/workspace
   

   Good practices:

   • Mount specific repos, not the entire host filesystem.
   • Use :ro (read-only) mounts for reference code or config that should never be mutated.
   • Keep secrets mounted as files or environment variables, not as plain-text inside the image.

2. Control network access

   • Default: keep agents on an internal Docker network with no direct exposure to the internet unless your tasks truly require it (e.g., fetching dependencies).
   • Use Docker network policies or firewall rules to:
     • Allow outbound-only to package registries if needed.
     • Block arbitrary outbound connections if your compliance policy requires it.

3. Scope credentials and tokens

   • Give the agent a dedicated Git token scoped to a specific org or repo, not a global user token.
   • Use environment variables in the agent container only:

     environment:
       - GITHUB_TOKEN=${GITHUB_TOKEN_AGENT}
     

   • Use read-only cloud credentials if you want the agent to inspect but not mutate external systems.

4. Leverage OpenHands’ visibility and auditability Because OpenHands is open source and transparent by design:

   • You can inspect the agent image and entrypoint to confirm exactly what runs.
   • Every run can be logged and replayed:
     • Store logs and artifacts on mounted volumes.
     • Configure the Web GUI or API to show per-run traces and diffs.

5. Run headlessly in CI with the same sandbox

   • Use the same Docker configuration in your CI pipeline so:
     • A run you test locally is identical to what runs in CI (“same agent, same runtime”).
     • You can schedule repo-wide maintenance (dependency upgrades, vulnerability patching) with the same isolated execution boundary.

Common Mistakes to Avoid

• Letting agents run with broad host access:
  Avoid mounting / or home directories into the container or giving agents full root access to the host. Keep mounts tight and specific to the workspace directories.

• Mixing runtime and control plane concerns:
  Don’t run the agent directly on your host with shared credentials and file system. Always route execution through Docker (or Kubernetes) so the blast radius is controlled and auditable.

Real-World Example

A regulated fintech team wants to auto-fix failing tests and dependency vulnerabilities on a monorepo, but they cannot let third-party SaaS directly touch their code. They deploy OpenHands in a private Kubernetes cluster, but first validate it locally with Docker on a developer workstation:

• They clone their monorepo into /workspace/repos/core-platform.
• They mount that repo into the openhands-agent container as /workspace/core-platform:rw.
• Git credentials are scoped to a bot account that can only push to specific branches.
• Network egress from the agent is restricted to GitHub, the internal artifact registry, and their LLM provider.
• The Web GUI runs only inside the company VPN, and every run’s logs, diffs, and PR links are stored on a local volume.

The result: agents autonomously fix 80–90% of failing tests and straightforward vulnerabilities, but all work happens in a transparent, replayable sandbox. Security can inspect container images, logs, and diffs; engineering can re-run tasks deterministically when configs or models change.

Pro Tip:
Treat the agent containers like build servers: version their images, keep their Dockerfiles in source control, and require changes to the runtime (mounts, env, base images) to go through the same code review process as application code.

Summary

Running OpenHands locally with Docker gives you a cloud-coding agent platform that behaves like real infrastructure, not a black-box chat app. You deploy the open source stack into a containerized sandbox, mount only the repos and credentials you intend the agent to touch, and control network and access policies at the Docker level. Because the platform is model-agnostic and open source, you keep full visibility into every agent, every artifact, and every run—so autonomy never comes at the cost of control.

Next Step

Get Started