DAIV Sandbox

What is daiv-sandbox?

daiv-sandbox is a FastAPI application designed to securely execute arbitrary commands within a controlled environment. Each execution is isolated in a transient Docker container ensuring a clean and secure execution space. It is designed to be used as a bash commands executor for DAIV.

This is very useful to increase the capabilities of an AI agent with bash commands execution capabilities. For instance, you can use it to apply formatting changes to a repository codebase like running black, isort, ruff, prettier, or update dependencies, lock files, etc...

To enhance security, daiv-sandbox leverages gVisor as its container runtime. This provides an additional layer of protection by restricting the running code's ability to interact with the host system, thereby minimizing the risk of sandbox escape.

While gVisor significantly improves security, it may introduce some performance overhead due to its additional isolation mechanisms. This trade-off is generally acceptable for applications prioritizing security over raw execution speed.

Getting Started

daiv-sandbox is available as a Docker image on GitHub Container Registry.

You can run the container using the following command:

$ docker run --rm -d -p 8000:8000 -e DAIV_SANDBOX_API_KEY=my-secret-api-key ghcr.io/srtab/daiv-sandbox:latest

You can also configure the container using environment variables. See the Configuration section for more details.

For usage examples, see the Usage section.

Security (Optional)

To enhance security, daiv-sandbox can be used with gVisor as its container runtime. This provides an additional layer of protection by restricting the running code's ability to interact with the host system, thereby minimizing the risk of sandbox escape.

To benefit from this additional layer of protection, you need to install gVisor on the host machine. Follow the instructions here and here. You will need to configure gVisor with a shared root filesystem to allow daiv-sandbox copy files to the container, see the gVisor documentation for more details.

Tip

If you're getting an error "overlay flag is incompatible with shared file access for rootfs", you need to add --overlay2=none flag to the gVisor configuration.

After installing gVisor, you need to define the DAIV_SANDBOX_RUNTIME environment variable to use runsc when running the container:

$ docker run --rm -d -p 8000:8000 -e DAIV_SANDBOX_API_KEY=my-secret-api-key -e DAIV_SANDBOX_RUNTIME=runsc ghcr.io/srtab/daiv-sandbox:latest

Configuration

All settings are configurable via environment variables. The available settings are:

Environment Variable	Description	Options/Default
DAIV_SANDBOX_API_KEY	The API key required to access the sandbox API.
DAIV_SANDBOX_API_V1_STR	Base path for API routes.	Default: "/api/v1"
DAIV_SANDBOX_ENVIRONMENT	The deployment environment.	Options: local, production Default: "production"
DAIV_SANDBOX_SENTRY_DSN	The DSN for Sentry error tracking.	Optional
DAIV_SANDBOX_SENTRY_ENABLE_LOGS	Whether to enable Sentry log forwarding.	Default: False
DAIV_SANDBOX_SENTRY_TRACES_SAMPLE_RATE	Sentry traces sampling rate.	Default: 0.0
DAIV_SANDBOX_SENTRY_PROFILES_SAMPLE_RATE	Sentry profiles sampling rate.	Default: 0.0
DAIV_SANDBOX_SENTRY_SEND_DEFAULT_PII	Send default PII to Sentry.	Default: False
DAIV_SANDBOX_RUNTIME	The container runtime to use.	Options: runc, runsc Default: "runc"
DAIV_SANDBOX_RUN_UID	UID for sandbox command execution.	Default: 1000
DAIV_SANDBOX_RUN_GID	GID for sandbox command execution.	Default: 1000
DAIV_SANDBOX_GIT_IMAGE	Image used to extract patches.	Default: "alpine/git:2.52.0"
DAIV_SANDBOX_HOST	The host to bind the service to.	Default: "0.0.0.0"
DAIV_SANDBOX_PORT	The port to bind the service to.	Default: 8000
DAIV_SANDBOX_LOG_LEVEL	The log level to use.	Options: DEBUG, INFO, WARNING, ERROR, CRITICAL Default: "INFO"

Usage

daiv-sandbox provides a REST API to interact with. Here is a quick overview of the available endpoints:

• POST /session/: Start a sandbox session.
• POST /session/{session_id}/: Run commands on the sandbox session.
• DELETE /session/{session_id}/: Close the sandbox session.
• GET /-/health/: Healthcheck endpoint.
• GET /-/version/: Current application version.

Starting a Sandbox Session

To start a sandbox session, you need to call the POST /session/ endpoint. A Docker image is pulled from the registry and used to create the sandbox container.

After image is pulled or built, the container will be created and started, along with an helper container that will be used to extract the patch of the changed files.

Here is an example using curl:

$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: notsosecret" \
  -d "{\"base_image\": \"python:3.12\"}" \
  http://localhost:8000/api/v1/session/

The response will be a JSON object with the following structure containing the session ID:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

The following table describes the parameters for the session/ endpoint:

Parameter	Description	Required	Valid Values
base_image	The base image to use for the container.	Yes	Any valid Docker image
ephemeral	Do not persist workspace between command runs.	No	true or false (default: false)
extract_patch	Extract a patch with the changes made by the executed commands.	No	true or false (default: false)
network_enabled	Enable network access inside the container.	No	true or false (default: false)
environment	Environment variables to set at container start.	No	Object of string pairs
memory_bytes	Memory limit for the container (bytes).	No	Integer (bytes)
cpus	CPU quota for the container.	No	Float (e.g. 0.5, 1.0)

Note

For security reasons, building images from arbitrary Dockerfiles is not supported by this service. Provide a base_image.

Warning

The base_image need to be a distro image. Distroless images will not work as there is no shell available in the container to maintain the image running indefinitely.

Here is an example using python:

import httpx

response = httpx.post(
    "http://localhost:8000/api/v1/session/",
    headers={"X-API-Key": "notsosecret"},
    json={"base_image": "python:3.12"},
)

response.raise_for_status()
resp = response.json()

print(resp["session_id"])

Running Commands

To run commands on a sandbox session, you need to call the POST /session/{session_id}/ endpoint using the session ID returned when starting the session.

This endpoint can be used to execute arbitrary commands on a provided archive, for instance, a tar.gz archive containing a repository codebase. The archive is extracted to a temporary directory and the commands are executed in the root of the extracted directory. The output of each command is returned in the response along with a patch of the changed files if the extract_patch parameter is set to true in the request to start the session and there were changes made by the commands.

By default, all commands are executed sequentially regardless of their exit codes. However, you can enable fail-fast behavior by setting the fail_fast parameter to true, which will stop execution immediately if any command fails (returns a non-zero exit code).

If archive is omitted, commands run against the existing container filesystem from the previous calls in the same session.

When extract_patch is enabled on session creation, the patch field in the response is a base64-encoded unified diff.

The following table describes the parameters for the POST /session/{session_id}/ endpoint:

Parameter	Description	Required	Valid Values
commands	The commands to execute.	Yes	List of strings
archive	The archive to extract and execute the commands on.	No	Base64 encoded tar.gz archive
fail_fast	Stop execution if any command fails.	No	true or false (default: false)

Here is an example using curl:

$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: notsosecret" \
  -d "{\"archive\": \"$(base64 -w 0 django-webhooks-master.tar.gz)\", \"commands\": [\"ls -la\"], \"fail_fast\": true}" \
  http://localhost:8000/api/v1/session/550e8400-e29b-41d4-a716-446655440000/

The response will be a JSON object with the following structure:

{
  "results": [
    {
      "command": "ls -la",
      "output": "total 12\ndrwxr-xr-x 3 root root 4096 Nov 20 20:28 .\ndrwxrwxrwt 1 root root 4096 Nov 20 20:28 ..\ndrwxrwxr-x 3 root root 4096 Nov 14 14:39 django-webhooks-master\n",
      "exit_code": 0
    }
  ],
  "patch": null // Base64-encoded diff; null when no changes were detected
}

Here is an example using python:

import httpx
import tarfile
import base64
import io

# Create tar archive first
tarstream = io.BytesIO()
with tarfile.open(fileobj=tarstream, mode="w:gz") as tar:
    # Add files to tar...
    pass

tarstream.seek(0)
response = httpx.post(
    "http://localhost:8000/api/v1/session/550e8400-e29b-41d4-a716-446655440000/",
    headers={"X-API-Key": "notsosecret"},
    json={
        "archive": base64.b64encode(tarstream.getvalue()).decode(),
        "commands": ["ls -la"],
        "fail_fast": True,
    },
)

response.raise_for_status()
resp = response.json()

print(resp["results"][0]["output"])
if resp["patch"]:
    print(base64.b64decode(resp["patch"]).decode())

Tip

To apply the patch to the original repository/directory, you can use the git apply command. Don't need to be a git repository, it can be any directory.

$ git apply --whitespace=nowarn --reject < patch.diff

Closing a Sandbox Session

To close a sandbox session, you need to call the DELETE /session/{session_id}/ endpoint using the session ID returned when starting the session.

$ curl -X DELETE \
  -H "X-API-Key: notsosecret" \
  http://localhost:8000/api/v1/session/550e8400-e29b-41d4-a716-446655440000/

The response will be an empty body with a status code of 204.

Tip

Why closing a sandbox session is important? Because it will remove the container from the host machine, freeing up resources.

Contributing

We welcome contributions! Whether you want to fix a bug, add a new feature, or improve documentation, please refer to the CONTRIBUTING.md file for more information.

License

This project is licensed under the Apache 2.0 License.

Support & Community

For questions or support, please open an issue in the GitHub repository. Contributions, suggestions, and feedback are greatly appreciated!

Happy Coding!