Enroll a robot

A Beacon robot belongs to a fleet inside a site. Before a robot can connect, you provision that hierarchy and mint an enrollment key the agent uses to exchange for its long-lived robot token.

1. Create a site

A site is a physical location — a warehouse, a lab, a customer deployment. Every robot belongs to exactly one site.

beacon sites create "Warehouse A"

2. Create a fleet inside the site

A fleet groups robots that get the same releases and configs. Common patterns: one fleet per robot model, or one fleet per generation.

beacon fleets create "pick-and-place v1" --site "Warehouse A"

Names work for --site and --fleet arguments throughout the CLI; pass an id when names are ambiguous.

3. Mint an enrollment key

Enrollment keys are scoped to a single site and fleet. Robots that present the key are automatically attached to that fleet on first connect.

beacon keys new \
  --site  "Warehouse A" \
  --fleet "pick-and-place v1" \
  --label "warehouse-a-batch-1"

The response includes the raw key value (rf_enroll_<hex>). This value is shown once and never returned again — only the hash is stored. Copy it into your provisioning script or a sealed secret store now.

Optional flags:

• --max-uses <n> (default 100) — caps how many robots can claim the key.
• --expires-in-hours <h> (use 0 for no expiry) — auto-disables the key after this window.

Revoke an active key:

beacon keys revoke <key-id>

4. Run the agent on the robot

The fastest way to bring a robot online is the beacon agent run command, which doubles the CLI as the agent on the same machine — useful for demos, dev loops, and one-off Linux/macOS robots.

beacon agent run \
  --enrollment-key rf_enroll_<paste-here> \
  --name warehouse-bot-01

On first run the agent exchanges the enrollment key for a robot token and saves both to ~/.config/roboflare/agent.toml. Subsequent runs reuse the saved identity, so you can omit --enrollment-key:

beacon agent run

Pass --fresh to force re-enrollment, or beacon agent forget to wipe the saved identity.

For production fleets you ship the standalone agent binary as a systemd / launchd service. The wire protocol is identical to beacon agent run, so the dashboard treats both the same way.

5. Verify it's online

beacon robots list

The robot's last_seen_at updates server-side from heartbeat receipt. If it shows - after a minute, check the agent's stderr and confirm the backend URL is reachable from the robot.

Next

Your robot is online. Ship it a release in Deploy an update.