Skip to main content
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

​
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:

​
Basic Apptainer Sandbox Example

This example shows how to create an ApptainerWorkspace that automatically manages Apptainer containers for agent execution:
examples/02_remote_agent_server/05_convo_with_apptainer_sandboxed_server.py
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: Use a pre-built agent server image for fastest startup: 
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: 
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: 
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: 
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:
FeatureDockerApptainer
Root access requiredYes (daemon)No
InstallationRequires Docker EngineSingle binary
Image formatOCI/DockerSIF
Build speedFast (layers)Slower (monolithic)
HPC compatibilityLimitedExcellent
NetworkingBridge/overlayHost networking

​
Troubleshooting

​
Apptainer Not Found

If you see apptainer: command not found:
  1. Install Apptainer following the official guide
  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