Federation & Service
What Federation and Service are in Downcity's AI infrastructure
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 runs only explicitly registered Services. The host supplies its database, Accounts, AI, EnvService, storage, and Queue; local and remote calls share the same protocol.
Local service operation
Local Federations use macOS user-level launchd or Linux user-level systemd. [deployment.process] defaults to auto_start = false and restart_on_failure = true: unexpected exits trigger recovery every 10 seconds, limited to 5 attempts within 60 seconds. fed stop disables automatic startup and stops the service. It remains stopped across system restarts until an explicit deploy/restart.
Automatic startup requires explicit opt-in. macOS starts after user login; Linux requires the user's manager to exist and be available. The CLI does not enable linger. System service definitions contain no secrets; runtime configuration is stored separately. See CLI Quickstart for configuration examples and status/logs behavior.
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 --id fed_x for the saved connection, 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-resetNon-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 has no global active/default connection. Target selection uses mutually exclusive, exact-match --id <id> or --name <name>; without a selector, a TTY prompts for this operation only and non-interactive execution fails. Duplicate names prompt in a TTY and fail outside one.
User sessions own identity, permissions, and Credits. City automatically carries optional city_id for logs, usage, and job source only. Business calls use federation.user.service(name) on the current Federation; administrators use a separate Session.