From 72dbd763f522912bf7e847d6b6b37adb7e1810e1 Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 8 Dec 2025 16:00:34 +0000 Subject: [PATCH] docs: Add Apptainer sandbox documentation Add comprehensive documentation for ApptainerWorkspace, showing how to run agent servers in rootless Apptainer containers for HPC and shared computing environments. Includes: - When to use Apptainer vs Docker - Configuration options (pre-built image, base image, SIF file) - Key features and differences from Docker - Troubleshooting guide Relates to OpenHands/software-agent-sdk#892 --- docs.json | 1 + sdk/guides/agent-server/apptainer-sandbox.mdx | 152 ++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 sdk/guides/agent-server/apptainer-sandbox.mdx diff --git a/docs.json b/docs.json index ddeff833..19312db2 100644 --- a/docs.json +++ b/docs.json @@ -244,6 +244,7 @@ "sdk/guides/agent-server/overview", "sdk/guides/agent-server/local-server", "sdk/guides/agent-server/docker-sandbox", + "sdk/guides/agent-server/apptainer-sandbox", "sdk/guides/agent-server/api-sandbox", { "group": "API Reference", diff --git a/sdk/guides/agent-server/apptainer-sandbox.mdx b/sdk/guides/agent-server/apptainer-sandbox.mdx new file mode 100644 index 00000000..891e996d --- /dev/null +++ b/sdk/guides/agent-server/apptainer-sandbox.mdx @@ -0,0 +1,152 @@ +--- +title: Apptainer Sandbox +description: Run agent server in rootless Apptainer containers for HPC and shared computing environments. +--- + +The Apptainer sandboxed agent server demonstrates how to run agents in isolated Apptainer containers using ApptainerWorkspace. + +Apptainer (formerly Singularity) is a container runtime designed for HPC environments that doesn't require root access, making it ideal for shared computing environments, university clusters, and systems where Docker is not available. + + +This example is available on GitHub: [examples/02_remote_agent_server/05_convo_with_apptainer_sandboxed_server.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/05_convo_with_apptainer_sandboxed_server.py) + + +## When to Use Apptainer + +Use Apptainer instead of Docker when: +- Running on HPC clusters or shared computing environments +- Root access is not available +- Docker daemon cannot be installed +- Working in academic or research computing environments +- Security policies restrict Docker usage + +## Prerequisites + +Before running this example, ensure you have: +- Apptainer installed ([Installation Guide](https://apptainer.org/docs/user/main/quick_start.html)) +- LLM API key set in environment + +## Basic Apptainer Sandbox Example + +This example shows how to create an ApptainerWorkspace that automatically manages Apptainer containers for agent execution: + +```python icon="python" expandable examples/02_remote_agent_server/05_convo_with_apptainer_sandboxed_server.py +``` + +```bash Running the Example +export LLM_API_KEY="your-api-key" +cd agent-sdk +uv run python examples/02_remote_agent_server/05_convo_with_apptainer_sandboxed_server.py +``` + +## Configuration Options + +The `ApptainerWorkspace` supports several configuration options: + +### Option 1: Pre-built Image (Recommended) + +Use a pre-built agent server image for fastest startup: + +```python highlight={2} +with ApptainerWorkspace( + server_image="ghcr.io/openhands/agent-server:main-python", + host_port=8010, +) as workspace: + # Your code here +``` + +### Option 2: Build from Base Image + +Build from a base image when you need custom dependencies: + +```python highlight={2} +with ApptainerWorkspace( + base_image="nikolaik/python-nodejs:python3.12-nodejs22", + host_port=8010, +) as workspace: + # Your code here +``` + + +Building from a base image requires internet access and may take several minutes on first run. The built image is cached for subsequent runs. + + +### Option 3: Use Existing SIF File + +If you have a pre-built Apptainer SIF file: + +```python highlight={2} +with ApptainerWorkspace( + sif_file="/path/to/your/agent-server.sif", + host_port=8010, +) as workspace: + # Your code here +``` + +## Key Features + +### Rootless Container Execution + +Apptainer runs completely without root privileges: +- No daemon process required +- User namespace isolation +- Compatible with most HPC security policies + +### Image Caching + +Apptainer automatically caches container images: +- First run builds/pulls the image +- Subsequent runs reuse cached SIF files +- Cache location: `~/.cache/apptainer/` + +### Port Mapping + +The workspace exposes ports for agent services: +```python +with ApptainerWorkspace( + server_image="ghcr.io/openhands/agent-server:main-python", + host_port=8010, # Maps to container port 8010 +) as workspace: + # Access agent server at http://localhost:8010 +``` + +## Differences from Docker + +While the API is similar to DockerWorkspace, there are some differences: + +| Feature | Docker | Apptainer | +|---------|--------|-----------| +| Root access required | Yes (daemon) | No | +| Installation | Requires Docker Engine | Single binary | +| Image format | OCI/Docker | SIF | +| Build speed | Fast (layers) | Slower (monolithic) | +| HPC compatibility | Limited | Excellent | +| Networking | Bridge/overlay | Host networking | + +## Troubleshooting + +### Apptainer Not Found + +If you see `apptainer: command not found`: +1. Install Apptainer following the [official guide](https://apptainer.org/docs/user/main/quick_start.html) +2. Ensure it's in your PATH: `which apptainer` + +### Permission Errors + +Apptainer should work without root. If you see permission errors: +- Check that your user has access to `/tmp` +- Verify Apptainer is properly installed: `apptainer version` +- Ensure the cache directory is writable: `ls -la ~/.cache/apptainer/` + +### Build Failures + +If image building fails: +- Ensure you have internet access +- Check available disk space (builds require several GB) +- Try pulling a pre-built image instead + +## Next Steps + +- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Alternative container runtime +- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Remote API-based sandboxing +- **[Local Server](/sdk/guides/agent-server/local-server)** - Non-sandboxed local execution