Agent connectors

Run Buda agents on your own machines — register a host to a Space with one command and watch its status from the dashboard.

Sometimes the work has to happen on your machine. Local files, a tool only your laptop can reach, a build that needs your environment — a connector registers one of your own machines to a Space so Buda agents can run work there, while you keep watching status and heartbeats from the cloud dashboard.

What a connector is

A connector is a small daemon you run on a machine you control. Once registered, it reports back to Buda Cloud with a regular heartbeat and shows up under Settings → Connectors for the current Space. Each connector is space-scoped — it's tied to the Space you installed it from, not to a single user, so anyone in that Space can see it.

Install the connector

Open Settings → Connectors for the Space you want the machine to join, and click Generate script.

Copy the command. It looks like this, with your Space's ID filled in:

npx -y @buda-ai/connector@latest daemon --space-id <your-space-id>

Run it in a terminal on the machine you want Buda agents to use. The daemon registers the host to the Space and starts sending heartbeats.

Confirm it appears. The connector shows up in the list with its device name, platform, and an Online badge.

This simple mode identifies the Space, not an individual user. Buda Desktop registers connectors using OAuth token mode instead.

Online, stale, offline

Each connector card shows a live status derived from its last heartbeat:

Online — a heartbeat within the last ~30 seconds. The machine is ready for work.
Stale — no heartbeat for ~30 seconds to 2 minutes. Likely a brief network hiccup or a paused process.
Offline — no heartbeat for over 2 minutes, or the daemon was stopped.

A separate Relay badge shows whether the connector currently holds a live realtime link back to Buda Cloud. The summary cards at the top of the page tally totals across the Space.

Troubleshoot

It never appears — check the terminal for errors and confirm the machine has outbound internet to https://buda.im.
Stuck on Stale — the process is running but heartbeats are delayed; check the network, then click Refresh.
Shows Offline — the daemon stopped. Re-run the install command to bring it back.
Wrong Space — generate the script from the correct Space; the --space-id in the command determines where the host registers.

Spaces

Spaces own connectors — how workspaces and membership work.

Integrations overview

Tools and connections for your agents.