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","oauthToken":"..."}\n' \
  | buda-connector daemon --launch-config-stdin

Supported launch config fields:

• serverUrl
• 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_..."

Desktop and other authenticated clients should use OAuth token launch config instead:

printf '%s\n' '{"serverUrl":"https://buda.im","oauthToken":"..."}' \
  | npx -y @buda-ai/connector@latest daemon --launch-config-stdin

You can also pass launch options directly:

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

Local Files

• ~/.buda/device.json (versioned device profiles keyed by server origin and token fingerprint)
• ~/.buda/connector.log
• ~/.buda/agents/

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 select independent profiles, so their daemons can run concurrently. Raw tokens are never used in profile 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.