Docs · Technician Guide

Install and run Aufsicht

Aufsicht ships as a single self-contained binary. There is no Python to install, no virtualenv to manage, and no configuration file to write by hand: the binary generates its own key, ledger, and workspace seal on first run and opens the dashboard for you. This page walks an engineer from a fresh machine to a connected agent, then covers the everyday commands and the one switch you need in an emergency.

Install in one line

Sign in to your account (Google or GitHub) and copy your personal install command. It detects your operating system and processor, pulls the matching binary from the private release channel, verifies its checksum, and drops it into ~/.aufsicht/bin. Nothing touches system directories and nothing runs as root.

curl -fsSL https://aufsicht-license.aufsicht.dev/api/download \
  -H "Authorization: Bearer <your-token>" | sh

Where the token comes from. Aufsicht is closed-source and ships from a private release channel, so you need a personal read token to download the binary - even on the free tier. You get one automatically the moment you sign in to your account: the exact command above appears there, pre-filled with your token, ready to copy. The token is read-only, tied to your account, and you can regenerate it any time to revoke the old one, so treat it like a password and do not paste it into shared scripts or commit it anywhere.

On macOS the binary is unsigned for now, so the first launch may need one approval in System Settings → Privacy & Security. That is the only Gatekeeper prompt you should ever see.

First run

Type aufsicht. In an interactive terminal you get a short launcher menu first, and the setup itself runs the moment the gateway starts - from that menu or from aufsicht serve. It creates ~/.aufsicht, writes a strong API key, initialises the SQLite ledger, activates the free tier (no key file is needed: no license.json means free), and opens the dashboard on 127.0.0.1:8765 in your browser. Piped or started by a service manager there is no menu: it just serves. You do not set a single environment variable.

aufsicht            # launcher menu: web UI, foreground, background
aufsicht init       # setup wizard, includes linking detected agents
aufsicht serve      # run in the foreground (Ctrl-C to stop)
aufsicht --help     # every command, one screen

Run it in the background

You rarely want a terminal window pinned open just to keep the guard alive. The launcher menu has a Run in Background option, and the same thing is one command away. Started this way the gateway detaches from your shell and keeps running after you close the terminal, exactly like a small always-on service. A PID file at ~/.aufsicht/gateway.pid lets the other commands find it again, so stopping or checking it later is trivial.

aufsicht start      # detach and keep running in the background
aufsicht status     # is it up? on which port?
aufsicht stop       # shut the background gateway down
aufsicht dashboard  # reopen the dashboard against the running one

Logs from a backgrounded gateway go to ~/.aufsicht/gateway.log. This works the same on macOS, Linux, and Windows, with no extra services to install. Note that aufsicht status answers from that PID file - it tells you the gateway process is alive, not that an HTTP request succeeded.

Connect your agent

Linking is a step of the setup wizard, and you can run the wizard again at any time. It finds each supported client's config and injects the aufsicht-gateway MCP entry pointing at your local gateway, so your agent talks to Aufsicht instead of straight to your repo. The older entry name arbiter-gateway is still accepted as an alias, so a config written by an earlier version keeps working. The MCP bridge also re-links on its own when it starts, unless you set AUFSICHT_AUTO_LINK=0.

aufsicht init        # setup wizard, step 5 links every agent it finds
aufsicht agents      # which agents are linked right now
aufsicht status      # is the gateway process up?

From here you prompt your agent exactly as before. The difference: a governed file write only lands after the permit and the evidence check, and every verdict lands in the ledger you can open from the dashboard.

Everyday commands

The commands you reach for most are few. aufsicht dashboard reopens the browser view without restarting anything. aufsicht db status shows where the ledger lives and how big it is, and aufsicht db backup copies it somewhere safe. When you buy a paid tier, aufsicht fingerprint prints the machine ID you send with your payment, and aufsicht license import --file key.json unlocks the tier once we send your key back.

aufsicht dashboard             # reopen the dashboard
aufsicht db status             # where the ledger is, how big
aufsicht db backup             # copy the ledger somewhere safe
aufsicht fingerprint           # machine ID to send with payment
aufsicht license import --file key.json   # unlock a paid tier after purchase
aufsicht license status        # current tier and expiry
aufsicht update                # check the private release channel

The emergency switch

A guard you cannot turn off is a liability, so there is one switch that steps the system back to the older, lighter checks. Set AUFSICHT_INTERLOCK_ENABLED=0 before you start the gateway and the newer interlock stands down while the legacy checks keep running. The older ARBITER_* environment names are still honoured for the gateway settings, the interlock and auto-linking, so nothing from an earlier setup breaks. Newer switches without an ARBITER_ twin are listed in the technician notes we send with your key. Use it to unblock yourself during an incident, understand that you are running with reduced checking while it is off, and turn it back on once you have found the cause.

AUFSICHT_INTERLOCK_ENABLED=0 aufsicht serve   # run with legacy checks only

Working with the grain

The guard helps most when your tasks are shaped to fit it. Keep each step small enough to finish in one pass and let larger jobs split naturally. When something fails, read the reason code the guard returns - something like WRITE_ASSERTION_FAILED - and fix the cause rather than retrying the same broken step, because blind retries only fail again against a limited budget. Keep secrets out of anything the agent submits as evidence; the guard works from hashes and statuses, never your file contents, and that is exactly what keeps your code off our systems. Before you trust the setup in earnest, trigger the failure path once on purpose and watch it get rejected cleanly, so you know what a real rejection looks like.

Running from source

If you are integrating Aufsicht into your own service rather than using the binary, the gateway is a standard ASGI app and the interlock gate is importable directly. This path is for contributors and advanced integrators, and it assumes you are comfortable managing your own environment and keys. If that is you, reach out and we will point you at the internal integration notes.