The SDK provides a unified interface to run AI coding agents in sandboxed containers or locally, with full PTY support, multiple provider backends, and a built-in serve mode for remote sessions.
| Flag | Short | Description | Takes Value |
|---|---|---|---|
| --agent | Agent name (enables sandboxed agent mode) | Yes | |
| --branch | -b | Git branch to clone | Yes |
| --cwd | Working directory | Yes | |
| --dry-run | Simulate execution without making changes | No | |
| --emit-session | -e | Emit session ID to stdout | No |
| --help | -h | Show help message | No |
| --host-port | Host server port (default: auto) | Yes | |
| --image | -i | Container image (default: scorpiox base image) | Yes |
| --local | Run agent locally on host (no container sandbox) | No | |
| --net | -n | Use host networking (no isolation) | Yes |
| --pat | Personal access token for private repos | Yes | |
| --port | Map host port H to container port C (repeatable, H+ for auto) | No | |
| Print mode: forkpty → sx --headless, monitor + print (container) | No | ||
| --prompt | Initial prompt to send to agent | Yes | |
| --provider | -p | Provider: scorpiox, claude_code, gemini, openai, anthropic | Yes |
| --repo | -r | Repository URL to clone into the session | Yes |
| --serve | Start scorpiox-host + sx with real PTY | No | |
| --session-id | Resume or attach to an existing session | Yes | |
| --sx-branch | Scorpiox build branch (default: from dist.scorpiox.net) | Yes | |
| --tui | Launch with TUI interface | Yes | |
| --version | -v | Show version information | No |
| --volume | Bind-mount a host path into the container | Yes | |
| -m | Model name to use for the provider | Yes |
# Run an agent in a sandboxed container (default mode) scorpiox-sdk --agent my-agent --repo https://github.com/user/project.git
# Run locally without container isolation scorpiox-sdk --agent my-agent --local --cwd /home/user/project
# Start in serve mode with PTY for remote sessions scorpiox-sdk --serve --host-port 8080
# Use a specific provider and model scorpiox-sdk --agent builder -p anthropic -m claude-sonnet-4-20250514
# Clone a private repo with PAT and a specific branch scorpiox-sdk --agent deploy-bot --repo https://git.example.com/org/app.git \ --pat ghp_xxxxxxxxxxxx -b feature/deploy
# Map ports for a web dev agent (host 3000+ auto-assigns, container 3000) scorpiox-sdk --agent web-dev --repo https://github.com/user/webapp.git \ --port 3000+:3000 --port 5432:5432
# Print mode — headless run, output streamed to stdout scorpiox-sdk --agent ci-bot --print --prompt "Run all tests and fix failures"
# Resume an existing session scorpiox-sdk --session-id abc123-def456 --emit-session
# Dry-run to preview what would happen scorpiox-sdk --agent my-agent --repo https://github.com/user/project.git --dry-run
# Use a custom container image with mounted volume scorpiox-sdk --agent builder -i my-registry/custom-image:latest \ --volume /data/models:/models