What problem it solves

AI applications need isolated environments where agents can execute code, run commands, manage files, and operate browsers or desktops. Teams also need a consistent way to run these environments locally with Docker or on Kubernetes without switching between separate interfaces.

Key features

• Agent working environments — Provide agents with isolated environments for command execution, file management, and code execution through built-in APIs. Examples cover coding agents, browsers, and desktops.

  Source: README, examples

• Local and Kubernetes deployment — Start sandboxes locally with Docker and deploy them on Kubernetes through a unified lifecycle API. Resource pools and batch creation support evaluation and training workloads.

  Source: README

• Network access control — Route inbound traffic through a unified ingress gateway and apply per-sandbox policies to outbound access.

  Source: README

• Credential Vault — Allow agents to call external services while keeping real credentials out of sandbox workloads. The project documents outbound credential injection through its Credential Vault.

  Source: README, docs

• SDK, CLI, MCP, and protocol interfaces — Integrate through SDKs for several programming languages, use the `osb` terminal CLI, or connect MCP-capable clients. The sandbox lifecycle and execution APIs also provide a foundation for custom runtime integrations.

  Source: README

Quick start

Copied verbatim from the project's README.

uvx opensandbox-server init-config ~/.sandbox.toml --example docker

uvx opensandbox-server

# Show help
# uvx opensandbox-server -h

uv pip install opensandbox

import asyncio

from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox from the alpine image
    sandbox = await Sandbox.create("alpine")

    try:
        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a script file
        await sandbox.files.write_files([
            WriteEntry(
                path="/tmp/hello.sh",
                data="echo \"Hello $1\"\necho '2 + 2 =' $((2 + 2))",
                mode=755,
            )
        ])

        # 4. Read the file back
        content = await sandbox.files.read_file("/tmp/hello.sh")
        print(f"Content: {content}")

        # 5. Execute the script
        execution = await sandbox.commands.run("sh /tmp/hello.sh OpenSandbox")
        for log in execution.logs.stdout:
            print(log.text)

    finally:
        # 6. Cleanup the sandbox
        await sandbox.destroy()

if __name__ == "__main__":
    asyncio.run(main())

Who it may suit

This project may suit developers building coding agents, code interpreters, browser or desktop automation, and agent evaluation systems that require isolated execution environments.

Topics to discuss

• Which agent workloads and evaluation patterns should receive priority in upcoming examples?

• How should sandbox lifecycle, file, and command APIs evolve for custom runtime integrations?

• What security controls and deployment practices should community guides standardize for sandbox workloads?

Written by ReadmeX AI from the project's README, source and public GitHub data; it may contain mistakes.

Read the original README https://github.com/opensandbox-group/OpenSandbox#readme

ReadmeX opened this community for a trending project; it is not run by the project. Maintainers can claim it from the community page.