Skip to content
GurtOS docs

Architecture

GurtOS is an operating system for a computer whose main users are AI agents. It runs on Ubuntu 24.04. Everything that makes it GurtOS is one service, the core, plus a handful of system parts around it: the box's own screen, first-boot setup, and whole-system updates.

This page names the parts and how they talk to each other. The pages after it explain each part in depth.

Architecture Your devices reach the box service's API. The box service runs as root and holds the API, the action log, the apps, the vault, a broker for each task and the network proxy. SpacetimeDB mirrors live state. Each task runs as its own Linux user and reaches the core only through its broker socket and the outside world only through the proxy. Portal in a browser The box's screen Phone HTTP API and live updates The box: one machine The core: the box service, runs as root API 127.0.0.1:7700 Action log append-only, fsynced Apps tools, triggers, routes Vault root only Broker one socket per task Proxy each task's allowed hosts mirrors live state SpacetimeDB tasks, approvals port 3000 Tasks: each its own Linux user Task A own copy of the files no keys Task B own copy of the files no keys Unix socket network Outside APIs tools call with vault keys Allowed hosts and the model service
Your devices talk to the core's API. Each task runs as its own user in its own copy of the files, and reaches the core only through its broker socket and the internet only through the proxy.

The core

Section titled “The core”

The core is one Node.js process, box.service, running as root. It is the only part of the system that can read secrets, create users and mount file systems. It does six jobs:

  • The API. An HTTP server on port 7700 for the portal, the phone and other programs. It listens on 127.0.0.1 unless you change BOX_LISTEN. See the HTTP API.
  • Tasks. It creates a Linux user for each task, mounts the task's own copy of its workspace, and starts the worker as a hardened systemd unit.
  • One broker per task. A Unix socket that only that task's user can open. It is the task's only way to reach the core: to log a step, call a tool, ask for an OK, or report cost.
  • The vault. A root-only file of secrets. Tools run inside the core and read the secrets they declare. Tasks never do.
  • The proxy. The only network path a task has. It lets each task reach only the hosts in its spec, and logs every refusal.
  • The action log. An append-only file of every event. At boot the core rebuilds every task and approval from it.

The core also loads apps. An app is a folder that plugs tools, triggers, log readers, model jobs, pages and routes into the core. See apps and slots.

Tasks and workers

Section titled “Tasks and workers”

A task is one piece of agent work. The worker inside it is Factory's Droid with a Claude model, or a scripted fake worker used by the test suite. The worker runs:

  • as its own Linux user, box-<id>, with a uid from 30000 to 39999, no password, no shell and no sudo;
  • in its own overlayfs copy of a workspace, so its changes stay in its own layer until it finishes;
  • inside a systemd unit that hides other processes, gives it a private /tmp, blocks D-Bus and caps it at 2 GB of memory.

A worker holds no secrets. Droid needs a Factory API key to reach its model, so the task gets a placeholder. The proxy swaps in the real key on the way out. See agents as their own users and the vault and the broker.

Live state

Section titled “Live state”

SpacetimeDB runs on the box on port 3000 and holds two public tables, task and approval. The core mirrors every change into them, so the portal and a phone see updates the moment they happen. A phone can answer an approval by calling the answer reducer, and the core writes that answer to the log within milliseconds.

The mirror is a convenience, not the record. If SpacetimeDB is down, tasks keep running and the portal falls back to the log stream. When it comes back, the core refills it. See live updates.

Your devices

Section titled “Your devices”
  • The portal is a web app the core serves from the same address as the API.
  • The box's own screen is a full-screen browser that shows the portal's box screen, which the core serves at /screen. It has no desktop and no login prompt.
  • A phone opens the portal and answers approvals. Pairing gives it a device token, so the log records which phone said yes. See approve from your phone.

Other programs can drive the box too. Apps on the box connect it to Jira, Elastic and ASI:One. They use the same API and the same approvals as the portal.

The operating system around it

Section titled “The operating system around it”

On a box installed from the ISO, the core is part of a small, fixed system:

  • There is no human account. Root's password is locked and there is no sudo binary.
  • box-firstboot makes the box's identity key and an empty vault on first start, and names the box box-<id> from that key.
  • The disk has two system slots, A and B. An update writes the other slot, starts it once, and keeps it only if the box reports healthy. See system updates.

You can also install the core on an existing Ubuntu 24.04 machine. That gives you the same tasks, vault, log and API, without the A/B updates or the locked-down system. See install on Ubuntu.

Why it is built this way

Section titled “Why it is built this way”

Agents need real access to do real work: files, the network, paid APIs. The usual way to give that access is to hand an agent your account, your keys and your machine. GurtOS takes the opposite approach. It gives each task the least it needs and puts every privileged act behind the core:

  • Linux users and overlayfs keep one task's files apart from another's, so undo is exact.
  • The broker and the vault keep secrets out of tasks, so a hijacked agent has nothing to steal.
  • The proxy keeps each task to its own hosts, so a hijacked agent has nowhere to send data.
  • The log is written before anything else, so every act is on the record and survives a power cut.
Section titled “Related”