docs: Add Apptainer sandbox documentation

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",

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.
+
+<Note>
+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)
+</Note>
+
+## 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
+```
+
+<Note>
+Building from a base image requires internet access and may take several minutes on first run. The built image is cached for subsequent runs.
+</Note>
+
+### 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