Sessions

Sandbox Sessions

View as Markdown

Sandbox sessions give you a general-purpose Linux environment inside a dedicated microVM. You get shell access, HTTP command execution, file transfer, port forwarding, and optional persistent storage through workspaces.

Create a sandbox session

$# Ephemeral
$chaser sandbox --ephemeral --json
$
$# With a custom OCI image
$chaser sandbox --ephemeral --image ghcr.io/example/dev:latest --json
$
$# Persistent (workspace-backed)
$chaser workspaces create --session-type sandbox --name dev --json
$chaser sandbox --workspace dev --json

Interactive shell

Open an interactive PTY session:

$chaser shell <session_id>

Run a one-shot command:

$chaser shell <session_id> -c "node -v && pwd"

The PTY endpoint is also available over WebSocket at GET /v1/sessions/{id}/pty with mode options: human (default), agent, or exec.

HTTP command execution

Run commands without managing PTY transport:

$# Auto-provision a sandbox and run a command
$curl -sS "$CHASER_API_URL/v1/exec" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"workspace": "dev", "command": "npm ci && npm test"}' | jq
$
$# Run in an existing session
$curl -sS "$CHASER_API_URL/v1/sessions/<session_id>/exec" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"command": "ls -la /workspace", "cwd": "/workspace"}' | jq

See Command Execution for background commands, streaming, and stdin control.

File transfer

Upload and download files through the API or CLI:

$# CLI
$chaser upload <session_id> ./app.js /workspace/app.js
$chaser download <session_id> /workspace/app.js ./app.js
$
$# REST API upload (multipart)
$curl -sS "$CHASER_API_URL/v1/sessions/<session_id>/upload" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -F "path=/workspace/app.js" \
>  -F "file=@./app.js" | jq
$
$# REST API download
$curl -sS "$CHASER_API_URL/v1/sessions/<session_id>/download?path=/workspace/app.js" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  --output ./app.js

File transfer supports files up to 16 MB per operation.

Port forwarding

If your application listens on a port inside the sandbox, access it through:

  • Direct URL: https://<session_id>.chaser.sh/forward/<port>/
  • Path style: https://api.chaser.sh/s/<session_id>/forward/<port>/
  • Local proxy: chaser forward <session_id> <guest_port> [local_port]
$# Start a dev server in the sandbox
$chaser shell <session_id> -c "cd /workspace && npm run dev -- --host 0.0.0.0"
$
$# Open a local proxy to it
$chaser forward <session_id> 3000 8080 --open

Runtime self-test

Run the built-in diagnostic to verify the sandbox environment:

$chaser sessions self-test <session_id> --json

This returns structured details about the runtime: working directory, PATH entries, detected tools (Node, Python, Git, etc.), shell configuration, and Chaser environment markers.

OCI image support

  • Ephemeral sessions accept an image parameter directly on POST /v1/sessions.
  • Persistent sessions inherit the image from their workspace. Set the image when creating the workspace with POST /v1/workspaces.
  • You cannot pass both workspace and image on the same request.

MCP terminal tool

The terminal MCP tool is the recommended way for AI agents to interact with sandboxes. It auto-provisions or reuses a session and supports:

  • command or cmd — run shell commands
  • xml — structured file operations (read_file, write_file, apply_edit, list_files)
$curl -sS "$CHASER_API_URL/v1/mcp" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "jsonrpc": "2.0", "id": 1,
>    "method": "tools/call",
>    "params": {
>      "name": "terminal",
>      "arguments": {"workspace": "dev", "command": "git status"}
>    }
>  }' | jq

The response includes the resolved session_id and workspace_id so follow-up calls can target the same runtime.