Install on Ubuntu

You can run GurtOS on a plain Ubuntu 24.04 system instead of the GurtOS image. You keep Ubuntu's login, package manager and updates. GurtOS adds its service, its task users and its firewall rule. Tasks, the vault, approvals and the action log work the same as on the OS image.

This is the quickest way to run real agent tasks today.

Requirements

Ubuntu 24.04, on x86_64 or arm64.
Root access (sudo).
At least 4 GB of memory and 10 GB of free disk. Each task may use up to 2 GB of memory. The box has run one task at a time in 1 GB, and adds 1.5 GB of disk (measured).
Internet access during the install, to download Node.js, Droid (about 300 MB), SpacetimeDB, and the tunnel and web server that remote access uses (frpc and Caddy).
No other software using user ids 30000 to 39999, TCP port 7700, port 3000, or ports 8800 to 8899.
One model key: an Anthropic API key from console.anthropic.com, or a Factory API key from app.factory.ai. Tasks never see it. Apps are optional. On a new box only the model app is on, and every other app stays off until you turn it on in App Center and add the keys it lists.

Install

Get the GurtOS source on the machine:

git clone https://github.com/benz16107/gurtos.git gurtos && cd gurtos

From the top folder of the source, run the install script as root:
```
sudo core/install.sh
```
It runs core/setup.sh, which installs nftables and ripgrep, Node.js 24 if no Node.js 22 or newer is present, the Droid CLI (checked against a SHA-256 written in the script), the frpc and Caddy binaries for remote access (also checked), and SpacetimeDB 2.13.0 from its pinned GitHub release files (checked the same way) as spacetimedb.service. No install script from the internet runs. Then it copies what the box runs (the core, the apps and the built portal) to /opt/box, installs its packages, creates an empty vault at /etc/box/vault.env with mode 0600, and installs and starts box.service. It prints active when the service is up. Running it again is safe.
Add your model key to the vault, in the setup wizard's Model key step or in the portal's Settings, Accounts & Keys (see Open the portal), or through the API. The command below sets a Factory key; for an Anthropic key, use the name ANTHROPIC_API_KEY instead. A request from the machine itself is allowed to set keys, the key takes effect at once, and the box never returns it. The box checks an Anthropic key with Anthropic and refuses one that Anthropic rejects:
```
read -rs -p 'FACTORY_API_KEY: ' v && echo
printf '{"value":"%s"}' "$v" | curl -s -X PUT http://127.0.0.1:7700/api/vault/FACTORY_API_KEY \
  -H 'content-type: application/json' -d @- && unset v
```
You can also edit /etc/box/vault.env (KEY=value, one per line) as root and restart box.service. The box refuses to start if that file is readable by anyone but root. See Add a secret to the vault.

Check it runs

systemctl is-active box.service spacetimedb.service
curl -s 127.0.0.1:7700/api/health

{"ok":true,"startedAt":"2026-10-24T07:00:00.000Z","paused":false,"cleanStart":false,"resumed":[],"tasks":0,"tools":[],"spacetime":{"port":3000,"database":"box"}}

tools lists every tool the apps that are on provide. A new box has only the model app on, which adds none. Check the service log for the line that lists the apps that loaded:

journalctl -u box.service -n 20 --no-pager

box up: 0 tasks in the log, tracks: anthropic

An app that fails to load is skipped and logged there. The box keeps running without it. Turn on more apps in App Center, or with POST /api/apps/<id>/enable. See Apps.

If the log says WARNING: the firewall rule did not load, so tasks are not network-limited, nftables is missing or blocked. Fix that before you run tasks: without the rule, tasks can reach any host.

Open the portal

The box serves the portal on the same address as the API. On the machine itself, open http://127.0.0.1:7700/ in a browser.

The first time, the portal shows the same setup wizard as GurtOS Server (see First boot and pairing). Its Model key step does the same job as step 3.

The API listens on 127.0.0.1 only. To use the portal from another computer, forward the port over SSH:

ssh -L 7700:127.0.0.1:7700 -L 3000:127.0.0.1:3000 you@192.0.2.10

Then open http://127.0.0.1:7700/ on your own computer. Forwarding port 3000 as well gives the portal live updates through SpacetimeDB; without it the portal falls back to the action log stream.

A forwarded connection arrives at the box from 127.0.0.1, so the box treats it like its own screen, with the owner's rights. That is fine for you over your own SSH login. Do not forward the port for anyone else.

Update or remove

To update, get a newer copy of the source and run sudo core/install.sh again. It replaces /opt/box and restarts the service. Tasks that were running resume from the action log.

To remove GurtOS, stop and disable the services, then delete what the install created:

sudo systemctl disable --now box.service spacetimedb.service
sudo rm /etc/systemd/system/box.service /etc/systemd/system/spacetimedb.service
sudo systemctl daemon-reload
sudo nft delete table inet box
sudo rm -rf /opt/box /var/lib/box /etc/box   # deletes the action log, workspaces and vault
sudo rm -rf /var/lib/spacetimedb              # SpacetimeDB's data

The install also left Node.js, /usr/local/bin/droid, /usr/local/bin/frpc, /usr/local/bin/caddy and the SpacetimeDB CLI in place. Remove them if nothing else uses them.

Task users (box-<id>) are removed when each task ends. Check for leftovers with getent passwd | grep '^box-'.

Your first task.