Enroll an Instance

This page shows you how to connect a running SLAW instance to your Botfather tower. Once enrolled, the instance appears in the Fleet view and its cost, agent, and issue metadata flow to the tower.

Prerequisites

• Botfather is running and reachable from the SLAW machine (see Install the Tower)
• SLAW is running on the instance you want to enroll
• You have Operator access to the Botfather admin UI at http://localhost:5174

How enrollment works

Enrollment is token-less and config-driven: setting botfather.url in the SLAW configuration file is all it takes to initiate contact. SLAW connects to the tower, submits a self-enrollment request using its machine identity, and waits for an Operator to approve it.

The enrollment gate shows one of six states:

State	Meaning
connecting	SLAW has a botfather.url and is attempting to reach the tower
pending	Enrollment request received by the tower; waiting for Operator approval
rejected	An Operator rejected this instance's request
active	Enrolled and approved; the tower has issued a per-instance API key
unreachable	Tower was reachable at least once (instance holds a key) but is not responding now
revoked	An Operator revoked this instance's access from the tower

Until the instance reaches active, the SLAW UI shows a blocking gate page (in enforce mode, the default).

1. Set botfather.url in SLAW

Open the SLAW configuration file for the instance. The default location is:

~/.slaw/instances/default/config.json

Add or update the botfather section:

{
  "botfather": {
    "url": "http://your-tower-host:8400"
  }
}

Replace your-tower-host:8400 with the address where Botfather is running. If both SLAW and Botfather are on the same machine, use http://localhost:8400.

Environment variable

You can also set the URL via the environment variable SLAW_BOTFATHER_URL — useful for scripted provisioning or MDM deployment. The environment variable takes precedence over the config file.

2. Restart the SLAW server

The enrollment integration activates on startup. Restart the SLAW server to pick up the new configuration:

# If running via the CLI
npx slaw run

# If running in dev mode
pnpm dev

3. Confirm the enrollment request was sent

Check the instance's enrollment status with the SLAW CLI:

slaw botfather status

You should see output similar to:

SLAW Control Tower (botfather)
Tower:       http://localhost:8400
Enforcement: enforce
Status:      not enrolled
Machine ID:  mch_...
Instance:    inst_...

The Status line transitions to enrolled (active) once the tower issues an API key.

While status is not enrolled, SLAW is in pending state — the tower has received the request and is waiting for Operator approval.

4. Check the approval queue

Open the Botfather admin UI at http://localhost:5174 and navigate to Approvals & Admin. Your instance should appear in the pending enrollment queue with its machine ID and hostname.

Approve or reject the request from there. When you approve, the tower issues a per-instance API key and the instance transitions to active.

For teams with many instances to onboard, set up auto-approve rules to skip the manual step.

5. Verify active enrollment

Once approved, re-run the status check:

slaw botfather status

SLAW Control Tower (botfather)
Tower:       http://localhost:8400
Enforcement: enforce
Status:      enrolled (active)
Machine ID:  mch_...
Instance:    inst_...
Enrolled:    2026-06-09T...

The instance appears in the Fleet view in the Botfather UI, and its metadata begins syncing every 60 seconds.

Troubleshooting enrollment states

Stuck on connecting — the tower is not reachable. Check the botfather.url value, confirm Botfather is running on :8400, and verify there are no firewall rules blocking the connection.

Stuck on pending — an Operator has not approved the request yet. Check the Approvals queue in the Botfather UI.

rejected — an Operator rejected the request. You can retry: remove the stored credentials and restart SLAW, or run slaw botfather reenroll.

unreachable — the instance holds a valid API key but cannot reach the tower. SLAW continues running (fail-open for enrolled instances in enforce mode). The instance will reconnect when the tower is reachable again.

revoked — the tower revoked the instance's key. SLAW will attempt a fresh enrollment on the next startup. An Operator must approve the new request.

---

Next steps

• Approve & Go — manage the approval queue and configure auto-approve rules for faster onboarding
• Fleet View — monitor every enrolled instance from the tower dashboard