Put the doorman on your machine in one command.

1What gets installed

A small, self-contained stack on your machine, started by Docker with one command. Together it's "the doorman":

Your agents are not modified. You point a program at the gateway (Section 6) and its calls flow through KMA. That's the whole integration.

2Before you start

You start in watch-only mode: install, see your agents and where they go, block nothing. Enforcement is switched on later, when you decide.

3Install — one command

Open a terminal and paste the line for your system. Pick the tab that matches.

It asks two things: where to install (press Enter for the default, ~/kma — or type a folder like C:\kma) and your registration token. Then it does the rest. First run pulls the images, so give it a few minutes on a slow connection.

Already installed? Run the same command again. It notices KMA is there and updates it instead — your secrets, registration, audit log and passports are kept. See Updating.

4What the installer does, step by step

Nothing hidden. In order:

1. Checks Docker is installed, running, and new enough (needs docker compose). Stops with a clear message if not.
2. Asks where to install. Default ~/kma (%USERPROFILE%\kma on Windows). Enter accepts the default. Scripted installs set KMA_DIR instead and are never prompted.
3. Detects an existing install in that folder and switches to update mode (keeps everything). Set KMA_FRESH=1 to force a brand-new install with a new machine identity.
4. Probes four local ports (viewer, log, passport, gateway). If one is already taken, KMA quietly moves to the next free one, tells you, and records it in .env. You can also choose your own with KMA_<NAME>_PORT (e.g. KMA_VIEWER_PORT).
5. Asks for your registration token and looks up your organisation from it (a read-only lookup — the token isn't consumed until the kit actually enrols).
6. Downloads the kit into the folder: the Compose file, the enrollment script, and the helper scripts for update, backup and restore, plus the kit's own INSTALL.md.
7. Generates your machine's local secrets (admin tokens, wallet key) and writes .env. These are made on your machine and never leave it.
8. Starts the stack (docker compose up -d --wait) and enrols the machine with your console using the token. Your machine creates its own key pair; only the public half is registered.
9. Skips the optional sensors (things that run beside the gateway rather than through it, such as coding-assistant hooks). They are installed only when you ask for them with KMA_SENSORS=1.

The installer is a plain script you can read: install.ps1 · install.sh. Everything it writes lives in the folder you chose.

5Approve the machine

After enrolment the machine appears in your console as pending. Open console.knowmyagents.com → Settings → Registrations (or the Add a machine page) and approve it.

This is deliberate — the second lock. A registration token alone can never attach a machine to your organisation; a person has to say yes. Until you approve, the kit still runs fully on the machine (it observes and enforces locally) — it just doesn't report to the console yet.

6Route your first program through the gateway

Now point an agent program at the gateway so its calls go through KMA. Nothing inside the program changes.

1. In the console open Programs → Add a program.
2. Tell it how your program runs (a command on this machine, a container, or a deployment). KMA hands you the exact thing to use: an overlay or a command that starts your program through the gateway.
3. Start your program that way. From its first call, KMA sees it.

Under the hood the program's outbound calls are routed via the local gateway, and — if you switch on "inside the call" for its doors — the program trusts KMA's local certificate so KMA can read the call and identify which agent made it. The console's Add a program page gives you the precise, copy-paste form for your setup; that page is the source of truth, so this guide doesn't hardcode addresses.

Agents on other machines or in Kubernetes? By default the gateway listens only on this machine (loopback). For a cluster or a VM, set KMA_GATEWAY_BIND in .env to 0.0.0.0 or this machine's private IP — only on a private network behind a firewall, because whoever can reach the door can call through it. The console's Add a program page includes a Kubernetes patch.

7What you'll see

8Next steps in the console

1. Issue passports. Give each Shadow Agent a verifiable identity from the Identity page. Shadow becomes identified.
2. Write rules. On Policies, write a rule in plain words and let KMA draft it — "only agents with a passport may call", a daily spend cap, per-door allow or refuse.
3. Write a charter — a plain-English conduct rule (e.g. "never trade defense-sector stocks"), judged for intent by an AI judge on every call it covers. Set your AI provider key and judge model in Settings → AI assistant first.
4. Watch, then enforce. On Doors, keep the mode on observe until the "would allow / would refuse" decisions look right, then flip to enforce. Set "Sees" to inside the call to identify agents and enable charters.

9Updating

Re-run the install one-liner from Section 3. It detects the existing install and updates it to the latest kit — your secrets, registration, audit log and passports are kept. It works from any older version.

Or run the updater directly from your kit folder:

The updater backs up the previous Compose file, fetches the new kit files, pulls the new images and restarts the stack. It never runs docker compose down -v, so your data can't be lost by an update.

10Backup & restore

Your kit folder contains backup.ps1 / backup.sh and restore.ps1 / restore.sh. Back up before major changes and on a schedule that matches how much history you're willing to lose:

One timestamped archive captures all three data volumes — the audit log database, your machine's private key and configuration, and the passport issuer's signing key — plus your agents' passports from the kit folder (from kit 0.9.11; older backups restore without them and the agents need re-issuing). It's a raw copy, so the log's hash chain still verifies after a restore.

The archive contains private keys. Store it somewhere secure and off this machine.

Restore on a fresh machine (or to roll back) with ./restore.sh <archive> / .\restore.ps1 <archive>. Restore is destructive — it overwrites the current keys and log with the archive's, and asks you to confirm.

11Uninstall or start fresh

Also revoke the old machine in the console (Settings → Registrations) so a removed machine can't reappear as trusted.

12Advanced options

All are environment variables set before running the installer.

Prefer a fully manual install on a locked-down box? The kit is just a folder with a Compose file and a .env. The same steps by hand are in the kit's own guide: INSTALL.md.

13What leaves your machine — and what doesn't

The hosted console is a window, not the doorman. Enforcement never depends on it — if the console goes dark, your gateway keeps working. The full record is always available to you in the Local Viewer, on your machine.

14Troubleshooting