Tools

list_hosts List hosts Read-only

List every host in the fleet: node_id, alias, address, user, tags, scopes, notes.

Entry point for every other tool. Their host argument takes an alias or a node_id, never a bare IP. Aliases may repeat; if one is ambiguous the call fails and lists the candidate node_ids. Read-only.

host_facts Host facts Read-only

Collect basic facts: distro, kernel, load, memory, disk, current user, containers.

Run this before doing real work on a host so you do not send Debian commands to Alpine, or assume you are root. Read-only: a fixed set of probes that change nothing; needs fleet.read.

fleet_status Gateway status Read-only

Show the gateway's own state: SSH pool, shell sessions, log subscriptions, tunnels.

Read-only; lists this connection's handles only; needs fleet.read.

exec Run command Destructive

Run one command on one host and wait for the result.

For work measured in seconds to a couple of minutes. Anything longer (builds, backups, large transfers) belongs in job_start, which survives SSH disconnects. Each call is a fresh process: cd and export do not carry over. Use shell_open when you need that state.

Side effects are whatever the command does. Needs fleet.exec; the connection's command rules and approvals apply (a high-risk command needs confirm=true). Output is capped (32 KB by default) and the timeout clamped (60 s by default, 900 s at most).

Batch several steps into one command rather than making many round trips.

exec_many Run command on many hosts Destructive

Run the same command on several hosts concurrently.

Use this for sweeps instead of looping over exec. One host failing does not stop the others. Same side effects and checks as exec on every target: the command rules check every target before any runs, and one approval covers the sweep. At most 8 hosts by default; each host's output is capped at half of exec's.

shell_open Open shell session Opens or closes a session

Open a persistent shell session; cwd, variables and functions persist.

bash on SSH hosts; on agent nodes the node's shell (PowerShell on Windows). For continuous debugging: cd somewhere, source an env, activate a venv, then keep working. Close it with shell_close; idle sessions are reaped after 30 min. Starts a shell process and runs nothing else; needs fleet.exec; at most 4 sessions per host; refused when the command rules are an allowlist.

shell_run Run in shell session Destructive

Run a command in an open session; returns exit code, merged output and cwd.

A command inside a session cannot be interrupted on its own: a timeout destroys the session. Use job_start for long work. Side effects are whatever the command does; needs fleet.exec, and the command rules, approvals and output cap of exec apply.

shell_close Close shell session Opens or closes a session

Close a persistent shell session and end its shell process. Needs fleet.exec.

list_dir List directory Read-only

List a remote directory: type, size, mode, mtime. Optionally recursive.

Read-only; needs fleet.read. Recursion goes 4 levels deep at most and the answer holds at most 2000 entries.

read_file Read file Read-only

Read a remote file. Text is decoded as UTF-8; set binary=true for base64.

Read-only; needs fleet.read. Returns at most max_bytes per call, never more than the gateway's file limit (4 MB by default); continue from next_offset.

write_file Write file Destructive

Write a remote file: create, overwrite or append; parent directories are created.

Overwrites are backed up next to the file (<path>.bak-<time>) unless backup=false. Needs fleet.write and may need a person's approval; content is limited to the gateway's file limit (4 MB by default).

Config edits: read_file, write_file with backup, validate with exec (nginx -t, sshd -t), then reload.

delete_path Delete path Destructive

Delete a remote file, or a directory tree with recursive=true.

Irreversible: nothing is backed up. Requires confirm=true and fleet.write, and may need a person's approval; refuses system directories (/, /etc, /usr, /home, ...).

copy_between_hosts Copy file between hosts Destructive

Copy a file between two hosts through the gateway.

Replaces the destination file without a backup. Needs fleet.read on the source and fleet.write on the destination; the file must fit the gateway's file limit (4 MB by default). For large files use transfer_start between agent nodes, or exec with rsync/scp directly between the hosts.

transfer_start Start file transfer Destructive

Copy a file or a whole directory between two agent nodes, of any size.

Runs in the background through the gateway; returns when done or after wait_s with a transfer_id (follow it with transfer_status). Each file appears at its target only complete and checked (SHA-256); links are skipped. Writes on the destination node and replaces files already there only with overwrite=true. Both nodes' policies apply: read (fleet.read) at the source, write (fleet.write) at the destination. For SSH hosts use copy_between_hosts or rsync with exec.

transfer_status Transfer status Read-only

Show a transfer's progress: files and bytes done, rate, what failed or was skipped.

Read-only; optionally waits up to wait_s for the transfer to finish.

transfer_cancel Cancel transfer Destructive

Stop a transfer. Files already finished stay; the one in progress does not appear.

job_start Start background job Destructive

Start a detached job on the node and return a job_id immediately.

The job outlives the SSH connection, the gateway restart and this conversation. stdout/stderr land in ~/.letkite/jobs/<job_id>/ on the node. Use this for builds, backups, bulk transfers, benchmarks. Side effects are whatever the command does; needs fleet.exec, and the command rules and approvals of exec apply.

job_status Job status Read-only

Show a job's state: running / finished / aborted, plus exit code and output sizes.

Omit job_id to list every job on the host. Read-only; needs fleet.read.

job_output Read job output Read-only

Read a job's stdout or stderr. Returns next_offset for a gap-free incremental follow-up.

Read-only; needs fleet.read; at most 32 KB per call by default.

job_kill Kill job Destructive

Send a signal (TERM by default) to the job's whole process group.

Usually ends the job and everything it started. Needs fleet.exec.

job_purge Purge job Destructive

Delete a finished job's directory and logs. Running jobs are left alone.

Its output cannot be read afterwards. Needs fleet.write.

log_open Open log subscription Opens or closes a session

Start collecting a log on the gateway; read it later with log_read.

Subscribe first, trigger something with exec, then read what appeared. That ordering is not possible with exec alone. On a Windows agent node a channel gives one line per event: time, level, provider, id and message. Starts a tail (journalctl, logread, an event log reader) on the node and changes nothing else; needs fleet.read. Close it with log_close.

log_read Read log lines Read-only

Read new log lines. dropped_lines > 0 means the ring buffer overflowed.

Read-only; needs fleet.read; at most 2000 lines per call.

log_close Close log subscription Opens or closes a session

Close a subscription and kill the remote tail/journalctl.

tunnel_open Open tunnel Opens or closes a session

Forward a node-local port to the gateway.

Pair with tunnel_http to reach admin interfaces bound to 127.0.0.1 on the node (Grafana, Prometheus, pprof, database HTTP gateways), or a device on the node's network. On agent nodes the node's ceiling.toml (tunnel_targets) and this connection's policy decide which addresses and ports are reachable; a refusal says so. The gateway listens on its own loopback only and closes the tunnel after 1 hour; needs fleet.admin and may need a person's approval.

tunnel_http HTTP through tunnel Destructive

Send one HTTP request through an open tunnel; returns status, headers and body.

Any method goes: a POST, PUT or DELETE changes whatever the service behind the tunnel does with it. Needs fleet.admin; the body read back is cut at 32 KB by default.

tunnel_close Close tunnel Opens or closes a session

Close a tunnel; requests through it stop working. Needs fleet.admin.

wake_node Wake node Destructive

Wake a sleeping agent node with Wake-on-LAN, through another node of the account.

The other node must be online on the same network (same subnet, same public address) and the sleeping machine's network card set to wake on a magic packet. Powers the machine on; needs fleet.exec on it and may need a person's approval.

wake_device Wake LAN device Destructive

Wake a machine with no agent (a NAS, a PC) by Wake-on-LAN.

via sends the magic packet to the broadcast address of one of its own networks. Nothing confirms the machine woke: check it after a minute, e.g. exec ping on via. Its card must be set to wake on a magic packet. Needs fleet.exec on via and may need a person's approval.

approval_wait Wait for approval Read-only

Wait for a person to approve or turn down a call that needs approval.

Approved: call the same tool again with exactly the same arguments; the approval is for that call, once. Turned down or expired: do not retry, ask the user instead. Read-only: it only reports the decision.

audit_tail Audit log tail Read-only

Tail the gateway audit log: who ran what, where, when (newest last).

Read-only; needs fleet.admin; at most 500 records per call. The gateway's own records are all there; the sign-in service's may arrive up to 100 ms late.

schedule_create Create schedule Destructive

Run a command on a node on a schedule, e.g. a backup every night.

Every run starts the command as a detached job, with the same effects as job_start; needs fleet.exec and a plan that includes schedules. Runs under this connection: its policy, command rules and approvals apply at every run (a command that needs a person's approval asks at each run and is skipped if nobody approves). Revoking the connection stops it. Failed and missed runs are emailed to the user. Tell the user what you scheduled and when it next runs.

schedule_list List schedules Read-only

List the schedules this connection made, with their next and last run.

schedule_delete Delete schedule Destructive

Remove a schedule this connection made; no further runs, a run in progress finishes.

schedule_runs Schedule run history Read-only

List a schedule's recent runs: when, how (woken?), exit code, the end of the output.

Also says why a run failed, was missed or skipped. Read-only.

share_create Create web share Opens or closes a session

Publish a web service running on a node at an https address, for this account.

A dev server or an admin page, for the people of this account: they sign in to open it. No ports opened on the node's router. The policy's tunnel_targets and the node's ceiling decide what can be shared; the person who connected you needs the permission shares.create there, and it may need a person's approval. Delete it with share_delete when done; it expires by itself after hours (24 by default, 30 days at most).

share_list List web shares Read-only

List the web shares this connection created.

share_delete Delete web share Destructive

Take a web share down: its address stops answering at once.

terminal_open Open terminal Destructive

Open an interactive terminal (a shell on a pseudo-terminal) on a node.

For programs that need one: prompts that ask, menus, sign-ins (gh auth login), REPLs, top, less. Prefer exec or shell_run for plain commands. Give command= to start one right away. Type with terminal_send, close with terminal_close. Starts a shell, and with command= runs that command at once (command rules and approvals apply as for exec); needs fleet.exec; at most 8 terminals per connection; refused when the command rules are an allowlist.

Each answer has the output since the last call and, when the program looks like it asks something, waiting_for: {kind: choice | confirm | password | device_code | text, prompt, ...} with how to answer.

terminal_send Type into terminal Destructive

Type into a terminal and return what it printed since the last call.

Returns once the output stops with the cursor after a prompt (or a menu) on screen, or with until once that text shows up. waiting_for says what the program asks, if it asks. Keystrokes act as typed (enter runs a command, ctrl+c interrupts); typed text passes the command rules and approvals; needs fleet.exec.

terminal_read Read terminal output Read-only

Show what a terminal printed since the last call, without typing.

With until, wait for it: a sign-in finishing, a build printing "done". Read-only; needs fleet.read.

terminal_ask Ask person to type Destructive

Hand the program's next answer to the person who connected you.

A password, a passphrase, a one-time code, anything that should not pass through the conversation. They get a notification (phone, email) and type it in the LetKite console; it goes into the terminal followed by enter. You get what the program printed after it and how many characters were typed, never the text (masked if the program shows it). Needs fleet.exec.

Waits for them up to wait_ms, sending progress meanwhile; if they have not answered by then, call terminal_ask again to keep waiting for the same request (it stays open 15 minutes). Tell the user in the conversation that the console is waiting for them.

terminal_resize Resize terminal Opens or closes a session

Change a terminal's size; full-screen programs redraw.

terminal_close Close terminal Destructive

Close a terminal; its shell and what runs in it end. Needs fleet.exec.

gui_observe Observe screen Read-only

Listed only when the connection's policy turns the screen tools on.

Look at a window on an agent node (Windows), or the whole screen: who and what is on it.

The tree lists elements with short ids (e3) to use in gui_act; prefer it to images, which cost far more context. The first line says whether the desktop is active, locked or taken over at the machine. Read-only: nothing on the desktop changes; needs the connection's gui level observe or act.

gui_zoom Zoom into screen Read-only

Listed only when the connection's policy turns the screen tools on.

Capture part of a window (or of the screen) at its own resolution, to read small text.

Read-only; same permission as gui_observe.

gui_act Act on screen Destructive

Listed only when the connection's policy turns the screen tools on.

Click, type and press keys in a window on an agent node, by element ids from gui_observe.

Points in an image gui_observe sent work too. This acts as a person at the machine would: whatever a click or keystroke does (send, delete, close) happens. Needs the connection's gui level act and may need a person's approval.

Batch the steps of one task; waiting happens on the node ({"wait": ..}), so there is no need to observe in between. Returns what changed.