# Command Execution

Chaser provides multiple ways to run commands in sandbox sessions, from simple one-shot execution to long-running background processes with streaming output.

## Auto-spawn exec

`POST /v1/exec` is the simplest way to run a command. It provisions a sandbox automatically (or reuses an existing one for workspace-backed requests) and returns the output.

```bash
# Run on a persistent workspace
curl -sS "$CHASER_API_URL/v1/exec" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "my-project", "command": "npm test"}' | jq

# Run on an ephemeral sandbox
curl -sS "$CHASER_API_URL/v1/exec" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ephemeral": true, "command": "python3 -c \"print(42)\""}' | jq

# Run with a custom image
curl -sS "$CHASER_API_URL/v1/exec" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ephemeral": true, "image": "node:20-bookworm", "command": "node -v"}' | jq
```

**Response fields (foreground):** `exit_code`, `output`, `output_truncated`

## In-session exec

`POST /v1/sessions/{id}/exec` runs a command in an already-running sandbox. Use this when you want to reuse an existing session.

```bash
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",
    "env": {"NODE_ENV": "production"}
  }' | jq
```

Optional fields: `cwd` (working directory), `env` (environment variables), `timeout_ms`, `background`.

## Background commands

Set `background=true` to start long-running processes without blocking the HTTP response. You get back a `command_id` and `pid` to manage the process.

```bash
# Start a background process
curl -sS "$CHASER_API_URL/v1/sessions/$SESSION_ID/exec" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm run dev", "cwd": "/workspace", "background": true}' | jq
```

### Manage background commands

| Endpoint | Description |
|----------|-------------|
| `GET /v1/sessions/{id}/commands` | List all commands in the session |
| `GET /v1/sessions/{id}/commands/{command_id}` | Get status and output of a specific command |
| `GET /v1/sessions/{id}/commands/{command_id}/stream` | Stream output via Server-Sent Events |
| `POST /v1/sessions/{id}/commands/{command_id}/stdin` | Send input to the process |
| `POST /v1/sessions/{id}/commands/{command_id}/kill` | Send a signal to the process |

### Stream output

```bash
curl -N "$CHASER_API_URL/v1/sessions/$SESSION_ID/commands/$COMMAND_ID/stream?from=0&interval_ms=500" \
  -H "Authorization: Bearer $CHASER_API_KEY"
```

### Send input and signals

```bash
# Send stdin
curl -sS "$CHASER_API_URL/v1/sessions/$SESSION_ID/commands/$COMMAND_ID/stdin" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "q\n"}' | jq

# Send SIGTERM
curl -sS "$CHASER_API_URL/v1/sessions/$SESSION_ID/commands/$COMMAND_ID/kill" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "TERM"}' | jq
```

## CLI one-shot

```bash
chaser shell <session_id> -c "python3 -c 'print(42)'"
```

## PTY WebSocket

For interactive terminal access, upgrade to a WebSocket:

```
GET /v1/sessions/{id}/pty?mode=human
```

Mode options: `human` (full interactive shell), `agent` (agent-optimized PTY), `exec` (non-interactive exec transport).

## MCP terminal tool

The `terminal` MCP tool wraps sandbox execution with session auto-provisioning:

```bash
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": "my-project", "command": "npm test"}
    }
  }' | jq
```

## Jobs

For queued, retriable command execution, use the jobs API with `sandbox.exec` or `pipeline.run`:

```bash
chaser jobs exec --workspace my-project "npm ci && npm test" --wait --json
```

See [Jobs](/docs/platform/jobs) for scheduling, pipelines, and other job kinds.