Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

The osb CLI is the primary terminal interface for OpenSandbox. Built on top of the OpenSandbox Python SDK, it covers every common workflow — creating and managing sandbox lifecycle, executing commands with foreground streaming or background tracking, reading and writing files, inspecting runtime egress policy, managing the Credential Vault, collecting diagnostics, and installing bundled skills directly into coding agents like Claude, Cursor, and Codex. If you need to automate a sandbox workflow from a script or shell, osb is the shortest path to get there.

​
Installation

Install opensandbox-cli using your preferred Python package manager. All three options install the same osb entry point. 
pip install opensandbox-cli
Confirm the installation: 
osb --help
osb --version

​
Before You Start

The osb CLI connects to a running OpenSandbox server. If you are working locally, start the server before running any osb commands. 
opensandbox-server
See the Server Deployment guide for full setup instructions, including production configuration options.

​
Configuration

Before running sandbox commands, point the CLI at your server and authenticate with an API key. The default config file is ~/.opensandbox/config.toml.
1

Initialize the config file

osb config init
This creates ~/.opensandbox/config.toml with default values.
2

Set the server domain

osb config set connection.domain localhost:8080
3

Set the protocol

osb config set connection.protocol http
Use https for remote or production servers.
4

Set your API key

osb config set connection.api_key <your-api-key>
5

Verify the configuration

osb config show -o json
You should see all four fields reflected in the JSON output.
If you need a non-default config file path, pass --config at the root level for the entire 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
An example ~/.opensandbox/config.toml looks like this: 
[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"

​
Config Resolution Priority

The CLI resolves connection and runtime settings in this order, from highest to lowest priority:
  1. Root CLI flags — --api-key, --domain, --protocol, --request-timeout, --config
  2. Environment variables — OPEN_SANDBOX_API_KEY, OPEN_SANDBOX_DOMAIN
  3. Config file — defaults to ~/.opensandbox/config.toml
  4. SDK defaults — built-in fallback values from the OpenSandbox Python SDK

​
Output Formats

Output format is selected per-command with the -o flag. Not every command supports every format — run <command> --help to see what is available.
FormatDescription
tableHuman-readable tables and panels (default for most commands)
jsonMachine-readable JSON, suitable for scripting and piping
yamlMachine-readable YAML
rawUnformatted text or streaming output (default for command run and file cat)
osb sandbox list -o json
osb sandbox list -o yaml
osb file cat <sandbox-id> /workspace/hello.txt -o raw

​
Available Command Groups

GroupDescription
osb sandboxLifecycle management (create, list, get, kill, pause, resume, renew, health, metrics, endpoint)
osb commandExecute commands, background jobs, persistent shell sessions
osb filecat, write, upload, download, search, info, replace, chmod, rm, mv, mkdir, rmdir
osb egressRuntime egress policy (get, patch rules)
osb diagnosticsStable logs and events by scope
osb devopsLow-level experimental diagnostics (inspect, summary)
osb configInit, show, set config values
osb skillsInstall and manage bundled AI agent skills
osb credential-vaultManage sandbox Credential Vault entries and bindings
Explore any group directly: 
osb sandbox --help
osb command --help
osb file --help
osb skills --help

​
Agent Skills

The CLI ships with five bundled skills that teach coding agents how to use OpenSandbox effectively. Installing a skill writes the skill definition into the agent’s expected location so it is available immediately. Bundled skills:
  • sandbox-lifecycle — creating, inspecting, and cleaning up sandboxes
  • command-execution — running foreground and background commands
  • file-operations — reading and writing sandbox files
  • network-egress — managing egress policy
  • sandbox-troubleshooting — collecting diagnostics and debugging
Supported targets:
TargetInstall 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
Install all bundled skills for a target with a single command: 
osb skills install --all-builtins --target claude --scope global
Or install a specific skill for a specific target: 
osb skills install sandbox-lifecycle --target codex --scope project
Use --scope project to install skills into the current directory (for project-specific agent configuration) or --scope global to install into your home directory for all projects.

Build docs developers (and LLMs) love

Get started for freeTalk to us