Permissions and approvals

Several independent limits apply to every tool call, and the strictest one wins. None of them depends on the AI behaving well.

The layers

Your role in the account. Owners and admins manage everything. Members can see machines and connect AI clients. Custom roles grant single permissions, such as approving requests or reading the audit log. A group can claim machines, so only its members reach them.
The connection. When you approve a client, you choose its scopes, the machines it reaches, and its policy.
The policy's command rules and approvals. They decide which commands run, which are refused, and which wait for a person.
The machine's own ceiling. ceiling.toml on the machine caps what any policy can allow there. The agent applies it locally, so not even the gateway can go beyond it.
The operating system account. Commands run as the account the agent or SSH connection uses, with that account's rights.

Policies

A policy belongs to the account and is chosen for each connection. It sets:

Key	What it controls
`shell`	`off`, `sandboxed` (Landlock on Linux, Seatbelt on macOS) or `full`. Windows has `off` and `full`.
`files`	Paths the file tools may use, each read-only or read-write; `*` for all.
`deny`	Paths that look as if they do not exist, for example key files.
`gui`	Screen tools: `off`, `observe` or `act`, optionally for listed apps only.
`tunnel_targets`	Addresses that port forwarding and web shares may reach.
`commands`	Command rules.
`approval`	Approvals: which tools always need one, who approves, and for how long a request waits.

Two policies come with every account: full (shell and files unrestricted, screen off) and read-only (no shell, files read-only, common secret files hidden, screen off). The screen tools are off unless a policy turns them on; until then they are not even listed to the AI.

Command rules

Shell mode (default): rules match commands by pattern, first match wins, and each says allow, deny, approve or confirm. Commands nested inside others ($(…), sudo, bash -c, PowerShell -EncodedCommand) are checked too, and the strictest result wins. A shell is flexible enough that shell-mode rules are a guardrail, not a security boundary.
Allowlist mode: only listed programs run, started directly without a shell, so the list is a hard boundary. Shell sessions and terminals are not available in this mode.
Ready-made rule sets: linux-readonly, windows-readonly, no-destructive, deploy.
Rules are checked by the gateway and again by the agent on the machine.

Independently of any policy, LetKite refuses commands that wipe a system (for example rm -rf /, mkfs or writing to a raw disk) and requires confirm=true for high-risk ones such as a reboot, stopping a service, removing packages or recursive deletion. The AI is told to show you the exact command before it confirms.

Approvals

A call needs a person's approval when a command rule says approve, or when the policy lists the tool under approval.tools. Tools that can require approval: exec, exec_many, shell_run, job_start, write_file, delete_path, copy_between_hosts, transfer_start, gui_act, tunnel_open, terminal_open, wake_node, wake_device.

Who approves: the person who connected the AI (owners and admins can too), any admin, or another person than the one who asked (four eyes).
How: the approver gets a link by email and, if they installed the LetKite web app, as a push notification on their phone. Approving needs a passkey or an authenticator code; denying does not.
Exactly what was asked: an approval covers one request, the same tool, machine and arguments, and can be used once.
Expiry: 10 minutes by default (1 minute to 24 hours, set in the policy). At most 20 requests per connection wait at a time.

While a call waits, the AI client gets a message saying who was asked and until when, and is told to tell you. It can wait with the approval_wait tool and then repeat the call with exactly the same arguments. A denied request must not be retried.

The machine's ceiling

Each machine has a local file that only its administrator can edit: /etc/letkite/ceiling.toml on Linux and macOS, %ProgramData%\letkite\ceiling.toml on Windows. It caps the shell, files, hidden paths, screen access, port forwarding and more on that machine. The agent checks every request against it, so the machine's owner keeps the last word even if the gateway were compromised.