docs: improve custom sandbox guide with detailed requirements and examples #5268

h55nick · 2024-11-25T21:22:44Z

This PR improves the custom sandbox guide documentation by:

Adding a clear "Important Requirements" section highlighting:
- Debian-based image requirement
- Root user requirement
- System-wide package availability
Providing a complete example Dockerfile with multiple packages
Adding two methods for building and running:
- Direct Docker build
- Docker Compose setup
Including detailed sections on:
- Configuration options
- Common issues and troubleshooting
- Testing procedures
- Security considerations

This addresses issue #5266 by making the custom sandbox setup process more clear and comprehensive.

Changes include:

Added clear requirements section
Improved example Dockerfile
Added docker-compose.yml example
Added troubleshooting guide
Added testing instructions
Added security considerations

…mples

h55nick · 2024-11-25T21:27:41Z

docs/modules/usage/how-to/custom-sandbox-guide.md

+    && rm -rf /var/lib/apt/lists/*
+
+# Ensure we're running as root
+USER root


I think we change to a openhands specific user, but we need to confirm this is a requirement to exit the build as root.

h55nick · 2024-11-25T21:28:12Z

docs/modules/usage/how-to/custom-sandbox-guide.md

 ```

-Save this file in a folder. Then, build your Docker image (e.g., named custom-image) by navigating to the folder in
-the terminal and running::
+Save this file as `docker/runtime.Dockerfile`. Then, build your Docker image using one of these methods:


we should probably note that a nested docker/ dir is not required.

Not sure if we want to take into account people that might not be too familiar with docker and dockerfiles.
In the previous version, it said to navigate to the folder in the terminal and then run the command. In the new version, it doesn't specify where to run the command from.

@mamoodi sounds like you want a flattened example. I'm fine with that. Let's update the documentation so that we don't have any nested directory structures.

h55nick · 2024-11-25T21:29:01Z

docs/modules/usage/how-to/custom-sandbox-guide.md


-First, ensure you can run OpenHands by following the instructions in [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
+- `SANDBOX_RUNTIME_CONTAINER_IMAGE`: Specifies the custom runtime image (e.g., `local/runtime:latest`)


Let's add a note here around SANDBOX_BASE_CONTAINER_IMAGE and the differences here.

Agree, as a newcomer I find this confusing. This is what I found out after lots of trial and error:

I could only get the custom sandbox image to work using the development workflow outside docker, e.g. make run.

Setting SANDBOX_RUNTIME_CONTAINER_IMAGE together with docker compose does not result in a working agent, it's like lots of things are missing from the image

Setting SANDBOX_BASE_CONTAINER_IMAGE together with docker compose fails with docker not being available when building the runtime image

The only way to get the custom sandbox image to work together with docker compose was to first set the custom image as base image in config.toml, start openhands using make run and then look for the logs showing what the runtime image was built and tagged as, then copying that image reference to SANDBOX_RUNTIME_CONTAINER_IMAGE. Then, using docker compose would result in a openhands agent using the custom runtime image

h55nick · 2024-11-25T21:29:55Z

docs/modules/usage/how-to/custom-sandbox-guide.md


 ```dockerfile
 FROM debian:latest

 # Install required packages
-RUN apt-get update && apt-get install -y ruby
+RUN apt-get update && apt-get install -y \


maybe we should note that this should be specific to the users wants. A common one might be installing the GH cli here.

h55nick · 2024-11-25T21:31:45Z

docs/modules/usage/how-to/custom-sandbox-guide.md


-## Using the Development Workflow


We should keep the "Development workflow" section intact. Let's note that this is specific for development of/on OpenHands, and not specific to "development using OpenHands" which are distinct.

mamoodi · 2024-11-26T14:32:05Z

docs/modules/usage/how-to/custom-sandbox-guide.md

@@ -12,53 +12,131 @@ You have two options for customization:
 1. Use an existing image with the required software.
 2. Create your own custom Docker image.

-If you choose the first option, you can skip the `Create Your Docker Image` section.
+## Important Requirements


This section is really nice

mamoodi · 2024-11-26T14:32:45Z

docs/modules/usage/how-to/custom-sandbox-guide.md

-the terminal and running::
+Save this file as `docker/runtime.Dockerfile`. Then, build your Docker image using one of these methods:
+
+### Method 1: Direct Docker Build


This may be a personal thing but the Method 1 and Method 2 do different things. One of them just builds the custom docker image and the other actually runs everything. I would just keep the Method 1 and show the user how to build it.

The other problem with the docker compose is it has OpenHands version which again is another place that needs to be continuously updated. Also it has other configurations that get passed into the docker command. If that command ever changes, this would need to be updated too.

Good points.

Let's add a comment in the docker-compose to check the require variables that can be passed. This should link to the docs that explain the variables available.

Let's add a command to the docker build (Method 1) that links to the explanation on how to run the command and specify how to pass in the newly built docker-image as the runtime image.

Agree to just keep Method 1 and then include instructions on how to set the SANDBOX_RUNTIME_CONTAINER_IMAGE env var (maybe also the equivalent config.toml setting) when running openhands.

mamoodi · 2024-11-26T14:34:00Z

docs/modules/usage/how-to/custom-sandbox-guide.md


-### Setup
+### Environment Variables


This section's information doesn't really add anything for this procedure.
The variable SANDBOX_RUNTIME_CONTAINER_IMAGE doesn't get used if I understand correctly.

Let's remove this section.

mamoodi · 2024-11-26T14:36:44Z

docs/modules/usage/how-to/custom-sandbox-guide.md


+## Common Issues and Troubleshooting


I would move this section above ## Security Considerations.

mamoodi · 2024-11-26T14:38:16Z

docs/modules/usage/how-to/custom-sandbox-guide.md

+   - Verify environment variable settings
+   - Check volume mount permissions
+
+## Testing Your Custom Sandbox


This section should be moved right after Create You Docker Image. However, it should have instructions on how to actually use the custom image. Either in development workflow or with the docker command through the README. Ideally without actually copy pasting the docker command.

neubig · 2024-12-11T09:19:52Z

Hi! Shall we get this merged?

motin · 2024-12-16T09:08:01Z

docs/modules/usage/how-to/custom-sandbox-guide.md


-For example, if you want OpenHands to have `ruby` installed, create a `Dockerfile` with the following content:
+Here's a complete example of a custom runtime Dockerfile:

 ```dockerfile
 FROM debian:latest


Suggested change

FROM debian:latest

FROM nikolaik/python-nodejs:python3.12-nodejs22

Rationale: Using the same base as the default sandbox image and just adding ruby makes it a bit more easy to get the right versions of python and node are being installed in the runtime image, rather than relying on the python and node versions that are included in debian:latest

motin · 2024-12-16T09:09:37Z

docs/modules/usage/how-to/custom-sandbox-guide.md

-RUN apt-get update && apt-get install -y ruby
+RUN apt-get update && apt-get install -y \
+    ruby \
+    python3 \


If using the default sandbox image in the FROM clause, we don't need to add python3 or nodejs here

motin · 2024-12-16T09:10:34Z

docs/modules/usage/how-to/custom-sandbox-guide.md


-First, ensure you can run OpenHands by following the instructions in [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
+- `SANDBOX_RUNTIME_CONTAINER_IMAGE`: Specifies the custom runtime image (e.g., `local/runtime:latest`)


Agree, as a newcomer I find this confusing. This is what I found out after lots of trial and error:

I could only get the custom sandbox image to work using the development workflow outside docker, e.g. make run.

Setting SANDBOX_RUNTIME_CONTAINER_IMAGE together with docker compose does not result in a working agent, it's like lots of things are missing from the image

Setting SANDBOX_BASE_CONTAINER_IMAGE together with docker compose fails with docker not being available when building the runtime image

The only way to get the custom sandbox image to work together with docker compose was to first set the custom image as base image in config.toml, start openhands using make run and then look for the logs showing what the runtime image was built and tagged as, then copying that image reference to SANDBOX_RUNTIME_CONTAINER_IMAGE. Then, using docker compose would result in a openhands agent using the custom runtime image

github-actions · 2025-01-16T01:56:30Z

This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

docs: improve custom sandbox guide with detailed requirements and exa…

fda49e7

…mples

h55nick commented Nov 25, 2024

View reviewed changes

mamoodi reviewed Nov 26, 2024

View reviewed changes

motin reviewed Dec 16, 2024

View reviewed changes

github-actions bot added the Stale Inactive for 30 days label Jan 16, 2025

h55nick closed this Jan 17, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve custom sandbox guide with detailed requirements and examples #5268

docs: improve custom sandbox guide with detailed requirements and examples #5268

h55nick commented Nov 25, 2024

h55nick Nov 25, 2024

h55nick Nov 25, 2024

mamoodi Nov 26, 2024

h55nick Nov 26, 2024

h55nick Nov 25, 2024

motin Dec 16, 2024 •

edited

Loading

h55nick Nov 25, 2024

h55nick Nov 25, 2024

mamoodi Nov 26, 2024

mamoodi Nov 26, 2024

mamoodi Nov 26, 2024 •

edited

Loading

h55nick Nov 26, 2024 •

edited

Loading

motin Dec 16, 2024 •

edited

Loading

mamoodi Nov 26, 2024 •

edited

Loading

h55nick Nov 26, 2024

mamoodi Nov 26, 2024

mamoodi Nov 26, 2024

neubig commented Dec 11, 2024

motin Dec 16, 2024 •

edited

Loading

motin Dec 16, 2024

motin Dec 16, 2024 •

edited

Loading

github-actions bot commented Jan 16, 2025


		First, ensure you can run OpenHands by following the instructions in [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
		- `SANDBOX_RUNTIME_CONTAINER_IMAGE`: Specifies the custom runtime image (e.g., `local/runtime:latest`)

	FROM debian:latest
	FROM nikolaik/python-nodejs:python3.12-nodejs22

docs: improve custom sandbox guide with detailed requirements and examples #5268

docs: improve custom sandbox guide with detailed requirements and examples #5268

Conversation

h55nick commented Nov 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

motin Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mamoodi Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

h55nick Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

motin Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

mamoodi Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neubig commented Dec 11, 2024

motin Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

motin Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jan 16, 2025

motin Dec 16, 2024 •

edited

Loading

mamoodi Nov 26, 2024 •

edited

Loading

h55nick Nov 26, 2024 •

edited

Loading

motin Dec 16, 2024 •

edited

Loading

mamoodi Nov 26, 2024 •

edited

Loading

motin Dec 16, 2024 •

edited

Loading

motin Dec 16, 2024 •

edited

Loading