How to Deploy an OpenHands Sandbox in 2026 to Isolate AI Coding Tasks from a macOS Host?
Use the officially supported OpenHands container sandbox as the default for AI coding tasks, and mount only the project directory the task needs. This fits tasks that edit code, run tests, or inspect an untrusted repository; it does not make the container an absolute security boundary, and it does not justify granting access to the Docker socket or host credentials by default.
This guide is for developers deploying OpenHands on a Mac for the first time, engineering teams separating several codebases, and technical leads planning a boundary between an Agent and macOS-native build tools.
Choose the execution backend before installing
OpenHands’ execution backend determines where an Agent’s commands run and what files those commands can reach. The distinction matters more than the choice of interface: running the application locally is not the same trust boundary as having a separate container execute code. Check the current OpenHands local setup documentation alongside its sandbox overview before following an installation recipe.
For code changes and test commands, prefer the official container sandbox path when the current documentation supports the intended setup. Avoid running an Agent directly against a broad host filesystem. An untrusted repository may include scripts that execute during tests or other project operations, and an Agent may be asked to run them. The container path narrows the execution environment, but any files deliberately mounted into it remain part of the task’s reachable surface.
Can OpenHands run in a Docker sandbox on macOS? OpenHands documents Docker as a sandbox option. Follow the current installation and configuration path for the OpenHands release in use; do not assume that every historical Docker Runtime instruction applies to every current setup. The official Docker sandbox guide describes the supported Docker approach, while the older V0 Docker Runtime document is explicitly a V0 path. Treat that distinction as a deployment requirement, not a documentation detail.
A practical backend decision looks like this:
- If the task edits a project, runs its tests, or executes repository scripts, use the documented container sandbox and restrict its mount to that project.
- If the task only needs to inspect reference material, use a read-only mount for those materials when the selected setup supports it.
- If the task needs Xcode or another macOS-native toolchain, keep the Agent’s container permissions separate from the native build environment. Do not assume a Docker container supplies macOS or its native toolchain.
- If the official setup requires broader host access or Docker management privileges, stop and assess whether the task truly needs them. If it does not, choose a narrower workflow instead.
Set the host and workspace boundary
Prepare a dedicated project directory before starting OpenHands. It should contain only the files required for the task. Do not mount a home directory, a general development folder, or a directory containing unrelated repositories simply because that is more convenient.
This is the answer to a common access-boundary question: Which files can OpenHands reach on the Mac? In practice, the Agent can work with the files made available through its configured execution environment and mounts. A project directory mounted for editing is not protected from changes merely because the Agent runs in a container. If the mount is writable, code inside that environment may alter or delete files within it. Docker’s documentation explains how bind mounts expose host paths and support read-only configuration.
Use separate paths for separate purposes. The working project can be writable when the task requires edits. Reference documents can be mounted read-only if the setup permits it. Keep credentials, personal files, unrelated repositories, SSH material, and system configuration outside the mounted paths unless a specific task requires a carefully limited exception.
Boundary check: A container limits what is exposed through its configuration; it does not undo access that the operator grants through a writable host mount. Review the actual mounts before starting a task, not after an unexpected file change.
The distinction is easy to miss when a deployment guide shows a convenient host path. A bind mount connects a host directory to a path inside the container, so the host directory is still the place where changes occur. A read-only mount can prevent writes through that mount, but it is not a substitute for leaving irrelevant or sensitive host paths unmounted.
Prepare the service entry point and container permissions
Before launching the service, check the current OpenHands installation instructions for the container image, configuration options, required environment variables, and local access address. These details can change. This guide deliberately does not provide a fixed command or image tag: use the current OpenHands local installation instructions and confirm that their options match the selected sandbox mode.
The management interface should only be reachable by the people and networks that need it. For a local development setup, bind the service to the loopback address 127.0.0.1 where the current configuration permits that choice. Docker’s port-publishing documentation explains why the host address matters: publishing a port without a specific host IP can expose it on all host network interfaces, rather than limiting access to the local machine. Verify the effective published address instead of inferring it from the fact that a browser on the Mac can open the interface. See Docker’s port publishing and host binding behavior.
Docker socket access deserves a separate decision. The socket is an interface to the Docker daemon, not merely a convenient file that allows an Agent to see container status. A process with access to a daemon may be able to request powerful container operations. Docker’s guidance on protecting access to the daemon is relevant because the security impact depends on the authority granted through that connection.
Does an OpenHands container need the Docker socket? Not by default as a matter of safe deployment practice. Only expose Docker management access when the chosen, documented workflow requires the Agent to create or control containers. First identify the feature that requires it, then confirm the current official instructions and assess the impact if an Agent-issued command is wrong. If no task requirement has been verified, leave the socket unavailable.
Also distinguish the OpenHands application container from the sandbox that executes Agent work. They are not interchangeable names for one security boundary. Review which component receives each mount, credential, and network permission. A setup that keeps the application container’s host access narrow can still create risk if a separate execution environment receives a broad writable mount or privileged management capability.
Configure credentials and permissions for the first task
Treat model-provider credentials, repository credentials, and workspace access as separate permissions. A model credential enables access to a model service; a repository token may permit reading or changing code; a writable mount determines which local files an Agent can change. Combining these into one long-lived credential and one broad filesystem mount makes it harder to identify or reverse a mistake.
For private repositories or external APIs, issue credentials scoped to the task where the provider supports it. Avoid putting tokens in the project directory, repository history, sample configuration, or task instructions where they can be exposed through logs or generated output. GitHub’s guidance on keeping API credentials secure describes practices for limiting credential exposure. Its documentation on token expiration and revocation also explains how to end access when a token is no longer needed.
Plan credential cleanup before the task starts. Record where temporary credentials were configured, remove them after use, and revoke any token that may have been exposed or whose scope is no longer appropriate. If credentials are injected through environment configuration, check whether the selected deployment passes them to the application, the execution container, or both. Do not assume that a credential is hidden from an Agent just because it is not stored in the workspace.
Containerization also does not eliminate network access or the consequences of granting a task permission. An Agent may still contact services available through the configured network and may misuse any valid credential it can access. Restrict permissions according to the work: a task that only needs to inspect a repository should not automatically receive write access to a private repository or credentials for unrelated services.
Verify the deployment with a low-risk task
Use a small project without sensitive data for the first run. The purpose is to verify deployment wiring and boundaries before entrusting OpenHands with a valuable codebase. The test should confirm that the interface is reachable as intended, the selected container runtime works, and only the planned workspace is available.
Follow this sequence:
- [ ] Review the current official setup instructions and confirm that the selected path is current, rather than a legacy V0 procedure.
- [ ] Create a dedicated test project directory and identify any reference material that should be read-only.
- [ ] Configure only the mounts needed for the task. Check which are writable and confirm that no unrelated host directory is included.
- [ ] Start OpenHands using the currently documented container configuration. Check the effective network binding and confirm that the service is not unintentionally reachable beyond the intended interface.
- [ ] Run a harmless task that reads a file and makes a small, expected change within the test workspace.
- [ ] Inspect the result on the host, confirm that changes landed only in the intended directory, and review the task output for unexpected paths or access.
- [ ] Check whether the task environment is still running after the test. Confirm that it did not receive Docker socket access or credentials that were not part of the plan.
This is a deployment and access-boundary check, not proof that every future task is safe. Repeat the review when the workspace changes, credentials change, a new tool is introduced, or the OpenHands configuration is updated. If the task fails because it cannot reach an unmounted file or use an unavailable credential, treat that as a prompt to evaluate the specific need—not as a reason to grant broad access automatically.
End the task and separate native macOS builds
When the task is complete, preserve intended code changes through the team’s normal review process, then stop or remove the task environment according to the current setup instructions. Revoke temporary credentials and remove temporary configuration. Do not leave a one-off environment running as the default trusted workspace for unrelated work.
For macOS-native application work, plan the build environment separately. An OpenHands Docker sandbox can provide an execution boundary for coding tasks, but it should not be described as a macOS build machine. If a workflow needs Xcode or another native macOS toolchain, decide which environment performs that build and how reviewed code reaches it. Keep the Agent’s write access to the project distinct from any credentials or permissions used by the native build process.
Apple’s App Sandbox documentation describes a mechanism for macOS applications and their authorized capabilities. That is a different mechanism from an OpenHands Docker sandbox. It does not establish that a Docker container is an absolute host boundary, nor does it make macOS application sandbox controls a substitute for restricting mounts and credentials in an Agent workflow.
| Deployment choice | Appropriate use | Boundary to verify |
|---|---|---|
| OpenHands with its documented Docker sandbox | Repository edits, tests, and tasks that execute project code | Exact workspace mounts, writable paths, service exposure, and whether Docker management access is needed |
| Direct local execution | Only where the current supported setup and the task’s trust requirements justify it | Which host files, credentials, and tools the process can reach |
| Separate macOS-native build environment | Xcode or other work requiring native macOS tooling | How code is transferred, which credentials are present, and whether the Agent can access the build host |
A Mac-based deployment decision should account for more than whether the interface starts. These operating conditions are useful to compare before choosing a workflow:
| Requirement | Container sandbox on a Mac | Separate native macOS environment |
|---|---|---|
| Edit a project in a restricted workspace | Suitable when only the required project path is mounted | Possible, but host access still needs to be limited |
| Run code from an untrusted repository | A narrower execution path, not an absolute guarantee | Requires an independently designed execution boundary |
| Use Xcode or macOS-native tools | Do not assume the container provides them | Suitable when the environment actually provides the required native toolchain |
| Give the Agent Docker management authority | Avoid unless the documented task requires it | Still a separate privilege decision; native execution does not make it harmless |
| Share credentials across tasks | Avoid broad, long-lived access | Use task-scoped credentials and remove or revoke temporary access |
If the work only requires Linux-oriented code execution and a bounded project workspace, start with the documented OpenHands container route and keep its permissions narrow. If the work needs native macOS builds, do not try to solve that requirement by broadening the Agent container’s host access. Separate the build environment from the Agent’s file permissions and pass reviewed code between them.
A self-managed container setup can keep a task close to an existing development workflow, but it still requires host maintenance, configuration review, and careful handling of mounts, network exposure, and credentials. Using a developer’s everyday Mac directly can also leave unrelated files and tools closer to the task than intended. When native builds are necessary, a dedicated Mac environment can separate that workload from the daily workstation; it does not replace the need to review code, constrain credentials, or configure the Agent sandbox correctly. For a temporary macOS build or test environment, KuzCloud’s console provides the relevant service entry point, while the KuzCloud help center can help clarify environment setup. Treat that environment as a place to run native work—not as a security guarantee for OpenHands.
Run AI Coding Tasks on a Dedicated Mac
Move your workloads off your local Mac and onto a dedicated physical machine.
Use full root access to configure a separate environment for native macOS builds and testing.