Skip to content

Consoles and network tools API

{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.

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
Terminal window
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"}'
{"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.

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:

{"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.

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.