Skip to content

README.md

Latest commit

 

History

History
365 lines (265 loc) · 8.03 KB

README.md

File metadata and controls

365 lines (265 loc) · 8.03 KB

OpenSandbox CLI

osb is the command-line interface for OpenSandbox. It is built for the common day-to-day flows:

  • create and manage sandboxes
  • run commands inside a sandbox
  • read and modify sandbox files
  • inspect runtime egress policy
  • collect low-level diagnostics
  • install OpenSandbox-specific skills for coding agents

It uses the OpenSandbox Python SDK under the hood and is intended to be the shortest path from a terminal to a working sandbox workflow.

Install

Choose one:

pip install opensandbox-cli
uv tool install opensandbox-cli
pipx install opensandbox-cli

Confirm the install:

osb --help
osb --version

Before You Start

Make sure an OpenSandbox server is reachable. If you are running locally, start the server first and then point the CLI at it.

opensandbox-server

Quick Start

1. Initialize config

osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config show -o json

If you want a non-default config file, choose it at the root command level for the whole invocation:

osb --config /tmp/dev.toml config init
osb --config /tmp/dev.toml config set connection.domain localhost:8080
osb --config /tmp/dev.toml config show -o json

2. Create a sandbox

osb sandbox create --image python:3.12 --timeout 30m -o json

If you set defaults first, later create commands can be shorter:

osb config set defaults.image python:3.12
osb config set defaults.timeout 30m
osb sandbox create -o json

3. Verify it is usable

osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json

4. Run a command inside the sandbox

Use -- before the sandbox command payload.

osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

5. Read or write a file

osb file write <sandbox-id> /workspace/hello.txt -c "hello" -o json
osb file cat <sandbox-id> /workspace/hello.txt -o raw

6. Clean up

osb sandbox kill <sandbox-id> -o json

Common Tasks

Create sandboxes

Basic:

osb sandbox create --image python:3.12

Private image:

osb sandbox create \
  --image my-registry.example.com/team/app:latest \
  --image-auth-username alice \
  --image-auth-password <token>

Manual cleanup mode:

osb sandbox create --image python:3.12 --timeout none

Explicit entrypoint argv:

osb sandbox create \
  --image python:3.12 \
  --entrypoint python \
  --entrypoint -m \
  --entrypoint http.server

Create with network policy and volumes:

osb sandbox create \
  --image python:3.12 \
  --network-policy-file network-policy.json \
  --volumes-file volumes.json

List and inspect sandboxes

osb sandbox list
osb sandbox list -o json
osb sandbox list --state running --state paused
osb sandbox get <sandbox-id> -o json
osb sandbox metrics <sandbox-id>
osb sandbox metrics <sandbox-id> --watch -o raw

Expose a service

osb sandbox endpoint <sandbox-id> --port 8080 -o json

Run commands

Foreground streaming:

osb command run <sandbox-id> -o raw -- sh -lc 'echo ready'

Tracked background execution:

osb command run <sandbox-id> --background -o json -- sh -c "sleep 10; echo done"
osb command status <sandbox-id> <execution-id> -o json
osb command logs <sandbox-id> <execution-id> -o json

Persistent shell session:

osb command session create <sandbox-id> --workdir /workspace -o json
osb command session run <sandbox-id> <session-id> -o raw -- pwd
osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
osb command session delete <sandbox-id> <session-id> -o json

Work with files

osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
osb file download <sandbox-id> /workspace/result.json ./result.json -o json
osb file search <sandbox-id> /workspace --pattern "*.py" -o json
osb file info <sandbox-id> /workspace/main.py -o json
osb file replace <sandbox-id> /workspace/app.py --old old --new new -o json
osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json

Manage runtime egress policy

Inspect current policy:

osb egress get <sandbox-id> -o json

Patch specific rules:

osb egress patch <sandbox-id> --rule allow=pypi.org --rule deny=internal.example.com -o json

If you are debugging connectivity, verify behavior with an actual command:

osb command run <sandbox-id> -o raw -- curl -I https://pypi.org

Collect diagnostics

These commands are experimental and return plain text.

osb devops summary <sandbox-id> -o raw
osb devops inspect <sandbox-id> -o raw
osb devops events <sandbox-id> --limit 100 -o raw
osb devops logs <sandbox-id> --tail 500 -o raw
osb devops logs <sandbox-id> --since 30m -o raw

Output Formats

Output selection is command-scoped, not global.

  • table: human-readable tables and panels
  • json: machine-readable JSON
  • yaml: machine-readable YAML
  • raw: unformatted text or streaming output

Examples:

osb sandbox list -o json
osb sandbox list -o yaml
osb file cat <sandbox-id> /workspace/hello.txt -o raw

Not every command supports every format. Use --help on the specific command when in doubt.

Command Groups

The main command groups are:

  • osb sandbox: lifecycle management
  • osb command: command execution and persistent sessions
  • osb file: file and directory operations
  • osb egress: runtime egress policy
  • osb devops: experimental diagnostics
  • osb config: local CLI configuration
  • osb skills: bundled skills for AI tools

Explore them directly:

osb sandbox --help
osb command --help
osb file --help
osb skills --help

Agent Skills

The CLI ships with built-in OpenSandbox skills for coding agents and agent-oriented tools.

Bundled skills:

  • sandbox-lifecycle
  • command-execution
  • file-operations
  • network-egress
  • sandbox-troubleshooting

Supported targets:

Target Install location
claude ./.claude/skills/ or ~/.claude/skills/
cursor ./.cursor/rules/ or ~/.cursor/rules/
codex ./.codex/skills/<name>/SKILL.md or ~/.codex/skills/<name>/SKILL.md
copilot ./.github/copilot-instructions.md or ~/.github/copilot-instructions.md
windsurf ./.windsurfrules or ~/.windsurfrules
cline ./.clinerules or ~/.clinerules
opencode ./.agents/skills/<name>/SKILL.md or ~/.agents/skills/<name>/SKILL.md

Common flows:

osb skills list
osb skills show sandbox-lifecycle
osb skills install sandbox-lifecycle --target codex --scope project
osb skills install --all-builtins --target codex --scope global
osb skills uninstall sandbox-troubleshooting --target claude --scope global

For scripts or agents, use structured output:

osb skills install sandbox-lifecycle --target codex --scope project -o json

Configuration Model

The CLI resolves configuration in this order:

  1. root CLI flags such as --api-key, --domain, --protocol, --request-timeout, --config
  2. environment variables such as OPEN_SANDBOX_API_KEY and OPEN_SANDBOX_DOMAIN
  3. config file, defaulting to ~/.opensandbox/config.toml
  4. SDK defaults

Config commands:

osb config init
osb config show
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set defaults.image python:3.12
osb config set defaults.timeout 30m

Example config file:

[connection]
api_key = "your-api-key"
domain = "localhost:8080"
protocol = "http"
request_timeout = 30
use_server_proxy = false

[output]
color = true

[defaults]
image = "python:3.12"
timeout = "30m"

Development

For local development in this monorepo:

cd cli
uv sync
uv run osb --help
uv run pytest

This repository uses a local uv source override for the OpenSandbox Python SDK, so running from cli/ will resolve against the checked-out SDK in the monorepo.