Hi, does anyone have a working example of a Docker-in-Docker (DinD) setup, preferably as a Docker Compose? Currently, the only documented local Docker option requires mounting

docker.sock

, which grants root-level access to the host's Docker daemon. I'd like to run OpenHands inside a parent Docker container with its own nested Docker daemon, so the inner instance has zero visibility into my host's containers, except for those I explicitly whitelist in the form of configured Docker network visibility. (I'm hoping this can be eventually publicly documented too.)

Hey @wonderful-airport-43031, are you accessing OpenHands through the GUI, CLI, or SDK?

I want to configure a fully local setup, where all the tools are Dockerized, including the agent sandbox, with no binary being run on the host OS. I haven't configured OpenHands before.

Got it, I’m still trying to understand the use case so I can give the best advice, but have you seen the software agent sdk? https://github.com/OpenHands/software-agent-sdk It’s the modern way of running OpenHands programmatically, and has a flexible “workspace” framework that can use no sandbox, docker, apptainer, etc: https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace It also powers our CLI and the new version of the GUI. I think that this should solve your problem, but if you have a little more detail about the use case and requirements I could respond with more confidence

I'm sorry if I misunderstood, but isn't the Agent SDK only a set of tools to "build agents"? My goal is to configure the OpenHands tool itself, i.e., to use the existing tools, provide a sandbox, GUI (or CLI), and make it possible to run everything locally with no cloud access. This is the use-case, for which the motivation is only the fact that I absolutely will not mount

docker.sock

as presented by the documentation. Thanks for any additional details, I'm not really confident in how your stack is built bottom-up.

OK, so the goal is to run the OpenHands GUI or CLI without mounting docker.sock?

yep 👍 it should be all isolated, with no way to interact with anything on my machine, until I whitelist it

OK, let me (OpenHands) double-check quickly, one sec

subsequently, I'm still exploring what kinds of sandboxes are supported, but I assume it should be possible to spin up a container service of a linux server and whitelist it, to make it possible for OpenHands for example to send commands to that server via ssh. The more universal this virtual environment setup can be, the better 🙂

I think this should work, can you check?

Thanks, the Dockerfile does indeed work, what changes have been made there? However, when trying the Agent, I'm getting

raise SandboxError('Agent Server Failed to start properly')

. I assume this setup has full access to both the internet and my exposed ports of other Docker containers (though Ollama doesn't seem to directly interact with my Ollama installation by default), so I'll need to create a Docker network isolation on my own. Does the Agent need to be started separately?

Hey Steve, thanks. Sorry I’m a bit swamped right now and don’t have time to take a look, but feel free to open an issue about what you’d like to see changed!

No problem, you can let me know when you or anyone else has the capacity to work on the onboarding process / security 🙂 I don't know how I'd formally define this as an issue, as it's a general question of not knowing how to start using OpenHands at all, so I'll appreciate any news; preferably straight in the form of a documentation section 🙂 I'm hoping the feedback from a newcomer will be useful (for doc testing).

Hey Steve, would love to get on a call with you to understand this onboarding challenge! Also copying my colleague @hundreds-twilight-32833 who is looking into our developer experience. Here is my calendar if you want to find a time - would be great to dig into this if you have 30 minutes 🙏 https://calendly.com/joe-all-hands-ai

@elegant-branch-54423 Hi, generally speaking, I'd definitely want to also run the OpenHands GUI as dockerized, because it's a better long-term approach to isolate all tools in order to reduce their risks of future version updates. As long as the tool doesn't interact with Docker directly, it should be a trivial matter to dockerize any tool that runs on a standard environment (Linux, Python...). What I hear from your solution is that you seem to suggest introducing the optionality to decouple the GUI from the Agent, in a way that we can have more control over the connector interface. That sounds like the perfect solution, as it makes the modules plug-and-play, letting us decide to run any Agent on any device, and just use protocols like TCP/IP to connect them. Even Docker naturally functions this way, such that whenever a container exposes a specific port, any other tools on the host can use this port to connect to that container (see: Ollama, commonly auto-detected on a standard port). In practice, compared to the existing Quick Start approach, this would mean that instead of the GUI spinning new Docker containers, it would be our job to start the containers and configure the connection between them. Anyone's personal preference can differ; there would absolutely be some value even in the alternative of simply having the GUI connect to a "Docker in Docker" (image: docker) where it would have the permission to spin up its own agents. From the configuration standpoint, if there are multiple Docker containers, I believe that a

docker compose

configuration file would be a more user-friendly example from the perspective of configuring a network isolation. Really, one of the risks that any newbie may not realize is that when you expose the

host.docker.internal

to the container, even though it's technically isolated from the machine, it can still use all the ports exposed on the host IP, which includes any ports exposed by other containers running on the host. For example, if you run some container with access control consisting of

admin

/

admin

user password inside, you may intuitively feel like "you're the only one who can access it via localhost anyway", but in fact, your other containers can sniff through this insecure pathway. On the other hand: sometimes you want an agent to have the access to the internet, and sometimes you may want to isolate it to only talk to some of your other containers without ever accessing the public internet directly (because its actions trace/log back to your IP, which may also be implicitly dangerous). In other words, I'm just saying that the

docker compose

includes standard patterns for a declarative network isolation, so the developer experience may be way better than just trusting your Linux skills to create all sorts of sandbox barriers 😉 (And honestly, Kubernetes is probably way better when it comes to declarative infrastructure maintenance, but there's also a higher learning curve when ensuring it's all correct, whereas in Docker Compose you just review a few network concepts. I wish you'll find someone in the community who will help write and validate all sorts of Quick Start variants 😄)

What I hear from your solution is that you seem to suggest introducing the optionality to decouple the GUI from the Agent, in a way that we can have more control over the connector interface. That sounds like the perfect solution, as it makes the modules plug-and-play, letting us decide to run any Agent on any device, and just use protocols like TCP/IP to connect them. Even Docker naturally functions this way, such that whenever a container exposes a specific port, any other tools on the host can use this port to connect to that container (see: Ollama, commonly auto-detected on a standard port).

In practice, compared to the existing Quick Start approach, this would mean that instead of the GUI spinning new Docker containers, it would be our job to start the containers and configure the connection between them. Anyone's personal preference can differ; there would absolutely be some value even in the alternative of simply having the GUI connect to a "Docker in Docker" (image: docker) where it would have the permission to spin up its own agents.

Hi @wonderful-airport-43031 I hope you are doing well! If you're still exploring options for hosting OpenHands, you may want to check out this Agent Canvas project (still in alpha): https://github.com/OpenHands/agent-canvas