GizStack
View .mdOpen in ChatGPTOpen in Claude

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

  1. Layers
  2. Places
  3. A conversation's scope
  4. Access levels
  5. Commands
  6. Approvals
  7. Other computers
  8. What it does not keep
  9. Code and tests

Layers

LayerWho keeps itWhat it keeps
PlacesThe Desk (desk/places.giz)The folders of the computer that agents may reach at all.
ScopeThe Desk, per conversationWhich places one conversation reaches, and its access level.
File toolsThe Drive API (desk/drive.giz)Reads and changes of files, with versions and a trash, inside the scope.
CommandsThe system (runtime/isolate.c)What a shell command reads, writes and reaches on the network.
ApprovalsThe 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 folders tool lists them.
  • search and read find and read the files of the scope only.

Access levels

LevelFile toolsCommands on this computerApproval
readRead 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.
fullAs 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:

SystemFilesNetwork at read
LinuxLandlock: 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.
macOSThe sandbox profile: writes only in the allowed folders; reads every file.The profile refuses IP connections.
WindowsLow 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 read and work a 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 at read.
  • 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

PartCodeTests
Places, scope, confined commandsdesk/places.giz, desk/places.ghtmltests/desk/places.test.giz
File tools in a scopedesk/drive.giztests/desk/places.test.giz, tests/desk/drive.test.giz
Hosts and their toolsdesk/hosts.giztests/desk/accounts.test.giz
Confinementruntime/isolate.ctests/desk/places.test.giz (Linux), tests/browser/renderer.test.giz