Tegoby Attention SpanBlogBook a demo

Protection levels

Updated

A protection level is how strongly this machine's kernel can enforce your rules. Tego picks the highest level your machine and your permissions allow, and every run records the level it had. How this compares with containers and VMs: Five ways to sandbox an AI agent.

On this page

The three levels

  • Basic: no root needed.
  • Plus: needs root; also records which files the agent reads.
  • Max: needs root and one boot setting; every decision is made in the kernel.

The terminal and contracts use the technical names: Basic is tier 1 (landlock), Plus is tier 2 (cgroup) and Max is tier 3 (bpflsm). In v0.1.3 the dashboard shows Plus as Strong and Max as Strongest.

Level Needs What it adds
Basic (tier 1, Landlock) No root. Linux 5.19 or later (or RHEL 9's 5.14), cgroup v2 Landlock and Tego's supervisor enforce file, program and network rules. Records programs, writes and connections.
Plus (tier 2, cgroup) Root, through sudo and a kernel with BTF type information Small kernel programs (BPF) watch the run. The kernel decides network hosts and records file reads too.
Max (tier 3, BPF LSM) Root, and bpf in the kernel's boot list of security modules The kernel's security-module hooks (LSM) make the decisions.

What the words mean:

  • Landlock is a Linux feature that locks a process and its children out of files, with no root.
  • Tego's supervisor is a separate process outside the agent that checks its system calls (through a seccomp filter).
  • BPF programs are small programs loaded into the kernel. LSM hooks are where the kernel asks before it opens a file or starts a program.

At every level the kernel refuses writes and programs outside your rules. Some things differ by level:

  • Reads. Basic does not record file reads by default. Set record: full to record them (every open gets slower), or use Plus.
  • Ask before reading. Holding a file read until you answer works only at Basic.
  • Loosen while it runs. The Adjustable live mode, which lets you loosen a running agent's rules inside a limit you set in advance, needs Plus or Max.
  • CI. tego run works on a hosted CI runner at Basic, with no root, and at Plus through sudo on GitHub's ubuntu-24.04 runner. Max does not, because a hosted runner cannot change the kernel's boot line. Tego has no ready-made CI setup: you add tego run to your workflow and write its contract yourself.

Warning

Granting sudo for tego is granting root. Use Plus and Max on machines whose sudo users are already their administrators. The dashboard never runs as root.

Which level does my machine get?

Shell
tego doctor
sudo "$(command -v tego)" doctor

The first shows what you get without root, the second what you get with it. Each ends with a tier: line naming the level, then a missing for line for each higher level and a fix: line that says what to change.

Out of the box, on common systems:

  • Basic everywhere it runs: any Linux 6.1 or later from a desktop login, RHEL 9, WSL2, Tego's Lima VM on a Mac, and hosted CI.
  • Max with no edit: Debian 13, Fedora, RHEL 9 and 10, Amazon Linux 2023, and Lima's Fedora template. On RHEL 9, the first release (v0.1.0) could not start a contract that declares net.listen at Plus or Max; later releases fix it (see the changelog).
  • Max after one boot line: Ubuntu 24.04 and later, Tego's Lima VM, and older WSL2 kernels.
  • No level at all: Ubuntu 22.04's stock 5.15 kernel. tego run exits with code 125.

On a 6.1 kernel (Debian 12, Amazon Linux 2023's default), Basic still runs, but the kernel enforces no network rule there: Tego's supervisor alone decides each connection. tego doctor prints your kernel's Landlock version.

The Mac and Windows rows are not fully tested yet: Tego's Mac VM has booted on an Apple silicon Mac, and the Windows path has not been run on a real machine. Install has the setup for each.

Run at Plus or Max

Shell
sudo "$(command -v tego)" run agent.yaml

The launcher runs as root for the whole run. The agent runs as you, with your HOME, and the run lands in your own ~/.tego. The dashboard shows a root run once it ends; until then, read it with sudo "$(command -v tego)" status.

To pin one level, add --tier landlock, --tier cgroup or --tier bpflsm. A pinned level the machine cannot give is refused; Tego never falls back to a weaker one.

Turn on Max

Max needs bpf in the kernel's boot list of security modules. Where it is missing, sudo "$(command -v tego)" doctor prints the lsm= value to use, built from the list your machine runs now.

Warning

Use only the lsm= value doctor printed on this machine. A line copied from elsewhere replaces the whole list and can switch off other security modules.

On Ubuntu, put the printed lsm=... into GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, then:

Shell
sudo update-grub
sudo reboot

On an Ubuntu cloud image, a later file overrides /etc/default/grub, so add your own drop-in instead, then run sudo update-grub and reboot:

Shell
echo 'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT lsm=<the list doctor printed>"' | sudo tee /etc/default/grub.d/99-tego-lsm.cfg

On Fedora and RHEL, bpf is usually there already. Where it is not, use sudo grubby --update-kernel=ALL --args="lsm=...".

Inside Tego's Lima VM (Ubuntu 24.04), follow the Ubuntu cloud image steps in the Linux tab, then restart the VM:

Shell
limactl stop tego
limactl start tego

Lima's Fedora template should report tier: bpflsm with no edit.

WSL kernels from 6.18.54.1 (WSL 3.0.3 and later) list bpf from boot. On an older kernel, run wsl --update in PowerShell first.

If you cannot update, set the list in %UserProfile%\.wslconfig, using the value doctor printed (WSL2 has no GRUB, so ignore its GRUB wording):

INI
[wsl2]
kernelCommandLine = lsm=<the list doctor printed>

Then run wsl --shutdown in PowerShell and open your distribution again.

To check it worked, cat /sys/kernel/security/lsm lists bpf, and sudo "$(command -v tego)" doctor ends with tier: bpflsm.

A higher level does not remove Tego's limits: an allowed host is still a way out, and an allowed interpreter can still do anything in its own memory. Security and limits lists them.