What the install puts on your machine
An account for the agents, a service on loopback, an address on your own network, the agents you pick, and a folder of state.
beafk install is the one command that changes your machine. This is what it
does, in order.
It is safe to run again. A machine that is already set up is read, not moved.
On Linux it is usually sudo beafk install. On a Mac, run it as yourself —
root is accepted and handed back, because the machine belongs to the person
logged in.
An account for the agents to run as
Agents run as a user of their own — not as you, and not as root. That
account owns the agents' sign-ins, their caches and their work, and it is what
limits what a mistake can reach.
[!NOTE]
On a Mac there is no account to make: a Mac has one human on it, the agents
run as you, and ~/.beafk of your own home is the machine.
A service that answers on 127.0.0.1
beafk installs a service that listens on the machine's loopback address
only — a systemd unit on Linux, and on a Mac a launch agent in your own
~/Library/LaunchAgents, which runs while you are logged in. It is not on the
internet, and nothing outside the machine can reach it directly. The next step
is how your phone gets to it.
An address on your own network
On Linux the walk installs Tailscale from Tailscale's own signed package
repository — the step labelled Tailscale is on the machine — then, after
the walk succeeds, a second screen stops for login: a
Tailscale link, and a QR code of the same link. You
open it on a device you are signed in on. The login is not a row of the walk.
On a Mac the walk does not install Tailscale — it only looks for the app. After
the walk, if the app is missing, the connect screen mints
Get Tailscale on the App Store,
with Homebrew under a fold labelled or Homebrew, from the terminal you just
used: brew install --cask tailscale, then open -a Tailscale. Sign in to
the account that owns your network, and turn the switch on in the menu bar
so it says Connected. You can paste first; preparing the app first is still
fine. An installed app whose switch is off is a machine with no address; beafk
will not turn it back on for you. The cabinet notices the app and the switch
on its own.
The machine ends up answering at something like
https://your-machine.your-tailnet.ts.net — reachable by your devices, invisible
to everybody else, with no port opened and nothing to configure on your
router.
The same login is on the connect screen in your browser after the walk, so you
can tap it there rather than read it off a terminal.
Press k at the login if you cannot finish it on that device — a Tailscale
account behind a company sign-in, usually — and paste an auth key. The key is
typed into a field that is never drawn on screen. It is never an argument,
never in your shell history, and never sent to beafk. For an unattended
install, --tailscale-key-file FILE or the BEAFK_TAILSCALE environment
variable says the same thing in advance.
Which switches to set when you generate that key — two of them cost people
their machine — is on
your first machine.
Press ⏎ to skip it. The same step, any time later:
sudo beafk net tailscale # Linux
beafk net tailscale # Mac — no sudo
On a Mac, sudo is refused here. Tailscale's app belongs to the person who is
logged in, and root cannot see it.
Room to survive a bad agent
On Linux, the install gives the machine some swap if it has none — a /swapfile
at a quarter of memory, never smaller than 2 GB and never larger than 8 GB, a
line in /etc/fstab so it survives a reboot, and one file of memory settings
under /etc/sysctl.d. It also caps what the agents as a group may take.
The floor matters when you size the disk: on a 2 GB VPS, that swapfile is 2 GB
and not 512 MB.
This is not about speed. An agent that leaks memory takes an unprotected box
down completely — the difference between "the machine is slow" and "the machine
is gone, log in at your provider's console" is this step. macOS manages its own
memory and gets none of it.
A screen and a browser
Also Linux only, and also invisible until you go looking: a virtual screen and a
Chromium in the agent account's cache, plus the browser tool server that points
at them.
A server has no monitor, and a browser with nowhere to draw cannot take the
screenshot you asked for. A Mac already has a screen, so this is skipped there.
If you would rather not have a browser on the machine, take the tool server off
in tool servers.
The agents you pick
You choose from a list, and it installs them: Claude Code, Codex, Grok Build,
Kimi Code, and — if you want it — Codex Security. Nothing is signed in yet;
that happens from your phone, later, in
signing an agent in.
A folder of state
Everything beafk knows about this machine lives in ~/.beafk: its database, its
identity key, the environment variables it delivers to your projects. Anything
holding a secret is written so that only that account can read it.
Checking afterwards
beafk status # what is installed, who is signed in, what is live
beafk doctor # whether a browser can reach this machine at all
See is the machine all right?, and
the command line for the rest of what these two belong
to.
The audit
If you are the person answering for this box,
everything it wrote is the other list: what is
on the machine now, what it touched outside a home directory, and what it never
does at all.