# Consoles and network tools API

> Open consoles, run network tools and start, follow and download packet captures through Falak's REST API.

Source: https://falak.sh/docs/api/consoles-and-network/

`{site}` is an id or slug; `{instance}` and `{server}` an id or name. A function site is refused (`422`): functions have no console or network of their own. A site or database target also needs `sites.view` / `databases.view` on the token.

## Consoles

The answer carries a `wss://` relay URL with a single-use ticket valid for 60 seconds; the client dials it and exchanges bytes (binary frames are raw terminal bytes, text frames JSON such as `{"t": "resize", "cols": 120, "rows": 40}`). Every console is a terminal session: audited, recorded and listed under Terminal. `falak console` uses these routes.

All routes answer `409 {"message": "The terminal relay is off on this installation."}` when the relay is off, and `422` on `server` when the server's agent is too old (no `terminal.v2`), offline or not active. Opening is rate limited to 30/minute.

| Method | Path | Body | Permission |
|---|---|---|---|
| POST | `/api/v1/sites/{site}/console` | `{server_id?, service?, cols?, rows?}` | `terminal.open` + `sites.view` |
| POST | `/api/v1/databases/instances/{instance}/console` | `{cols?, rows?}` | `terminal.open` + `databases.view` |
| POST | `/api/v1/servers/{server}/console` | `{user?, cols?, rows?}` | `terminal.open` |
| GET | `/api/v1/sites/{site}/console` | | `terminal.open` + `sites.view` |
| POST | `/api/v1/terminal/sessions/{session}/ticket` | | the session's view permission |
| DELETE | `/api/v1/terminal/sessions/{session}` | | the session's close permission |

```bash
curl -X POST "https://falak.example.com/api/v1/sites/shop/console" \
  -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" -d '{"service": "web"}'
```

```json
{"data": {
  "session_id": "01k…", "url": "wss://falak.example.com/terminal/v1/sessions/01k…?ticket=…", "writable": true,
  "server_id": "01k…", "server_name": "app-1", "target_type": "site", "target_name": "shop",
  "container": "compose:web"
}}
```

- `201` on success. `server_id` picks one of the site's servers (default: the leader); `cols`/`rows` default to 80×24.
- A compose site with several services and no `service` answers `422` on `service`, listing them. A database must be running.
- `GET …/sites/{site}/console` says what a console can open: `{"data": {"servers": [{"id", "name", "leader"}], "services": ["web", "worker"] | null, "runtime": "compose"}}`.
- `…/ticket` returns a new URL for the same session (reconnect): `{"data": {"url", "writable"}}`; `404` once the session is closed. `writable` is false for watchers of a shared session without `terminal.control`.

## Network tools

Need `network.tools`. Rate limited to 10 runs a minute per user, with at most 2 running at once (`429` "Wait for your other network tools to finish.").

| Method | Path |
|---|---|
| POST | `/api/v1/servers/{server}/net-tools` |
| POST | `/api/v1/sites/{site}/net-tools` (also `server_id?`, `service?`) |
| POST | `/api/v1/databases/instances/{instance}/net-tools` |
| GET | `/api/v1/net-tools/runs/{run}?after=<seq>` |

| Field | Tools | Rule |
|---|---|---|
| `tool` | all | `ping`, `traceroute`, `dns`, `http`, `tcp` |
| `target` | ping, traceroute, dns, tcp | A hostname or IP (an IP for a `PTR` lookup) |
| `count` | ping (1–20, default 4), tcp (1–10, default 3) | |
| `max_hops` | traceroute | 1–30, default 20 |
| `record_type`, `nameserver` | dns | `A` `AAAA` `CNAME` `MX` `TXT` `NS` `SRV` `PTR`; an IP |
| `url`, `method`, `connect_to`, `insecure` | http | `http(s)://…` up to 2048 characters; `GET` or `HEAD`; an IP; boolean |
| `port` | tcp | 1–65535 |
| `timeout_s` | all | 1–60, default 30 |

Each tool accepts only its own fields. `POST` answers `201 {"data": Run}`; poll the run with `after` set to the last `seq` you saw until `status` settles:

```json
{"data": {"id": "01k…", "tool": "http", "input": {"url": "https://shop.example.com/health"},
          "target_type": "site", "target_name": "shop", "server_id": "01k…", "server_name": "app-1",
          "container": "…", "command_id": "01k…", "status": "running", "exit_code": null, "error": null,
          "created_at": "…", "finished_at": null, "lines": ["…"], "last_seq": 12}}
```

`status` is `running`, `succeeded`, `failed`, `timed_out` or `cancelled`. A run can be read by its owner or anyone with `network.tools` in the organization. An agent without `net.tools` is refused with `422`.

## Packet captures

Need `network.capture` (also to list, read and download). At most 3 captures in progress and 10 an hour per organization (`429`).

| Method | Path |
|---|---|
| POST | `/api/v1/servers/{server}/net-captures` |
| POST | `/api/v1/sites/{site}/net-captures` (also `server_id?`, `service?`) |
| POST | `/api/v1/databases/instances/{instance}/net-captures` |
| GET | `/api/v1/net-captures?target_type=server\|site\|database&target_id=…` (the last 10) |
| GET | `/api/v1/net-captures/{capture}` |
| POST | `/api/v1/net-captures/{capture}/cancel` |
| GET | `/api/v1/net-captures/{capture}/download` |

Body: `{interface?, duration_s?, max_mb?, full_packets?, filter?: {host?, port?, protocol?, direction?}}`:

| Field | Rule |
|---|---|
| `interface` | `default`, `wireguard` or `docker`; servers and native sites only (containers capture every interface of their namespace) |
| `duration_s` | 1–60, default 30 |
| `max_mb` | 1–100, default 20 |
| `full_packets` | Default false: packet headers (96 bytes, may include the first bytes of a payload) |
| `filter.host` | An IP or CIDR (names are not resolved) |
| `filter.port` | 1–65535 (not with `icmp`) |
| `filter.protocol` | `tcp`, `udp`, `icmp` |
| `filter.direction` | `in`, `out`, `both` |

A capture goes `queued` → `capturing` → `uploading` → `ready` (or `failed`, `cancelled`, `expired`). Once `ready`, `download` streams the pcap (`application/vnd.tcpdump.pcap`); it answers `410` after 24 hours. Starting, cancelling and downloading are audited. An agent without `net.capture` is refused with `422`.
