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.
Consoles
Section titled “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 |
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"}}201on success.server_idpicks one of the site’s servers (default: the leader);cols/rowsdefault to 80×24.- A compose site with several services and no
serviceanswers422onservice, listing them. A database must be running. GET …/sites/{site}/consolesays what a console can open:{"data": {"servers": [{"id", "name", "leader"}], "services": ["web", "worker"] | null, "runtime": "compose"}}.…/ticketreturns a new URL for the same session (reconnect):{"data": {"url", "writable"}};404once the session is closed.writableis false for watchers of a shared session withoutterminal.control.
Network tools
Section titled “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:
{"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
Section titled “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.