Skip to content

Server Federation

Federation allows distributing scopes across multiple servers with automatic merging and centralized management.

Master Server Configuration

Single master server

Configure one master server with an environment variable or in settings.toml:

export DAIMYO_MASTER_SERVER_URL="http://master.example.com:8000"

master_server_url = "http://master.example.com:8000"

For HTTPS with a private CA certificate:

export DAIMYO_MASTER_SERVER_URL="https://master.example.com:8000"
export DAIMYO_REMOTE_SSL_CA_BUNDLE="/etc/ssl/certs/company-ca.pem"

Warning

To disable certificate verification (not recommended for production):

export DAIMYO_MASTER_SERVER_URL="https://master.example.com:8000"
export DAIMYO_REMOTE_SSL_VERIFY="false"

Multiple master servers

MASTER_SERVER_URL accepts a TOML list when configured via settings.toml:

master_server_url = [
    "https://primary.example.com:8000",
    "https://secondary.example.com:8000",
]

The first URL in the list has the highest priority. When the same scope exists on several servers, rules are merged as follows:

  • Commandments (mandatory rules): accumulated additively from every responding server.
  • Suggestions (SHOULD rules) and katas: the first URL's content overrides the same-named entries from subsequent URLs, just as a child scope overrides a parent.
  • Local scope (if present): always merged on top of the combined remote result.

If a server is unreachable its contribution is silently skipped; the remaining servers are still queried.

The system will:

  1. Look for scopes locally
  2. Query every configured master server (in list order)
  3. Merge remote results with priority (first URL wins for suggestions and katas)
  4. Merge the combined remote result with the local scope (local always wins)

Scope Sharding

The same scope name can exist on both master server and locally. When both exist, they are merged with the remote version as the base and the local version extending it.

Template Rendering in Federated Deployments

Important: In federated deployments, templates are always rendered by the requesting instance, not by the master server.

When a subordinate instance fetches scopes from a master server:

  1. Master returns raw templates: The master server returns unrendered templates with Jinja2 syntax intact (using debug=true internally)
  2. Subordinate renders with its own context: The requesting instance renders templates using its own:
  3. Configuration variables (from its settings.toml and environment)
  4. Enabled plugins (git context, filesystem info, custom plugins)
  5. Scope metadata and tags

Why this matters:

  • Different contexts per instance: Each subordinate may have different plugins, variables, and configuration
  • Workspace-specific rendering: Templates like {{ git_branch }} or {{ project_name }} resolve correctly for each workspace
  • Consistent rule logic, variable deployment: Master defines rule templates once; each instance applies them with local context

Example:

Master server defines:

python.deployment:
  ruleset:
    - Deploy to {{ DEPLOYMENT_REGION | default('us-east-1') }}
    - Notify {{ TEAM_SLACK | default('#deployments') }}

Subordinate A (with DEPLOYMENT_REGION=eu-west-1, TEAM_SLACK=#eu-team): Renders as "Deploy to eu-west-1" and "Notify #eu-team"

Subordinate B (with DEPLOYMENT_REGION=us-west-2, TEAM_SLACK=#us-team): Renders as "Deploy to us-west-2" and "Notify #us-team"

This architecture enables centralized rule management with decentralized context, allowing each workspace to maintain its own identity while following common organizational standards.

Authenticated Federation

When an OIDC session is active (i.e., oidc_issuer_url and oidc_client_id are configured and the user has run daimyo login), the remote client automatically injects the access token into every request sent to the master server:

Authorization: Bearer <access_token>

If the access token has expired, it is refreshed transparently before the request is sent.

Handling Authentication Failures

If the master server returns 401 Unauthorized after a token refresh attempt, or 403 Forbidden, daimyo treats the remote scope as temporarily unavailable:

  • The failure is logged as a warning.
  • Remote scope items are skipped for that request.
  • Local scopes are never affected — they remain fully accessible regardless of remote authentication failures.

This graceful degradation ensures that a misconfigured or unreachable authentication server does not bring down local rule serving.

Setup

  1. Configure the OIDC settings (see Authentication — Prerequisites).
  2. Log in: daimyo login
  3. Start the server or run CLI commands as usual — tokens are injected automatically.

Cache Management and Reloading

Daimyo uses in-memory TTL (Time-To-Live) caches for resolved scopes and scope listings to ensure high performance. By default, these caches expire after 20 minutes.

If you modify rule files (commandments.yml, suggestions.yml), katas (katas.yml), or vision artifacts (tenka.yml) and want the changes to be visible immediately without restarting the server, you can trigger a manual reload.

How Reloading Works

When a reload is triggered:

  1. Local caches are cleared: All resolved scopes, kata collections, and tenka vision layers are evicted from memory.
  2. Federation propagation: For every URL in MASTER_SERVER_URL, the instance sends a best-effort POST /api/v1/reload request. A failed reload on one server is logged as a warning but does not prevent the remaining servers or the local reload from completing.
  3. Lazy reload: Caches remain empty until the next request for a scope, at which point the files are re-read from disk and re-merged.

Triggering a Reload

  • REST API: POST /api/v1/reload
  • MCP Server: reload() tool

Note

The daimyo serve --reload CLI flag is for development auto-reload (using uvicorn) and is different from this manual cache invalidation.