Configuration

Configuration reaches a broker through three places: environment variables (usually from a systemd env file), protected files those variables point at, and the policy file. This page is the reference for all three.

Naming convention#

Common settings follow each broker’s prefix, which is HF_BROKER, GH_BROKER, or SUDO_BROKER:

<PREFIX>_AGENT_ENDPOINT
<PREFIX>_OPERATOR_ENDPOINT
<PREFIX>_DEVELOPMENT
<PREFIX>_NETWORK_EXPOSURE
<PREFIX>_SCOPE_FILE or <PREFIX>_POLICY_FILE
<PREFIX>_SECRETS_FILE
<PREFIX>_STATE_DIR

Secret-bearing settings should always be file paths in a deployment. Raw values in environment variables exist for development, and the doctor reports inline credential values as inconclusive.

hf-broker#

gh-broker#

brokers/github/.env.example in the repository carries the full annotated environment.

sudo-broker#

The admission config is supplied as sudo-broker serve --admission-config rather than through the environment.

File layout#

/etc/<broker>/env
/etc/<broker>/secrets
/etc/<broker>/operator-secrets
/etc/<broker>/<policy-file>
/var/lib/<broker>/
/etc/systemd/system/<broker>.service

/etc/<broker> is root-owned and group-readable only where needed. Upstream credentials are separate files owned by the service user or root, mode 0600. /var/lib/<broker> is owned by the service user.

The named client secret file format is shared:

client-name = generated-secret

Secrets carry at least 32 bytes of entropy-equivalent material and are never printed by diagnostics after setup.

Default sockets#

/run/unyolo/huggingface/agent/broker.sock
/run/unyolo/huggingface/operator/broker.sock
/run/unyolo/github/agent/broker.sock
/run/unyolo/github/operator/broker.sock
/run/unyolo/sudo/agent/broker.sock
/run/unyolo/sudo/operator/broker.sock

unYOLO defines no default TCP port for any listener. The Git data plane requires an explicit deployment-selected TCP endpoint because standard Git clients cannot use a Unix socket.

Client config#

setup client writes ~/.config/<broker>/client.json, owner-readable only, using the closed unyolo.io/client/v1 schema:

{
  "api_version": "unyolo.io/client/v1",
  "client_id": "agent-a",
  "agent_endpoint": "unix:///run/unyolo/provider/agent/broker.sock",
  "git_endpoint": "tcp://127.0.0.1:38471",
  "shared_secret": "broker-client-secret"
}

Broker CLIs, MCP adapters, and Git helpers load this file directly. Production clients do not depend on shell startup files or inherited secrets.

Admission config#

An optional closed JSON object that must define every default and global value:

{
  "requests_per_window": 60,
  "window_seconds": 60,
  "client_active": 25,
  "client_pending": 10,
  "global_active": 512,
  "global_executing": 64,
  "clients": {
    "automation-a": {
      "requests_per_window": 20,
      "window_seconds": 60,
      "active": 8,
      "pending": 4
    }
  }
}

Bounded to 64 KiB with an absolute, normalized path. Partial values, unknown clients, duplicate or unknown fields, non-positive limits, pending limits above active limits, and client active limits above the global active limit all fail startup.

Telegram ingress config#

{
  "telegram_bot_token_file": "/etc/unyolo-telegram/telegram-bot-token",
  "telegram_chat_id": 123456789,
  "inbox_path": "/var/lib/unyolo-telegram/callbacks.db",
  "inbox_key_file": "/etc/unyolo-telegram/inbox-key",
  "routes": {
    "h": {
      "operator_endpoint": "unix:///run/unyolo/huggingface/operator/broker.sock",
      "operator_token_file": "/etc/unyolo-telegram/operator-token-h"
    }
  }
}

Route keys are h, g, and s. Duplicate or unknown fields, unsupported routes, relative secret paths, and malformed endpoints are rejected.

Env file parsing#

internal/config/envfile reads the literal KEY=VALUE files setup generates. It bounds input to 1 MiB, rejects duplicate or malformed assignments, and does not interpret shell syntax. Explicit process environment values take precedence in its overlay lookup.

Doctor commands use this parser so they can inspect installed configuration without inheriting the systemd process environment. When an env file is selected it is authoritative.