Agent isolation
An agent of GizDesk reads and changes files and runs commands on the person's computer. This document is the one description of what keeps it to what the person gave it, and of what does not. How the runtime confines a process is in System: Confinement.
Contents
- Layers
- Places
- A conversation's scope
- Access levels
- Commands
- Approvals
- Other computers
- What it does not keep
- Code and tests
Layers
| Layer | Who keeps it | What it keeps |
|---|---|---|
| Places | The Desk (desk/places.giz) | The folders of the computer that agents may reach at all. |
| Scope | The Desk, per conversation | Which places one conversation reaches, and its access level. |
| File tools | The Drive API (desk/drive.giz) | Reads and changes of files, with versions and a trash, inside the scope. |
| Commands | The system (runtime/isolate.c) | What a shell command reads, writes and reaches on the network. |
| Approvals | The agent's policy (desk/model.giz) | Which tool calls wait for the person. |
Each layer is the only owner of its rule. A command is not checked by the Desk's code: the system refuses what the scope does not allow, so a command that the agent writes cannot get around it.
Places
A place is a Drive of the Desk:
- Giz Drive, the Desk's own Drive, in
~/Giz Drive(GIZDESK_FILES). It is always first. - A folder of this computer that the person gave on the Drive page (Folders of this
computer): any absolute path, read and changed (
folder) or read only (readonly). A folder that is a place already, holds one or is in one is refused.
A place is a Drive record, so its view, search, versions (.giz/ inside the folder), trash,
share links and S3 access are those of every Drive. Removing a place keeps its folder and files.
In a place read only, every reader is a viewer: the Drive API refuses each change, and a share
link into it reads only, whatever role it was made with.
A conversation's scope
Each conversation (table chats) has folders, the Drive ids of its places separated by
spaces ("" is every place), and access. The person sets both with the folder button beside the
message box; a new conversation takes the last choice, and a branch takes its parent's.
- A relative path is in the first place of the scope. Commands start there.
- An absolute path must be inside one of the places; any other path is refused.
- A place that no longer exists is left out. A scope left with none has every place.
- The agent is told its folders and access level, and the
folderstool lists them. searchandreadfind and read the files of the scope only.
Access levels
| Level | File tools | Commands on this computer | Approval |
|---|---|---|---|
read | Read the places. | Read every file, change none, reach no network. | None. |
work (default) | Read, and change the places that are not read only. | Change only those places and the temporary folders. | None. |
full | As work. | Run as the person, with no limit. | Each command. |
The temporary folders are /tmp, /var/tmp, /dev/shm, the terminal and null devices and
~/.cache (~/Library/Caches on macOS), so compilers and package tools work; on Windows,
%LOCALAPPDATA%\Temp\Low, which TEMP and TMP name for the command.
Commands
run_command runs a command in the shell of the system: powershell.exe -NoProfile -Command
on Windows, /bin/sh -lc elsewhere. It runs in the first place of the scope, for at most 600 s,
and answers at most 1 MiB of output.
At read and work the Desk starts the shell with SpawnOptions.confined of
Confinement. The runtime confines the child before the shell starts, so
the shell and all that it starts are confined:
| System | Files | Network at read |
|---|---|---|
| Linux | Landlock: writes only in the allowed folders; reads every file. A kernel before 5.13 has no Landlock and confines no files. | seccomp refuses IPv4 and IPv6 sockets. |
| macOS | The sandbox profile: writes only in the allowed folders; reads every file. | The profile refuses IP connections. |
| Windows | Low integrity: writes only in the allowed folders, which are labeled Low only while the command runs; reads every file. | Not refused: the network stays. |
If the process cannot be confined, the command does not run (exit 71). On Windows a command stopped at its limit is ended with its job, and the Desk's runtime takes the Low labels away.
Approvals
The agent's permission policy (Permissions, Assistant.approve) decides which tool calls wait
for the person; a write tool waits under Create with approval and All tools. On top of it,
run_command always waits at full, and run_on_host always waits. There is no second
approval setting.
Other computers
Connections → Computers adds SSH hosts (desk/hosts.giz). list_hosts lists them and
run_on_host runs a command there as that host's account, in its folder. No scope applies
there, so every such command waits for the person's approval.
What it does not keep
- Reads. At
readandworka command can read every file the person can, such as~/.ssh. Only the places limit what the file tools read. - The network at
work. A command may reach the network; on Windows also atread. - Compute. CPU, memory and the number of processes are not limited; the bounds are 600 s and 1 MiB of output.
- Old kernels. On Linux before 5.13 files are not confined.
- What a model is sent. Files the agent reads go to its model's provider.
For untrusted code at a service's scale, use a separate sandbox with compute limits (Isolation and Resource limits are the runtime's own).
Code and tests
| Part | Code | Tests |
|---|---|---|
| Places, scope, confined commands | desk/places.giz, desk/places.ghtml | tests/desk/places.test.giz |
| File tools in a scope | desk/drive.giz | tests/desk/places.test.giz, tests/desk/drive.test.giz |
| Hosts and their tools | desk/hosts.giz | tests/desk/accounts.test.giz |
| Confinement | runtime/isolate.c | tests/desk/places.test.giz (Linux), tests/browser/renderer.test.giz |