Federation & Service

Federation is the shared server runtime that City connects to. It owns user identity, City isolation, Service routing, model catalogs, usage, and payments, while providing a unified interface over multiple AI providers.

Federation AIService

The Federation AIService is a City component that:

• Registers model providers and their capabilities
• Exposes a unified model API regardless of the backend
• Tracks usage and routes requests to the appropriate provider
• Handles failover and rate limiting

An Agent binds to a model through an ID like "default" or "quality". The Federation AIService resolves this ID to a live model instance at runtime.

Service / Action infrastructure

City also provides a general-purpose Service and Action layer for building backend capabilities that Agents can call:

• Service — a long-running backend capability (e.g., a knowledge base, a search engine, a database)
• Action — a discrete operation that an Agent can invoke (e.g., send an email, query a database, call an external API)

Services and Actions are registered with City and can be discovered and called by any connected Agent.

Relationship to City

Federation is the server and City is the user client carrying a user_token. When you use the City SDK, you are interacting with:

• City identity and auth
• Federation AIService (model catalog and routing)
• Service/Action infrastructure (backend capabilities)
• Usage, balance, and billing (City Services)

Federation generates an Ed25519 Key Ring on first startup and publishes verification keys through /.well-known/jwks.json. Embassy can connect to Federation directly; a product deploys Bureau only when it needs its own backend capabilities. A Bureau Token and the independent Bureau client let that service verify User Tokens locally. Federation does not create Bureau Tokens on startup.

Administrator login and recovery

The first fed deploy interactively asks you to set a Federation administrator ID, password, and confirmation. The password must be at least 12 characters; Federation stores only a salted password digest. After starting fed web, enter those credentials on the login page. The browser never receives the remote administration Session Token, which remains in the local BFF process.

An ordinary deployment never changes the administrator. If the password is lost, only an operator with Local host authority or Cloudflare Worker/D1 deployment authority can run:

fed deploy --admin-reset

Non-interactive environments must also pass --yes; this only confirms the reset and does not skip credential prompts. The CLI applies recovery directly through a local SQLite transaction or Wrangler-authorized remote D1 access; Workers do not receive recovery environment variables, and plaintext passwords never enter the database. A successful recovery revokes every previous administrator session. Federation exposes no anonymous password-reset API.

fed deploy continuously reports the current stage and elapsed time for builds, typechecks, Cloudflare account checks, D1 / Queue / R2 preparation, Worker deployment, health checks, and administrator verification. CI and redirected output receive stable line-based progress logs instead of terminal animation.

fed bureau token opens the interactive token manager. Choose Issue, or run fed bureau token issue <bureau_id>, to enter a purpose and use an Admin Session to ask Federation to issue the credential. Federation generates the plaintext and stores only its purpose, hash, and lifecycle state. The plaintext is returned once and configured as DOWNCITY_BUREAU_TOKEN on the Bureau server. Federation and Bureau can run on different servers. A Bureau Token proves machine identity and cannot issue User Tokens.

Where to learn more

• City SDK — building on City and Federation
• Payments — usage, balance, and billing APIs