Secure, Fast, and Extensible Sandbox runtime for AI agents.
name: command-execution description: Use OpenSandbox command execution commands to run foreground or background processes, inspect tracked execution status and logs, interrupt work, and manage persistent shell sessions inside a sandbox. Trigger when users want to execute commands in a sandbox and need exact OpenSandbox CLI flows.
OpenSandbox Command Execution
Run commands with osb command. Use foreground streaming by default, and add --background when you need tracked execution.
When To Use
- the user wants to run a one-off command in a sandbox
- the user needs a tracked background command with later status/log inspection
- the user wants to stop a running command
- the user wants a persistent shell session that keeps working directory or environment state across runs
Config Gate
Run this first:
osb config show -o json
If domain is missing, stop and set it before command execution:
osb config set connection.domain <host:port> -o json
osb config show -o json
If auth is required and api_key is missing, stop and set it before command execution:
osb config set connection.api_key <api-key> -o json
osb config show -o json
Separator Rule
Use -- before the sandbox command payload. This is required when the payload contains flags like -l, -c, or -m.
osb command run <sandbox-id> -o raw -- sh -lc 'echo ready'
osb command run <sandbox-id> -o raw -- python -m http.server
osb command session run <sandbox-id> <session-id> -o raw -- sh -lc 'pwd'
Execution Modes
Treat these as three distinct execution paths:
osb command runwithout--backgroundUse for foreground one-shot commands when the result should stream directly to the terminalosb command run --backgroundUse when the user needs an execution ID, later status checks, or log retrievalosb command session ...Use when shell state must persist across commands, such as exported variables or a working directory
Golden Paths
Foreground one-shot command:
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
Tracked background command:
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 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
Foreground Commands
For simple one-off execution, use:
osb command run <sandbox-id> -o raw -- <command>
osb command run <sandbox-id> --workdir /workspace -o raw -- <command>
osb command run <sandbox-id> --timeout 30s -o raw -- <command>
Use foreground mode when the user wants immediate output and does not need a tracked execution ID.
Background Commands
Use background mode when the user will need follow-up inspection:
osb command run <sandbox-id> --background -o json -- <command>
osb command run <sandbox-id> --background --workdir /workspace -o json -- <command>
osb command run <sandbox-id> --background --timeout 5m -o json -- <command>
Then inspect the tracked execution:
osb command status <sandbox-id> <execution-id> -o json
osb command logs <sandbox-id> <execution-id> -o json
osb command logs <sandbox-id> <execution-id> --cursor 0 -o json
Use status for lifecycle state and exit information. Use logs for tracked background output. Do not suggest command logs for foreground commands that already streamed to the terminal.
Persistent Sessions
Use sessions when commands must share shell state:
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 run <sandbox-id> <session-id> --workdir /var -o raw -- pwd
osb command session delete <sandbox-id> <session-id> -o json
Rules:
session create --workdirsets the initial working directory for the sessionsession run --workdiroverrides the working directory for that single run only- exported variables and shell state persist across
session runcalls in the same session - delete the session when the user is done; do not leave idle sessions around
Interrupting Work
Interrupt only tracked executions:
osb command interrupt <sandbox-id> <execution-id> -o json
Only suggest interruption when the user explicitly wants to stop work or the process is clearly stuck.
Failure Semantics
- foreground
osb command runstreams output directly and requires-o raw - background
osb command run --backgroundreturns tracked execution metadata and supports structured output - foreground
command runandsession runexit non-zero on an execution error, or when the output stream ends before the command finishes - background
command runexits non-zero without success metadata on an execution error or when the output stream ends before startup confirmation - tracked background commands should be checked with
statusandlogs - if the command failure is caused by an unhealthy sandbox rather than the command itself, switch to
sandbox-troubleshooting
Response Pattern
Structure the answer as:
- exact command to run
- which execution mode it uses
- the next inspection or cleanup command if the workflow continues
Keep command examples concrete and ready to paste.
Minimal Closed Loops
Foreground command with timeout:
osb command run <sandbox-id> --timeout 30s -o raw -- python -c "print(1 + 1)"
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
Background execution with interrupt:
osb command run <sandbox-id> --background -o json -- sh -c "sleep 300"
osb command interrupt <sandbox-id> <execution-id> -o json
osb command status <sandbox-id> <execution-id> -o json
Persistent session with shared shell state:
osb command session create <sandbox-id> --workdir /workspace -o json
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
Per-run working directory override inside a session:
osb command session create <sandbox-id> --workdir /tmp -o json
osb command session run <sandbox-id> <session-id> -o raw -- pwd
osb command session run <sandbox-id> <session-id> --workdir /var -o raw -- pwd
osb command session delete <sandbox-id> <session-id> -o json
Best Practices
- use
osb command run -o raw -- ...for quick foreground commands - use
--backgroundwhen the user will need execution tracking - use sessions only when state persistence is actually needed
- use
--workdirexplicitly when directory context matters - use
--timeoutwhen the command should not run indefinitely - prefer
statusbefore guessing whether a background command is still running or already failed