Apptainer Sandbox

A ready-to-run example is available here!

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.

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)
LLM API key set in environment

Basic Apptainer Sandbox Example

This example is available on GitHub: examples/02_remote_agent_server/08_convo_with_apptainer_sandboxed_server.py

This example shows how to create an ApptainerWorkspace that automatically manages Apptainer containers for agent execution:

examples/02_remote_agent_server/08_convo_with_apptainer_sandboxed_server.py

import os
import platform
import time

from pydantic import SecretStr

from openhands.sdk import (
    LLM,
    Conversation,
    RemoteConversation,
    get_logger,
)
from openhands.tools.preset.default import get_default_agent
from openhands.workspace import ApptainerWorkspace


logger = get_logger(__name__)

# 1) Ensure we have LLM API key
api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."

llm = LLM(
    usage_id="agent",
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    base_url=os.getenv("LLM_BASE_URL"),
    api_key=SecretStr(api_key),
)


def detect_platform():
    """Detects the correct platform string."""
    machine = platform.machine().lower()
    if "arm" in machine or "aarch64" in machine:
        return "linux/arm64"
    return "linux/amd64"


def get_server_image():
    """Get the server image tag, using PR-specific image in CI."""
    platform_str = detect_platform()
    arch = "arm64" if "arm64" in platform_str else "amd64"
    # If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
    # Otherwise, use the latest image from main
    github_sha = os.getenv("GITHUB_SHA")
    if github_sha:
        return f"ghcr.io/openhands/agent-server:{github_sha[:7]}-python-{arch}"
    return "ghcr.io/openhands/agent-server:latest-python"


# 2) Create an Apptainer-based remote workspace that will set up and manage
#    the Apptainer container automatically. Use `ApptainerWorkspace` with a
#    pre-built agent server image.
#    Apptainer (formerly Singularity) doesn't require root access, making it
#    ideal for HPC and shared computing environments.
server_image = get_server_image()
logger.info(f"Using server image: {server_image}")
with ApptainerWorkspace(
    # use pre-built image for faster startup
    server_image=server_image,
    host_port=8010,
    platform=detect_platform(),
) as workspace:
    # 3) Create agent
    agent = get_default_agent(
        llm=llm,
        cli_mode=True,
    )

    # 4) Set up callback collection
    received_events: list = []
    last_event_time = {"ts": time.time()}

    def event_callback(event) -> None:
        event_type = type(event).__name__
        logger.info(f"🔔 Callback received event: {event_type}\n{event}")
        received_events.append(event)
        last_event_time["ts"] = time.time()

    # 5) Test the workspace with a simple command
    result = workspace.execute_command(
        "echo 'Hello from sandboxed environment!' && pwd"
    )
    logger.info(
        f"Command '{result.command}' completed with exit code {result.exit_code}"
    )
    logger.info(f"Output: {result.stdout}")
    conversation = Conversation(
        agent=agent,
        workspace=workspace,
        callbacks=[event_callback],
    )
    assert isinstance(conversation, RemoteConversation)

    try:
        logger.info(f"\n📋 Conversation ID: {conversation.state.id}")

        logger.info("📝 Sending first message...")
        conversation.send_message(
            "Read the current repo and write 3 facts about the project into FACTS.txt."
        )
        logger.info("🚀 Running conversation...")
        conversation.run()
        logger.info("✅ First task completed!")
        logger.info(f"Agent status: {conversation.state.execution_status}")

        # Wait for events to settle (no events for 2 seconds)
        logger.info("⏳ Waiting for events to stop...")
        while time.time() - last_event_time["ts"] < 2.0:
            time.sleep(0.1)
        logger.info("✅ Events have stopped")

        logger.info("🚀 Running conversation again...")
        conversation.send_message("Great! Now delete that file.")
        conversation.run()
        logger.info("✅ Second task completed!")

        # Report cost (must be before conversation.close())
        cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
        print(f"EXAMPLE_COST: {cost}")
    finally:
        print("\n🧹 Cleaning up conversation...")
        conversation.close()

You can run the example code as-is.

The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.

ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

Configuration Options

The ApptainerWorkspace supports several configuration options:

Option 1: Pre-built Image (Recommended)

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:

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:

Install Apptainer following the official guide
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/

Next Steps

Docker Sandbox - Alternative container runtime
API Sandbox - Remote API-based sandboxing
Local Server - Non-sandboxed local execution

Guides

Architecture

API Reference

When to Use Apptainer

Prerequisites

Basic Apptainer Sandbox Example

Configuration Options

Option 1: Pre-built Image (Recommended)

Option 2: Build from Base Image

Option 3: Use Existing SIF File

Key Features

Rootless Container Execution

Image Caching

Port Mapping

Differences from Docker

Troubleshooting

Apptainer Not Found

Permission Errors

Next Steps

Guides

Architecture

API Reference

​When to Use Apptainer

​Prerequisites

​Basic Apptainer Sandbox Example

​Configuration Options

​Option 1: Pre-built Image (Recommended)

​Option 2: Build from Base Image

​Option 3: Use Existing SIF File

​Key Features

​Rootless Container Execution

​Image Caching

​Port Mapping

​Differences from Docker

​Troubleshooting

​Apptainer Not Found

​Permission Errors

​Next Steps

When to Use Apptainer

Prerequisites

Basic Apptainer Sandbox Example

Configuration Options

Option 1: Pre-built Image (Recommended)

Option 2: Build from Base Image

Option 3: Use Existing SIF File

Key Features

Rootless Container Execution

Image Caching

Port Mapping

Differences from Docker

Troubleshooting

Apptainer Not Found

Permission Errors

Next Steps