docs/reference/instances.md

# Instances

Instances are running Chrome processes managed by PinchTab. Each managed instance has:

- an instance ID
- a profile
- a port
- a mode (`headless` or `headed`)
- an execution status

One profile can have at most one active managed instance at a time.

## List Instances

```bash
curl http://localhost:9867/instances
# CLI Alternative
pinchtab instances
# Response
[
  {
    "id": "inst_0a89a5bb",
    "profileId": "prof_278be873",
    "profileName": "work",
    "port": "9868",
    "headless": true,
    "status": "running",
    "startTime": "2026-03-01T05:21:38.27432Z"
  }
]
```

`pinchtab instances` is the simplest way to inspect the current fleet from the CLI.

## Start An Instance

### Primary: Start by profileId and mode

```bash
curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"profileId":"prof_278be873","mode":"headed","port":"9999"}'
# CLI Alternative
pinchtab instance start --profileId prof_278be873 --mode headed --port 9999
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting",
  "startTime": "2026-03-01T05:21:38.27432Z"
}
```

Notes:

- if `profileId` is omitted, PinchTab creates an auto-generated temporary profile such as `instance-...`
- if `port` is omitted, PinchTab allocates one from the configured instance port range

### Alternative: Start by profile name

You can also start an instance using a profile name and headless flag:

```bash
curl -X POST http://localhost:9867/instances/launch \
  -H "Content-Type: application/json" \
  -d '{"name":"work","headless":false}'
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting",
  "startTime": "2026-03-01T05:21:38.27432Z"
}
```

The `POST /instances/launch` endpoint takes:
- `name` — profile name (required)
- `headless` — true for headless mode, false for headed mode (optional, defaults to true)

Port is automatically allocated from the configured instance port range.

## Get One Instance

```bash
curl http://localhost:9867/instances/inst_ea2e747f
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "running",
  "startTime": "2026-03-01T05:21:38.27432Z"
}
```

Common status values:

- `starting`
- `running`
- `stopping`
- `stopped`
- `error`

## Get Instance Logs

```bash
curl http://localhost:9867/instances/inst_ea2e747f/logs
# CLI Alternative
pinchtab instance logs inst_ea2e747f
```

Response is plain text.

## Stop An Instance

```bash
curl -X POST http://localhost:9867/instances/inst_ea2e747f/stop
# CLI Alternative
pinchtab instance stop inst_ea2e747f
# Response
{
  "id": "inst_ea2e747f",
  "status": "stopped"
}
```

Stopping an instance preserves the profile unless it was a temporary auto-generated profile.

## Start By Profile

You can also start an instance from a profile-oriented route:

```bash
curl -X POST http://localhost:9867/profiles/prof_278be873/start \
  -H "Content-Type: application/json" \
  -d '{"headless":false,"port":"9999"}'
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting"
}
```

This route accepts a profile ID or profile name in the path. Its request body uses `headless` rather than `mode`.

## Open A Tab In An Instance

```bash
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pinchtab.com"}'
# Response
{
  "tabId": "8f9c7d4e1234567890abcdef12345678",
  "url": "https://pinchtab.com",
  "title": "PinchTab"
}
```

There is no dedicated instance-scoped `tab open` CLI command today. The CLI shortcut is:

```bash
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
```

That command opens a tab for the instance and then navigates it.

## List Tabs For One Instance

```bash
curl http://localhost:9867/instances/inst_ea2e747f/tabs
# Response
[
  {
    "id": "8f9c7d4e1234567890abcdef12345678",
    "instanceId": "inst_ea2e747f",
    "url": "https://pinchtab.com",
    "title": "PinchTab"
  }
]
```

## List All Tabs Across Running Instances

```bash
curl http://localhost:9867/instances/tabs
```

This is the fleet-wide tab listing endpoint. It is different from `GET /tabs`, which is shorthand/bridge-style and not a fleet-wide inventory.

## List Metrics Across Instances

```bash
curl http://localhost:9867/instances/metrics
```

Use this when you want per-instance memory metrics across all running instances.

## Attach An Existing Chrome

```bash
curl -X POST http://localhost:9867/instances/attach \
  -H "Content-Type: application/json" \
  -d '{"name":"shared-chrome","cdpUrl":"ws://127.0.0.1:9222/devtools/browser/..."}'
# Response
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "shared-chrome",
  "status": "running",
  "attached": true,
  "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}
```

Notes:

- there is no CLI attach command
- attach is allowed only when enabled in config under `security.attach`

## Attach An Existing Bridge

```bash
curl -X POST http://localhost:9867/instances/attach-bridge \
  -H "Content-Type: application/json" \
  -d '{
    "name":"shared-bridge",
    "baseUrl":"http://10.0.12.24:9868",
    "token":"bridge-secret-token"
  }'
# Response
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "shared-bridge",
  "port": "",
  "url": "http://10.0.12.24:9868",
  "status": "running",
  "attached": true,
  "attachType": "bridge"
}
```

Notes:

- `baseUrl` must point at a running PinchTab bridge
- the orchestrator performs a health check before registering it
- `security.attach.allowHosts` must allow the bridge host
- `security.attach.allowSchemes` must include `http` or `https` for bridge attachment