Buda Connector

Standalone connector daemon for Buda Agent Connector runtimes.

The cloud server defaults to https://buda.im. Pass --server-url or set BUDA_CONNECTOR_SERVER_URL only for local development or private deployments.

Role

• Registers the local or remote host with apps/buda.
• Starts an embedded @bunny-agent/daemon HTTP runtime in the same Node process.
• Sends heartbeats and local log batches to the cloud registry.
• Maintains a WebSocket relay so Buda Cloud can actively reach the connector.
• Stores device identity and local logs under ~/.buda.

Architecture

See Buda Connector Agent Workspaces for the Agent/Space directory model, context-file lifecycle, shared skill discovery, runtime routing, and security boundaries.

Local Development

Start Buda first:

pnpm --filter buda dev

Create/register a connector identity:

BUDA_CONNECTOR_SERVER_URL=http://localhost:3000 pnpm --filter @buda-ai/connector new

Run the daemon loop:

BUDA_CONNECTOR_SERVER_URL=http://localhost:3000 pnpm --filter @buda-ai/connector dev

The connector starts Bunny Agent daemon on 127.0.0.1 with an ephemeral port by default and reports the local daemon URL to Buda in connector metadata.

The localhost API path bypasses auth for development. Desktop sidecars should pass an OAuth token with --launch-config-stdin.

Launch Config

Desktop can start the sidecar with:

printf '{"serverUrl":"https://buda.im","spaceId":"spc_...","oauthToken":"..."}\n' \
  | buda-connector daemon --desktop --launch-config-stdin --plain

The Desktop controller keeps stdin open as its transient lease. Closing Desktop closes the lease and stops a transient daemon. If the standalone CLI takes the same daemon over as persistent, closing Desktop no longer stops it.

Packaged Desktop launches also set BUDA_CONNECTOR_BUNDLED_RUNTIME_ROOT, BUDA_CONNECTOR_RUNTIME_ENTRYPOINT, and BUDA_CONNECTOR_RUNTIME_NODE so the detached runtime is copied out of the application bundle without requiring network access.

Supported launch config fields:

• serverUrl
• spaceId
• token
• workdirRoot
• oauthToken
• bunnyDaemonHost
• bunnyDaemonPort

One-line install

Buda Space Settings can show a connector token command for the current space. The token selects that Space's independent local connector profile:

npx -y @buda-ai/connector@latest daemon --token "cet_..."

The command installs the runtime into a stable, platform-specific directory under ~/.buda, starts or reuses one detached daemon for the device/Space identity, and attaches the terminal Dashboard. The Dashboard lists every local Connector identity stored in ~/.buda/device.json across servers and Spaces, and also discovers running daemons from their authenticated local control records if a stored identity is missing. It opens before registration finishes and shows a token-scoped Connecting / New Connector / Resolving Space row until the server returns the canonical identity. The Connector resolved by the invocation token is selected first.

Dashboard controls:

• Up / Down (or K / J): select a local Connector when the Connectors section is active.
• Tab: switch between the Connectors, Activity, and Agent Debug sections.
• Mouse wheel: scroll the Activity or Agent Debug pane under the pointer.
• S: ask for confirmation, then gracefully stop the selected Connector. The Dashboard remains open so another local Connector can be selected.
• Escape: exit the Dashboard only. Every Connector daemon keeps running in the background.
• Ctrl+C: open an exit menu. Exit Dashboard only is the safe default. Stopping every local Connector requires choosing Stop all local Connectors and exit and confirming a second warning because running Agent tasks will be interrupted.

The manager sends stop requests through each daemon's existing authenticated local control channel. Local control requests time out instead of blocking the Dashboard indefinitely. When a missing local profile recovers an existing canonical Connector ID, an idle stale daemon is stopped cleanly before the new credential takes over; active Agent work is never force-stopped. The manager never prints Connector or device tokens. --plain and non-TTY launches retain their existing log/background behavior.

You can also pass launch options directly:

buda-connector daemon --token "cet_..." --workdir "$HOME/.buda/agents"

Local Files

• ~/.buda/device.json (canonical identities keyed by device, normalized server origin, and Space)
• ~/.buda/daemons/ (owner-only local control metadata and process locks)
• ~/.buda/runtime/<platform>-<arch>-node<ABI>/<version>/ (stable detached runtimes)
• ~/.buda/logs/connector.log
• ~/.buda/agents/

Existing ~/.buda/connector.log files are left in place as historical logs after upgrading.

Server URL paths and query strings do not create a new identity. Scheme and non-default port changes do. Connector tokens for different Spaces on the same server resolve independent canonical identities, so their daemons can run concurrently. Raw tokens are never used in identity keys or lock paths. The installation-level physical device ID remains shared across profiles.

New server profiles share a privacy-preserving device ID derived by hashing the operating system's stable machine identifier. The raw machine identifier is never stored or sent. If the identifier is unavailable, the connector persists one installation-level fallback ID instead.

If an origin profile is missing, the connector explicitly asks that Buda server to recover the device using the supplied Space connector token. Recovery is limited to the token's space: Buda reuses the server-authoritative connector ID and rotates the new local device credential. A revoked device is prohibited from recovering and must contact support. Ordinary registration with an existing local profile never allows the Space token to replace its pinned device credential. Recovery restores the cloud connector identity so its existing cloud agents can reconnect; it cannot restore local files that were physically deleted from ~/.buda/agents.