Python SDK

Operator client plus a robot-side helper for emitting structured logs that flow back to the dashboard.

The Python SDK has two shapes living in the same package:

Client — operator-side. Talks to the control plane over HTTPS. This is the analog of the TypeScript BeaconClient.
Beacon — robot-side. Writes structured JSONL records to the log path the agent tails, so your robot app can call Beacon.log(...) and have lines show up in the dashboard log debugger.

Install

The SDK lives in this monorepo as sdk/python. Until it is published to PyPI, install in editable mode:

pip install -e ./sdk/python

Operator client

from beacon import Client

with Client(token="rf_org_...") as bn:
    robots = bn.robots.list()
    print(f"{len(robots)} robots online")

    release = bn.releases.create({"semver": "1.2.3", "notes": "speed tune"})
    print(release["id"])

The client unwraps Beacon's { "data": ... } / { "items": [...] } envelope automatically — list endpoints return the array, single-object endpoints return the inner data.

Resources

bn.robots.list()
bn.robots.inspect(robot_id)
bn.robots.logs(robot_id)

bn.releases.list()
bn.releases.create({"semver": "1.2.3"})

bn.configs.list()
bn.configs.set({"name": "...", "namespace": "...", "payload": {...}})

bn.enrollment_keys.list()
bn.enrollment_keys.create({"site_id": "...", "fleet_id": "..."})
bn.enrollment_keys.revoke(key_id)

Errors

Non-2xx responses raise RuntimeError with the API's error message extracted from the { "error": { "message": "..." } } envelope. Catch and inspect:

try:
    bn.releases.create({})
except RuntimeError as e:
    print("API rejected:", e)

Robot-side `Beacon` helper

On the robot, your application emits structured records and the agent tails them into the tunnel — your code never opens a socket.

from beacon import Beacon

robot = Beacon.connect()  # reads BEACON_LOG_PATH or ROBOFLARE_LOG_PATH

robot.log("starting pick task", task_id="abc123")
robot.event("pick_complete", duration_ms=842)
robot.metric("battery_pct", 73.2)
robot.ros_node("nav2_lifecycle_manager", status="running")
robot.rosbag("/var/lib/rosbags/2026-05-20T08-00.bag", action="started")

Every call appends one JSON record to the log file with ts, level, source, message, and the extra fields you passed. The agent tails that file and streams it to the dashboard's log debugger.

Set BEACON_LOG_PATH if you want to write somewhere other than ~/.roboflare/app.log — useful when running your app inside a container that mounts a host-side log volume.