Fred
Developer Guide
Start here. The one design rule that governs everything, the five concepts you need before writing any code, and a 20-minute reading path through the documents that matter most.
What is Fred
Fred is a platform for deploying operator-configured AI agents at team scale. A platform admin sets the guardrails — quotas, allowed models, allowed tools. A team admin enrolls agents from a catalog and configures them for the team's context: prompts, MCP tools, routing policy. Team members interact with those agents through a managed chat interface — without writing code.
What makes Fred different from a simple LLM wrapper is its strict enforcement of governance boundaries. Operators configure within limits they cannot exceed. Every action is team-scoped and authorized. Execution is isolated from product management so neither layer can accidentally reach into the other's concerns. Fred is designed to run in regulated environments where auditability and role separation matter.
The one design rule that governs everything
Fred has three layers. They never merge.
This separation means the execution engine can evolve without touching product
APIs, and the product surface can evolve without touching how agents run. It also
keeps the authorization model clean: there is no control-plane-issued grant.
The caller's Keycloak JWT carries identity end to end, and the agent pod itself
authorizes each request with a per-request OpenFGA check on
runtime_context.team_id — the pod is the execution authority, not
a token the control-plane hands it.
Components
Deployed services
These components run as processes or containers in a production deployment.
| Component | Layer | Role |
|---|---|---|
apps/fred-agents |
Runtime | Reference agent pod — the Fred-provided set of agents, built on fred-runtime |
apps/control-plane-backend |
Control plane | Product/session/admin APIs — issues no execution token; execution auth is JWT + pod-side OpenFGA |
apps/knowledge-flow-backend |
Control plane | Document ingestion, retrieval, and knowledge management |
apps/frontend |
Client | React SPA — chat UI, agent management, session lifecycle |
Authoring libraries
These are Python libraries — they are not running services. They are the building
blocks used to write agent pods. apps/fred-agents is itself built with
them and serves as the reference implementation. Any team can import these same
libraries to author their own fully deployable agent pod, tailored to their context,
that slots into the same platform without modifying Fred's core.
| Library | Layer | What it provides |
|---|---|---|
libs/fred-runtime |
Runtime | Execution framework — agent engine, SSE, HITL, checkpoints. The core import for any custom agent pod. |
libs/fred-sdk |
SDK | Shared execution contracts, typed primitives, prompt utilities |
libs/fred-core |
Cross-cutting | Caching, config, logging, KPI stores |
fred-runtime, define
your agent behaviors, and deploy the result as a standard container. The control
plane enrolls it exactly like apps/fred-agents — no changes to Fred's
core required.
Five things to understand before writing code
› 1 Team-scoped agent instances
There are no global agents. An agent exists as a template (defined in the runtime pod catalog) and an instance (enrolled by a team admin in control-plane). Members interact only with instances. The instance carries tuning field values, MCP configuration, and prompt overrides — all team-scoped and stored in control-plane, never in the runtime pod.
› 2 JWT + per-request OpenFGA — no execution grant
There is no control-plane-issued grant or token for execution. Identity
flows as the caller's Keycloak JWT, forwarded unchanged all the way to
the agent pod. The pod is its own execution authority: on every request
it validates the JWT (issuer, audience, per-agent aud) and
runs a live OpenFGA check that the caller holds CAN_READ on
runtime_context.team_id. Neither the frontend nor the user
can forge or escalate that check — a missing or unauthorized team fails
closed (403). This is the primary security boundary between product
and execution.
› 3 The MCP catalog — tools as first-class citizens
Agents use tools via the Model Context Protocol (MCP). The MCP catalog
(mcp_catalog.yaml in the agent pod) declares available
servers, their configuration fields, and their behavioral contracts.
The control-plane proxies this catalog to the frontend — it does not
interpret it. The operator selects which MCP servers an agent instance
uses at enrollment time.
› 4 Platform admin vs team admin — orthogonal, not hierarchical
A platform admin (platform_admin) sets immutable guardrails:
quotas, allowed model profiles, allowed MCP servers. A team admin
(team_admin) configures everything within those guardrails:
agents, routing policy, shared prompts.
Neither role can write to the other's surfaces.
A platform admin cannot manage agents or prompts. A team admin cannot
touch platform policy. This is enforced at the API layer, not only in
the UI. See docs/swift/platform/REBAC.md for the full model.
› 5 Personal vs team scope
Everything in Fred is scoped to a team — including "personal."
/teams/personal is a reserved system team that represents
one user's private space. Personal prompts, sessions, and history all
live under this team. There is no parallel user-owned namespace outside
the team model. A user who is not a member of any other team still
has exactly one team: personal.
20-minute reading path
Five documents, in order. Read the why before you open each one.
gh issue list --milestone "swift-golive"How work gets done
Every task follows a fixed sequence: RFC → developer confirmation → GitHub issue → implementation → close-out. Steps cannot be skipped or reordered.
swift-golive, swift ga) are the
single source of truth for sprints, issues, and status —
gh issue list --milestone "swift-golive"