Skip to content
felix-runPublic

About

Self-hostable managed agents harness. Author YAML manifests; Felix compiles them into governed agents with durable fibers, memory, skills, eval, approvals, and sandboxes — over OpenAI, A2A, MCP, and SSE. Fork, rewind, and steer runs. Docker, Helm, AWS, or GCP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,671 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Felix

CI License: Apache 2.0

Felix is a self-hostable agents harness: the primitives and the runtime to build any agent, for any agentic workflow. You describe an agent as a YAML manifest (apiVersion: felix/v1); Felix compiles it into a governed agent with durable fibers, memory, skills, eval, approvals, and sandboxes — served over REST/SSE, an OpenAI-compatible API, A2A, and MCP. Fork, rewind, and steer live runs. Deploy with Docker, Helm, AWS, or GCP on infrastructure you operate.

📖 docs.felix.run — installation, concepts, manifest and API reference

Web UI github.com/felix-run/web
Roadmap docs/ROADMAP.md
Changelog CHANGELOG.md

What you get

  • Manifests — felix/v1 YAML; the agents in manifests/ are worked examples, not the product
  • Governance — auth, approvals, audit, usage meters
  • Durable execution — fibers, steer and follow-up
  • Session control — fork, rewind, compacting / windowed / semantic strategies
  • Memory and skills — durable facts, procedural memory, Agent Skills
  • Surfaces — REST/SSE, OpenAI-compatible /v1, A2A, MCP
  • Eval — datasets, fixtures, --mock CI path
  • Deploy — lean Docker, Helm, AWS, or GCP

Quick start

Prerequisites

  • uv. It fetches Python 3.14 itself.
  • Docker with Compose v2, for the database and the full stack. The test suite does not need it.
  • A model key. An agent that names no model runs on claude-sonnet, so Anthropic is the short path; with only an OpenAI key, also set FELIX_DEFAULT_MODEL_ID=gpt-4.1. .env.example lists the rest.
  • jq for the examples below (optional).

Set up

make bootstrap   # checks the tools, writes .env with generated passwords, installs, adds pre-commit
make test        # the suite on in-memory stores: no database, no model key

Put your model key in .env: FELIX_ANTHROPIC_API_KEY, or FELIX_OPENAI_API_KEY plus FELIX_DEFAULT_MODEL_ID=gpt-4.1.

Build your first agent

An agent is a manifest. Write one in a directory of your own, outside the clone, for example ~/felix-agents/triage.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/felix-run/felix/main/schemas/manifest.schema.json
apiVersion: felix/v1
kind: Agent
metadata:
  name: triage
  description: Sorts incoming requests into bug, question or feature, and says why.
spec:
  pattern: react
  system_prompt:
    inline: |
      You triage incoming requests. Answer with one of bug, question or feature,
      then one sentence on why.
  tools: []   # built-ins, MCP servers and your own plugin tools go here
  auth:
    inbound:
      allow_anonymous: true   # local development only; drop it once callers carry a key

Validate it, then serve it from this checkout with Postgres and Valkey in Docker:

uv run felix validate-manifest ~/felix-agents/triage.yaml   # --strict: warnings fail too (CI)
make db migrate                                # Postgres + Valkey on localhost, schema applied
FELIX_MANIFESTS_DIR=~/felix-agents make dev    # the API on :8080, serving manifests/ and yours
# in a second terminal:
curl -s -X POST http://localhost:8080/chat -H 'content-type: application/json' \
  -d '{"manifest":"triage","messages":[{"role":"user","content":"The export button does nothing"}]}' | jq

From there, the same manifest grows by adding primitives: tools, skills, memory, MCP servers and A2A peers, sub-agents and delegation, approvals and guardrails, execution.mode: durable, and a different pattern. Manifest capabilities lists them, manifests/governed.yaml uses most of them, and docs.felix.run covers each one. To give an agent a tool of your own, or a new pattern, model provider or store, write a plugin: examples/felix-plugin-example shows every seam, and Extending Felix explains them. The editor schema in the header line completes and checks every field as you type.

On a running stack, PUT /manifests/<name> with {"manifest": {...}} stores a manifest without a restart. That needs the manifests:write scope.

Run the full stack

make up               # migrates, then api :8080, worker, scheduler, pgvector, Valkey (fs object store)
curl -s http://localhost:8080/health | jq

The stack applies Alembic migrations in a one-shot migrate service before the api, worker and scheduler start, so there is no separate migration step for Compose.

Two alternatives to make up:

make up-lite          # tighter memory caps for ~2–4 GiB hosts
make up-full          # adds MinIO and the aws extra (FELIX_DOCKER_EXTRAS=aws)

make up runs scripts/dev-key.sh, which writes a local API key into .env on first run and prints it. The stack is authenticated by default and publishes on 127.0.0.1 — set FELIX_BIND_ADDR to widen it, but only behind real auth.

Export the key so the examples below work:

export FELIX_KEY=$(grep -o 'sk-felix-local-[a-f0-9]*' .env | head -1)

For cloud SDKs, embeddings, or browser tools locally, use make install-full.

Send a request

With the stack up, chat with a bundled example, quick:

curl -s -X POST http://localhost:8080/chat \
  -H "authorization: Bearer $FELIX_KEY" \
  -H 'content-type: application/json' \
  -d '{"manifest":"quick","messages":[{"role":"user","content":"What is 7 * 6?"}]}' | jq

Or use the OpenAI-compatible surface, where model is the manifest name:

curl -s http://localhost:8080/v1/chat/completions \
  -H "authorization: Bearer $FELIX_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"quick","messages":[{"role":"user","content":"hi"}]}' | jq

quick is stateless. For an assistant that remembers across sessions, send the same request to assistant: it captures durable facts from each turn, shows them to the next session, and has recall / remember / forget tools (forget waits for an approval). Memory is per person: each caller (issuer|subject — the dev key is api_key|local-dev) has a pool of their own, shared by every agent that works for them, and also sees what an operator wrote for the agent through /memory (spec.memory.scope: agent keeps an agent to its own pool instead). A request that names no person — anonymous, or a key with no sub — remembers nothing, so assistant refuses anonymous requests — under make dev (FELIX_AUTH_MODE=none) it answers 401; use the Compose stack and $FELIX_KEY.

Local development without Compose

make db migrate               # Postgres + Valkey in Docker on localhost; `make down` stops them
make dev                      # Granian on :8080, FELIX_AUTH_MODE=none, FELIX_OBJECT_STORE=fs
make cli                      # felix chat: a chat REPL against a running API
make check                    # ruff + ty + pytest + format check; STRICT=1 if the venv is lean
./scripts/test.sh -k <expr>   # one test; sets the in-memory stores the suite needs
make help                     # every target, grouped

Run tests with ./scripts/test.sh, never a bare pytest — the repo .env points at a real Postgres, so the suite would fail on connection errors that look like code bugs. See docs/TROUBLESHOOTING.md for this and other recurring failure modes. tests/README.md says where a new test goes.

make dev runs FELIX_AUTH_MODE=none: the API is unauthenticated and every caller holds every scope, and each boot logs a warning saying so. The mode is refused unless FELIX_HOST is a loopback address, but that check reads the setting, not the socket the server binds: a --host 0.0.0.0 on Granian's own command line passes it and serves the API to the network.

Deployment

Small VMs and lean images

Default images and Compose stay lean:

Concern Default Full / cloud
Object store FELIX_OBJECT_STORE=fs (local dir) s3 or gcs + felix-harness[aws] / felix-harness[gcp]
Image extras none FELIX_DOCKER_EXTRAS=aws,gcp
Compose api + worker + Postgres + Valkey --profile full adds MinIO
Memory Compose mem_limit caps raise via FELIX_*_MEM_LIMIT
make up-lite   # deploy/docker/compose.lite.yml — ~2–4 GiB hosts
make up-gcp    # GCE / public VM: no DB or cache host ports

Docker packaging lives under deploy/docker/. Always run Compose from the repo root — make up sets --project-directory ..

Heavy optional dependencies (Playwright, sentence-transformers, DuckDB, Presidio) are never in the default image. Install them through extras only when needed.

Observability

prometheus-client is a core dependency, so GET /metrics works on a lean image with no extras. Traces and OTLP logs need felix-harness[otel] and FELIX_OTEL_ENABLED=true.

make up-observability   # OTel Collector, Prometheus, Grafana, Jaeger, Loki, exporters

To export to a backend you already run instead, set the FELIX_OTEL_* variables in .env (they reach every process through compose.yml) and build with FELIX_DOCKER_EXTRAS=otel — no overlay, and nothing in Felix that names the destination. Spans carry the gen_ai.* semantic-convention attributes, so an LLM-observability backend renders a chat as a generation with model, tokens and cost. See deploy/docker/README.md.

Grafana lands on http://localhost:3000 with datasources provisioned and one dashboard built from the counters Felix actually emits — including a governance row for the controls deploy/GOVERNANCE.md tells operators to watch. Model calls are spans carrying the OpenTelemetry GenAI semantic conventions, so any OTLP backend renders them as generations with token usage and cost rather than anonymous timing bars.

/metrics is deliberately not public: its label values include tenant-supplied manifest ids and remote MCP tool names, so an anonymous scrape would disclose every tenant's manifests and tools — and since those span every tenant, it also needs the metrics:read scope (or admin / *). scripts/metrics-token.sh mints a scrape key holding metrics:read and nothing else, in a metrics tenant of its own, so it reads metrics and reaches no tenant's agents; run it again to upgrade a key it minted before the scope existed. In Kubernetes, set serviceMonitor.enabled=true and point it at a Secret holding the same kind of key.

docs/OBSERVABILITY.md is the metric catalog and span schema.

Analytics warehouse (optional)

Postgres is the system of record. The warehouse is optional append-only spill for audit and eval analytics, flushed by the worker after the Postgres write.

Choice When to use it Extra
none Lean default; no analytics spill —
duckdb Recommended. Small VMs; embedded file under FELIX_DATA_DIR/warehouse warehouse
clickhouse High-volume audit and event scale-out warehouse-clickhouse
doris Already operating Apache Doris or MySQL-protocol BI warehouse-doris
uv sync --extra warehouse     # or: make install-warehouse
# Then set: FELIX_WAREHOUSE=duckdb
# In Docker: FELIX_DOCKER_EXTRAS=warehouse FELIX_WAREHOUSE=duckdb

Architecture

Client → Ingress (Caddy / Traefik / nginx / Cloudflare DNS+CDN)
           ├─ felix-api        (CPython 3.14, Granian, FastAPI)
           ├─ felix-worker     (Taskiq consumer)
           └─ felix-scheduler  (Taskiq cron enqueue)
                  │
     Postgres+pgvector · Valkey · object store (fs | S3 | GCS)
Component Responsibility
apps/api HTTP: /chat, /v1, /a2a, /mcp, management APIs, OpenAPI
apps/worker Audit flush, scheduled jobs, memory consolidation, retention, anomaly scan, continuous eval, fiber resume, skill improvement and evaluation
felix-scheduler Enqueues labeled Taskiq cron tasks — required alongside the worker, or nothing periodic fires
packages/ai Model layer: wire formats, catalog, turn types. Imports nothing from felix
packages/harness Manifests, patterns, tools, session, governance, auth, plugins
apps/cli felix migrate | eval | mint-jwt | login | ingest-docs | skills | workspace | sessions | bundle-manifests | validate-manifest | doctor | version
manifests/ Bundled agents: quick, assistant, deep, router, oss-only, hybrid-router, support, decider-support, cowork, code, governed, contributor, triage

Vendor independence

Felix is service- and cloud-agnostic: the harness talks to Postgres, a cache, and an object store through Protocols, not a single vendor SDK.

AWS and GCP are first-class — S3, Secrets Manager, GCS, and Secret Manager via the optional felix-harness[aws] and felix-harness[gcp] extras. Small VMs can use FELIX_OBJECT_STORE=fs with zero cloud SDKs.

  • Set FELIX_OBJECT_STORE to s3, gcs, fs, memory, or a backend you register
  • Set FELIX_SECRETS_BACKEND to env, file, aws, gcp, or a backend you register
  • A manifest's secret:NAME refs resolve only names FELIX_MANIFEST_SECRETS lists for the tenant (a JSON map of name → [tenant, …] or "*"; empty allows none). Felix's own secrets — any FELIX_* name, the provider and sign-in keys, DATABASE_URL, REDIS_URL — are refused whatever it says. PUT /manifests answers 422 for an unlisted ref, and compiling refuses it before the backend is asked
  • An MCP server's auth: person:<provider> sends the caller's own token only to a server FELIX_MCP_PERSON_AUTH lists for that provider and tenant ({"github": [{"url": …, "tenants": […]}]}; empty allows none). PUT /manifests answers 422 for any other, and compiling leaves it out
  • Deploy notes: deploy/aws/, deploy/gcp/
  • Manifest secrets, plus opt-in SOC 2 and EU AI Act mapping: deploy/GOVERNANCE.md
  • Helm: enable persistence when using fs, so /data survives restarts
  • Production JWT and api_key deploys need FELIX_CONSUMER_SHARED_SECRET for POST /internal/*
  • Retention: the worker's nightly sweep prunes audit_events, usage_events, finished fibers and a2a_tasks, and (off by default) idle session threads — FELIX_AUDIT_RETENTION_DAYS (30), FELIX_USAGE_RETENTION_DAYS (365), FELIX_FIBER_RETENTION_DAYS (7), FELIX_WORKFLOW_RUN_RETENTION_DAYS (30; finished workflow runs), FELIX_SCHEDULED_TASK_RETENTION_DAYS (30; one-shot agent-scheduled tasks that have fired, never an operator's job), FELIX_MEMORY_TASK_RETENTION_DAYS (30; agent-written task memories untouched this long are forgotten, not deleted — restorable with POST /memory/{id}/restore, and never an operator-written one), FELIX_JOB_RUNS_KEEP (200; run records kept per job, newest first, trimmed after each run rather than nightly — 0 keeps all; the current UTC day's runs stay until it ends, since a heartbeat's daily cap counts them), FELIX_SESSION_RETENTION_DAYS (0 = keep), FELIX_APPROVAL_RETENTION_DAYS (0 = keep, and only settled approvals — a grant that can still authorize is never swept), FELIX_ATTACHMENT_RETENTION_DAYS (0 = keep; the one sweep that deletes bytes as well as rows, since attachments/ is an object-store prefix nothing else collects), FELIX_ARTIFACT_RETENTION_DAYS (30; spilled tool outputs, bytes and ledger row, the same way — on by default because spill is the harness's working copy), FELIX_FILE_CHECKPOINT_RETENTION_DAYS (7; what the file tools changed, kept for /chat/rewind with restore_files, bytes and ledger row, counted from each file's last change in its thread; FELIX_FILE_CHECKPOINT_MAX_BYTES_PER_TENANT caps the content kept, 256 MiB; FELIX_FILE_CHECKPOINTS=false records none); a manifest's governance.retention_days shortens the audit TTL for its own rows
  • Memory per person: a person is issuer|subject, so an API key's sub and a sign-in's subject are different people even when the strings match. FELIX_PRINCIPAL_ALIASES (empty) maps one person to the person they belong to, as JSON ({"google:123":"github:70701"}; a value with no | is Felix's own sign-in issuer, felix-self), so one person signing in two ways keeps one memory; one hop, and a target that is itself an alias, or a shared credential on either side, refuses the boot. Memory alone reads it. A person's agents see only operator-written rows of an agent's own pool, so what an agent learnt before people had pools reaches no one until felix memory assign --tenant T --manifest M --to PERSON [--include-operator] [--dry-run] moves it into the person's; a row they already hold is merged, not overwritten, and a re-run moves nothing. Isolation between people is the memory store's filter inside the tenant; memory:read/memory:write span everyone (see deploy/GOVERNANCE.md)
  • Approvals: FELIX_APPROVALS_REQUIRE_SECOND_PERSON (false) refuses an approval's answer from the person whose run asked for it, so a second person (or an admin) must decide; see deploy/GOVERNANCE.md
  • Uploads: FELIX_ATTACHMENTS_MAX_BYTES_PER_TENANT (256 MiB, 0 = no ceiling) bounds what one tenant may store through /files, on top of the 600 KiB per-upload cap. Over the ceiling answers 409. On the default fs store this shares a disk with artifact spill and manifest storage, so the ceiling is what keeps one tenant from degrading every other one

Sizing. Each worker process carries its own connection pool, so raise the two together: FELIX_WORKERS (1) and FELIX_DB_POOL_SIZE (10) + FELIX_DB_MAX_OVERFLOW (20) — past that ceiling requests queue for FELIX_DB_POOL_TIMEOUT_SECONDS and then fail. Set FELIX_DB_POOL_PRE_PING=false against a direct Postgres; it costs a round trip per checkout and only earns it behind PgBouncer, RDS Proxy, or Cloud SQL. Connections give up after FELIX_DB_CONNECT_TIMEOUT_SECONDS (10) and every connection is application_name=felix-<role> in pg_stat_activity. A statement timeout belongs on the role (ALTER ROLE felix SET statement_timeout), not in the client — a client-side one does not survive a pooler; felix doctor reports what applies. On SIGTERM a worker gets FELIX_GRACEFUL_SHUTDOWN_SECONDS (120, the Helm chart's grace period) to finish in-flight requests before it is killed.

Behind a pooler. WORKERS × (POOL_SIZE + MAX_OVERFLOW) is the ceiling, and four workers on the defaults is 120 connections against a stock Postgres max_connections of 100 — which is when a transaction-mode pooler stops being optional. Set FELIX_DB_PREPARED_STATEMENTS=false there: psycopg3 auto-prepares after five executions, and under transaction pooling the sixth lands on a different server connection and fails. PgBouncer ≥ 1.21 with max_prepared_statements > 0 tracks them for you and needs no change; RDS Proxy instead pins the session when it sees one, defeating the multiplexing you deployed it for, so turn preparation off there.

Extending Felix

Felix is built to not dictate your workflow. Features other harnesses bake in are meant to be added from outside: core stays minimal, and the seams below are open by design.

Install a package that declares a felix.plugins entry point and core discovers it at startup — Felix never imports it by name:

[project.entry-points."felix.plugins"]
my-plugin = "my_plugin:register"

register(registry) is then called once. Through the registry a plugin adds tools, HTTP routes, cron tasks, auth modes, rate-limit keys, body limits, self-authenticating mounts, startup hooks, audit/usage sinks, and eight agent-loop hooks (before_turn, filter_history, before_compact, before_model, after_model, before_tool, after_tool, compact_failed).

Core also exposes open registries, callable at import time, each selected by ordinary config:

Register Selected by
register_pattern spec.pattern
register_model_provider FELIX_MODEL_ROUTES
register_decision_provider FELIX_DECISION_ROUTES
register_object_store FELIX_OBJECT_STORE
register_secrets_backend FELIX_SECRETS_BACKEND
register_warehouse_backend FELIX_WAREHOUSE
register_embedder_backend FELIX_MEMORY_EMBEDDER
register_search_backend FELIX_SEARCH_BACKEND
register_session_strategy spec.session.strategy
register_checkpointer spec.memory.checkpointer

A plugin carries its own manifest config under spec.extensions.<name> — the one field exempt from the schema's extra="forbid" — and reads it from the pattern build context.

Agent Skills need no code at all: put a skill at <FELIX_SKILLS_DIR>/<name>/SKILL.md (check it with felix skills validate), or upload one per tenant to the object store. In a react agent, a person runs one by typing /skill-name args in a chat turn, and a manifest can start every conversation with one (spec.skills: [{name: x, preload: true}]). A manifest with spec.skill_authoring.enabled lets its agent draft skills into the tenant's library; a draft enters no catalog until it is published, and publishing is gated — a failing security scan always blocks, FELIX_SKILL_PUBLISH_MIN_QUALITY (0 = off) sets a floor on the 0-100 review score, and FELIX_SKILL_PUBLISH_BLOCK_ON_ADVISORY (false) also refuses an advisory scan. Operators review the queue, author, publish, roll back and archive through /skill-library (skills:read to read, skills:write to change). The agent can also file feedback on a library skill (submit_skill_feedback), as can an operator. A person's accept is the only thing that has the worker rewrite the skill from it, with FELIX_SKILL_IMPROVE_MODEL (empty = the default route), and the rewrite is a draft for review. POST /skill-library/{name}/versions/{v}/eval scores a version against a baseline without it: FELIX_SKILL_EVAL_MODEL answers each scenario with and without the skill, FELIX_SKILL_EVAL_JUDGE_MODEL scores both answers 0-100, and FELIX_SKILL_EVAL_MAX_SCENARIOS (10) caps the run. For an agent-written version only an evaluation on the bundle's own evals/ scenarios counts. FELIX_SKILL_PUBLISH_REQUIRE_EVAL and FELIX_SKILL_PUBLISH_MIN_EVAL_UPLIFT add an evaluation requirement for the whole deployment. PATCH /skill-library/-/policy lets a tenant tighten every bar, never loosen it. Skill jobs are bounded per call (FELIX_SKILL_EVAL_MAX_TOKENS, FELIX_SKILL_IMPROVE_MAX_TOKENS), per job (FELIX_SKILL_JOB_DEADLINE_SECONDS) and per tenant (FELIX_SKILL_JOBS_MAX_QUEUED, FELIX_SKILL_JOBS_DAILY_LIMIT).

Skills published on GitHub come in the same way: GET /skill-library/-/browse?source=github:owner/repo lists the skills a repository offers (skills/*, .claude/skills/*, Claude Code plugin layouts and the other common roots) at one resolved commit, and POST /skill-library/-/import (or felix skills add github:owner/repo/path) fetches one as a draft, pinned to a commit of the repository's own history, with its source, ref, commit and license on the version. An import is never published in the same request: a person reads the draft, then publishes it. A re-import saves a new version only when the skill's files changed. Imported text is third-party instructions, so it — and every version built on it — is held to a stricter gate (an advisory scan blocks its publish whatever the policy says), and what activate_skill returns of it is screened as untrusted tool output where the manifest enables content screening. FELIX_SKILL_IMPORT_SOURCES (empty = any GitHub source) limits which repositories may be named, per tenant (acme=github:acme/*); FELIX_SKILL_IMPORT_GITHUB_TOKEN (optional) reaches private ones and lifts the anonymous rate limit, and outside a development box refuses to boot unless every allowlist entry names a tenant and a literal owner. FELIX_SKILL_IMPORT_MIN_AGE_DAYS (0 = off) is a supply-chain cooldown counted from when the tenant first saw a skill's exact files (never from a commit date, which the pusher sets): until then an import is refused outright, and a tenant can raise the bar (import_min_age_days in its policy) but not lower it. Every GitHub call is charged against FELIX_SKILL_IMPORT_CALLS_PER_HOUR (per tenant, 500) and FELIX_SKILL_IMPORT_CALLS_PER_HOUR_TOTAL (4000).

An imported skill is checked against its origin with GET /skill-library/{name}/-/upstream (felix skills diff): the commit its ref names now, whether the files moved, when the cooldown lets them in, and a per-file diff against the live version. POST /skill-library/{name}/-/update (felix skills update) re-imports it as a new draft, never published; GET /skill-library/-/upstream (felix skills outdated) lists every imported skill's state, 25 at a time. Once a person has read an import and vouches for it, POST /skill-library/{name}/versions/{v}/adopt with a reason (felix skills adopt <name> <v> --reason ..., skills:write) saves its files unchanged as a new operator draft that is no longer held to the import gate or screened as third-party text; the earlier versions keep their mark, the draft is published the ordinary way, and the skill stops following its origin. FELIX_SKILL_IMPORT_CHECK_HOURS (0 = off, up to 168) has the worker check them on that cadence, spending at most half of each budget, so the listing and the library detail can answer without asking GitHub. FELIX_SKILL_UPDATE_WEBHOOKS (acme=ops,acme=ci, each id a FELIX_WEBHOOK_ENDPOINTS endpoint open to that tenant; no wildcard) announces each new upstream digest once as a signed skill.update_available event — metadata only, sent by the worker with the completion webhooks' signing and retries, never from the check itself. Give the API and the worker the same FELIX_SKILL_UPDATE_WEBHOOKS and FELIX_WEBHOOK_ENDPOINTS: both run checks, and only the worker sends.

examples/felix-plugin-example/ is a working package that exercises every seam above.

Two things are deliberately not extensible: the nine-wrapper governance order in manifests/builder.py (order defines precedence, so before_tool / after_tool hooks are the sanctioned boundary instead), and spec.guardrails.providers. Both have their rationale recorded in docs/ROADMAP.md.

API surfaces

Surface Path
Direct REST / SSE POST /chat, POST /chat/stream
Durable run poll GET /chat/runs/{resume_token}
Steer / follow-up POST /chat/steer
Operator edited a workspace file POST /chat/workspace/edited
Thread workspace files (file pane) GET /chat/workspace/tree, GET /chat/workspace/file, POST /chat/workspace/write, POST /chat/workspace/delete, POST /chat/workspace/rename
Abort / continue POST /chat/abort, POST /chat/continue
Thinking level POST /chat/thinking
Session snapshot GET /chat/sessions, GET /chat/sessions/{id}
Session search (FTS) GET /chat/sessions/search?q=
Session lease POST /chat/sessions/lease, …/lease/release, GET /chat/sessions/{id}/lease
Session name / label / export POST /chat/sessions/name, …/label, GET …/export
Compact / UI prompt POST /chat/compact, POST /chat/ui
Side question (read-only) POST /chat/ask
Session fork / rewind POST /chat/fork, POST /chat/rewind
OpenAI-compatible POST /v1/chat/completions, GET /v1/models
A2A JSON-RPC POST /a2a
MCP POST /mcp (the default manifest), POST /mcp/{manifest}
Agent card GET /.well-known/agent-card.json
Liveness / readiness GET /live (also /health), GET /ready
Scheduler heartbeat GET /health/scheduler — 503 when felix-scheduler stopped sweeping; for an external monitor, not a probe
Worker heartbeat GET /health/worker — the running worker's version, 503 when none has beaten within FELIX_WORKER_STALE_SECONDS (60); what a deploy waits on, not a probe
Metrics GET /metrics — authenticated, see below

/mcp is the official mcp Python SDK's stateless Streamable HTTP transport, serving a manifest's governed tools compiled as the caller. It speaks both protocol eras: a 2026-07-28 client (per-request _meta, server/discover, the MCP-Protocol-Version / Mcp-Method / Mcp-Name headers) and a legacy initialize client (2025-11-25 and earlier). Point an MCP host at /mcp/{manifest} to reach a given agent; a legacy client may instead name one in params.manifest. Every exchange is one POST, so there is no session and a GET is answered 405.

Felix serves an API, not a web UI, and browsers on another origin cannot call it directly, by design. The chat UI and docs live in felix-run/web; test_invariants.py fails on any static file, template or mounted sub-app here. There is no CORS layer. A preflight OPTIONS gets a 401 (or a 405 under auth_mode=none) with no Access-Control-Allow-* headers, so the browser blocks the request before it is sent. A plain GET does reach Felix, but the page is not allowed to read the answer. Felix has no browser login of its own (no cookies), so a page could only call it by holding a bearer token or API key, where any script on that page can read it. Put a server-side proxy on the page's own origin in front of Felix instead: it holds the credential and forwards /api/* to the API. felix-web's chat UI does this from a Worker (FELIX_ORIGIN, with an optional x-chat-key gate for its own clients), and any reverse proxy that adds the Authorization header works the same way. Non-browser clients — the CLI, felix-client, curl, other services — are unaffected.

A failed send is safe to resend: POST /chat and POST /chat/stream take an Idempotency-Key header, and a resend under the same key never runs a second turn — /chat returns the stored response, /chat/stream replays what the first request wrote to its thread (see deploy/GOVERNANCE.md). Session leases are advisory by default; FELIX_LEASE_ENFORCE=strict refuses a driving request that presents no X-Felix-Lease-Token while another client holds the thread.

An operator who edits, deletes or renames a workspace file directly can say so with POST /chat/workspace/edited ({thread_id, path, op: write|delete|rename, bytes?, to_path?} — structure only; the server writes the text the model reads). A run in flight reads it before its next model call without cancelling any tool call, unlike a steer, and its stream carries a workspace_note frame ({path, op, bytes}, plus to_path for a rename); with no run in flight it is appended for the next one. Either way the thread's log holds it once, as an in-context custom entry with metadata.type: workspace_edit. Lease-guarded like /chat/steer.

A client can also show and edit the thread's workspace itself, in the same directory the agent's next turn works in. GET /chat/workspace/tree?thread_id= lists it recursively ({root_kind: scoped|checkout, scope, manifest, entries: [{path, type: file|dir, bytes?}], truncated}; limit defaults to 2,000, at most 5,000; no symlink is followed or listed, and .git and .felix-scopes are left out). GET /chat/workspace/file?thread_id=&path= returns one file whole ({path, bytes, sha256, encoding: utf-8|base64, content}), refusing one over the workspace tools' 512,000-byte read cap with 413 too_large. POST /chat/workspace/write ({thread_id, path, content, expected_sha256?}) replaces a file atomically and folds in the same note /chat/workspace/edited sends; with expected_sha256 it is refused with 409 {detail: workspace_changed, sha256, bytes} when the file is no longer what was read, so an operator's save never silently overwrites the agent's. POST /chat/workspace/delete ({thread_id, path, expected_sha256?} → {status, path, event_id}) and POST /chat/workspace/rename ({thread_id, path, to_path, expected_sha256?} → {status, path, to_path, sha256, event_id}) act on regular files only (400 not_a_file for a directory, 404 not_found for a missing file), compare the same way (409 workspace_changed), and fold in the op: delete / op: rename note; a rename makes the directories to_path needs and never replaces anything (409 target_exists). For folders, POST /chat/workspace/delete_folder ({thread_id, path, expected_count?} → {status, path, files, event_id}) removes a folder and everything in it, and POST /chat/workspace/rename_folder ({thread_id, path, to_path} → {status, path, to_path, event_id}) moves one; operator-only (the agent's tools stay files-only). Neither follows a symlink — one inside a deleted folder is removed as the link, never its target — and both refuse, before anything changes, the root (400 invalid_path), a file (400 not_a_directory), a folder that is or holds .git / .felix-scopes (400 reserved_path), and one over 2,000 entries (409 {detail: too_many_entries, count}). expected_count is the number of files the operator was shown: a folder that holds a different number now is 409 {detail: workspace_changed, count} and nothing is deleted. A folder rename never replaces anything (409 target_exists) or moves a folder into itself (400 invalid_path). Each folds in a note with kind: folder (and files for a delete). The workspace is decided server-side: a thread's repository checkout when it has one, otherwise the spec.workspace.scope of the manifest the thread last ran under — or, for a thread that has never run, of the manifest the caller names (else FELIX_DEFAULT_MANIFEST). The caller never chooses a scope. Writes, deletes and renames are lease-guarded and audited as workspace_write, workspace_delete, workspace_rename, workspace_delete_folder and workspace_rename_folder. Each /v1/models entry says where its agent keeps files: felix.workspace is {tools: server|client|both|none, scope}.

An agent deletes and renames workspace files with the delete_file ({path}) and rename_file ({path, to_path}) tools, on the same backend operations: files only, no symlink followed, nothing inside .git or .felix-scopes, and a rename never replaces anything. Neither is bound unless a manifest lists it; the bundled manifests that bind write_file bind both, gated no less than write_file is, since a delete has no undo. A client that runs the user's own folder declares the same pair as client tools; the bundled cowork manifest's are local_delete and local_rename, behind the same workspace-write approval as local_write and local_edit.

The bundled code agent builds on cowork for coding tasks: it reads repository instructions, preserves uncommitted work, makes focused changes, and verifies results. Its file tools work in the connected client's folder, and file mutations and shell commands require approval. With a running harness and an API key configured, build the companion TUI (pnpm tui:build in felix-web) and start it from the project directory:

bun /path/to/felix-web/apps/tui/dist/felix.js --manifest code --shell

--shell enables real, noninteractive commands and asks locally before each command, including under --yes. An approved command has your account's access; the initial working directory is checked, but the command is not sandboxed. Without --shell, the terminal and browser emulate a small set of file commands. The code agent's durable run lifetime is two hours; a caller token's expiry can shorten it. Cowork remains a separate agent.

For multi-step tasks, code records a persisted plan and updates it as work finishes; the browser and TUI display these plan calls. In plan mode it can list, read, and search project files while file changes and shell commands remain blocked until the user approves leaving plan mode. The read-only local_info tool reports the connected client's workspace and native or emulated shell support before the agent chooses commands. Update the companion client to use this tool; older clients can still use the file tools. local_instructions finds AGENTS.md and CLAUDE.md along a target file's parent directories, including for new files, with explicit continuation offsets for truncated instructions. Client local_edit checks the contents used to construct its replacement again before writing. If the file changed while terminal confirmation was pending or a browser write was staged, the edit fails so the agent can reread and reconcile the newer work. This check does not lock out other programs writing to the project. Terminal delete and rename recheck the approved source. Rename uses an exclusive hard link before unlinking the source, so it cannot replace a destination created during approval; cross-filesystem moves are refused. A partial move can retain both names. Browser rename also retains its source if its contents changed during the copy.

To verify the built terminal against the real API and durable fiber loop with temporary in-memory stores and a scripted model, run uv run python scripts/smoke-code-tui.py in this repository. --tui /path/to/felix.js selects a build outside the default sibling felix-web checkout.

A dropped stream is recoverable: structural SSE frames carry an id: cursor (token-level frames do not, which per the SSE spec leaves the client's lastEventId on the last one it saw), and GET /chat/stream/{thread_id} replays what was missed (or opens with a snapshot frame) and then tails the thread. A foreground run ends on disconnect, so reattachment recovers its thread log. A durable run, including code and cowork, continues in the worker; reconnecting resumes status and pending approvals or client-tool requests. A client must be connected to answer those requests.

Management surfaces: /audit, /approvals, /plans, /workflows, /jobs, /heartbeats, /manifests, /eval, /usage, /memory, /skill-library. A job's schedule is seconds, every:30m, an @hourly/@daily/@weekly/@monthly/@yearly macro, five-field cron, or a one-shot at:<ISO-8601 with offset>; cron and macros are read in UTC unless the job names an IANA timezone ({"schedule": "0 8 * * 1-5", "timezone": "America/New_York"} is 08:00 New York time on weekdays, all year). Across a daylight-saving change a time the clocks skip fires at the first instant after the gap and a time they repeat fires once, at its first occurrence; a zone beside an interval or at:, which no zone moves, is refused. A job's reader writes its preferences over PUT /jobs/{name}/preferences (free text, at most 8 KiB: what to cover, skip, tone, length) — the job's own writer, who needs no jobs scope (so a person steers the task an agent scheduled for them), or an operator; not every jobs:write holder. Every firing carries them whole in its prompt; the agent cannot change them; re-saving the job keeps them, and a re-save by someone else clears them. A job with "preferences_required": true and none yet runs nothing: its run is recorded skipped, "waiting for its reader's preferences". A manifest with spec.state lets the job's runs keep their own state — bookmarks per source, a ledger of what they did — which the same people read and clear over GET/DELETE /jobs/{name}/state; it goes with the job, and a re-save by someone else clears it. POST /jobs/{name}/run runs a job now instead of waiting for cron (409 job_running while a run of it is in flight; a job's runs are unattended, so an approval rule without allow_unattended refuses a gated call rather than waiting — see deploy/GOVERNANCE.md); GET /manifests/{name}/versions lists what a rollback can go back to. /workflows holds authored workflow definitions — typed steps wired port to port — and answers each save with the ports and problems the editor draws, conditional on If-Match; POST /workflows/{id}/runs runs one durably — each agent step a child durable run on its own thread, tool steps through their manifest's governed tools, approval steps through /approvals — and GET /workflows/{id}/runs/{run} shows every step; a job naming a workflow_id starts one on its schedule. /memory lists, searches (the same hybrid ranking the agent sees), time-travels (/memory/as-of/{turn_seq}, narrowed to one conversation with ?thread_id=, since a turn number orders one thread's log), writes, forgets and restores (POST /memory/{id}/restore; ?status=forgotten lists what was forgotten) long-term memories; ?principal= narrows a read to one person's pool (empty for agent pools), and a write's principal puts it in that person's — an agent that remembers across sessions otherwise accumulates a store nobody can inspect.

Python client (experimental): the felix-client package — from felix_client import FelixClient — covering chat (prompt, stream, steer, follow_up, workspace_edited, fork, rewind, set_model), the thread's workspace (workspace_tree, workspace_read, workspace_write, workspace_delete, workspace_rename, workspace_delete_folder, workspace_rename_folder), durable runs with their polling, and approvals. It depends on httpx and nothing in Felix, so installing it does not install the server; its surface may change between releases without a deprecation period. Not yet on PyPI — install it from the repository: pip install "felix-client @ git+https://github.com/felix-run/felix#subdirectory=packages/client". For everything else, and as the contract, use the HTTP API: each release attaches its openapi.json, from which a client in any language can be generated. from felix.sdk import FelixClient still works inside the harness.

Models

FELIX_MODEL_TIMEOUT_SECONDS (default 120) bounds each HTTP request to a model provider. Generating a large tool call — a file's contents as an argument, say — can exceed it, and the failure surfaces as a failed run rather than a slow one. On a streaming call it bounds the gap between chunks rather than the whole turn. Read and write timeouts are deliberately not retried: the retry re-sends identical input and waits out the identical ceiling, so the answer is a larger timeout, not another attempt. Connect timeouts still retry, and connect is pinned at 10s so raising this does not also let an unreachable provider hang.

Outbound integrations carry their own ceilings: spec.mcp_servers[].timeout_ms (default 30s), spec.peers[].timeout_ms (default 60s), and the existing timeout_ms on sandboxes and containers.

Providers Felix ships, all speaking one of two wire formats:

Provider Endpoint Configured with
anthropic api.anthropic.com FELIX_ANTHROPIC_API_KEY
openai api.openai.com/v1, or FELIX_LITELLM_BASE_URL FELIX_OPENAI_API_KEY
workers_ai api.cloudflare.com/…/accounts/{account_id}/ai/v1 api_key, account_id, optional gateway_id
groq together deepseek cerebras fireworks openrouter xai mistral google each vendor's OpenAI-compatible endpoint api_key

Everything past the first two is configured through FELIX_MODEL_PROVIDER_OPTIONS rather than a settings field per vendor. Each is also selectable as FELIX_MEMORY_EMBEDDER, since /embeddings is part of the same wire format.

The hosted tier ships without per-token rates, deliberately, except Workers AI. Felix does not invent prices: an unpriced model contributes zero to spend and a manifest that declares limits.max_cost_usd on one is refused at compile, pointing at spec.model.price. Guessing is how every unrecognised model came to be billed at Claude Sonnet's $3/$15 per Mtok. Workers AI is the exception because Cloudflare publishes a per-token rate for each model (it meters in neurons and states the conversion), so the catalog carries those rates for the models behind the -cf routes below and a few more, under @cf/ keys, and a spend cap holds on them. Any other @cf/ id stays unpriced. The 10,000 free neurons a day are not subtracted, so spend reads high rather than low.

A provider is a descriptor — a wire format, an endpoint, and where its credential lives — so adding one is a row rather than a module. Both wire formats and the HTTP transport are public in felix_ai.wire (OpenAICompletionsClient, AnthropicMessagesClient, post_with_retry, map_stop, parse_tool_arguments), because re-deriving retry-on-429, SSE parsing and usage accounting is most of the work of writing a provider — and what a provider gets wrong in usage reporting fails open on limits.max_cost_usd.

FELIX_MODEL_PROVIDER_OPTIONS carries a per-provider endpoint and credential as JSON. The built-in providers have named settings, but a provider added by a plugin cannot — Settings ignores unknown env vars — so this is how an installed provider is given a key. An entry also overrides the named field, which is how a built-in is pointed at a gateway:

FELIX_MODEL_PROVIDER_OPTIONS={"anthropic":{"base_url":"https://gateway.internal/v1"}}

Every option value is added to the redaction list except the ones the provider consumes as addressing — base_url, any {placeholder} its endpoint templates, and its header options — so a credential cannot reach tool output whatever the option is called. The converse is worth knowing: an unrecognised option is redacted, so a long, non-secret value there will be masked out of tool results. Keep credentials out of base_url, which is exempt by definition and also reaches server logs through connection errors. Providers named in FELIX_MODEL_ROUTES are resolved against the registry at startup, so a typo fails immediately rather than on the first request that happens to take that route.

Manifests reference logical model ids, mapped to wire ids by FELIX_MODEL_ROUTES (a JSON override) or by the built-in defaults:

Logical id Provider Wire model
claude-opus anthropic claude-opus-5-5
claude-sonnet (default) anthropic claude-sonnet-5-5
claude-haiku anthropic claude-haiku-5-5
claude-fable anthropic claude-fable-5-1
claude-sonnet-4 / claude-haiku-4 anthropic legacy ids, now claude-sonnet-5-5 / claude-haiku-5-5
gpt-4.1 / gpt-4.1-mini openai same
glm-5.3-cf workers_ai @cf/zai-org/glm-5.3 (1M, text only)
glm-5.3-flash-cf workers_ai @cf/zai-org/glm-5.3-flash (1M, vision)
deepseek-v4-pro-cf / deepseek-v4-flash-cf workers_ai @cf/deepseek-ai/deepseek-v4-pro-0813 / @cf/deepseek-ai/deepseek-v4-flash-0731 (1M, text only)
qwen3.8-27b-cf workers_ai @cf/qwen/qwen3.8-27b (262K, vision)
kimi-k2.7-code-cf workers_ai @cf/moonshotai/kimi-k2.7-code (262K, vision)
kimi-k2-cf workers_ai @cf/moonshotai/kimi-k2.6 (262K, vision)
gpt-oss-120b-cf / gpt-oss-20b-cf workers_ai @cf/openai/gpt-oss-120b / @cf/openai/gpt-oss-20b (text only)
glm-flash-cf workers_ai @cf/zai-org/glm-4.7-flash (text only)
llama-3-pro / llama-3-fast workers_ai legacy ids, now @cf/zai-org/glm-5.3 / @cf/zai-org/glm-5.3-flash

A turn that carries an image and is bound for a model the catalog marks text-only goes to spec.model.vision_model, or FELIX_DEFAULT_VISION_MODEL_ID when the manifest names none — so a cheap text route can stay the default and a picture still gets looked at. The image stays in the thread's history, so every later turn of that thread also goes to the vision route, until compaction or a window drops it. The vision route fails over to whichever of spec.model.fallbacks can see — a text-only fallback is skipped — and has no escalation of its own. With neither set, the request is refused with a 422 naming the route instead of reaching a model that would answer that it cannot see. A custom route declares what it accepts with a modalities key, which the catalog cannot know for an arbitrary model: {"vision":{"provider":"workers_ai","model":"@cf/meta/llama-3.2-11b-vision-instruct","modalities":["text","image"]}}. A model the catalog cannot vouch for either way is sent the image as before.

Every -cf route supports tool calling and is priced, so limits.max_cost_usd is enforced on it. GLM-5.3, GLM-5.3 Flash, DeepSeek V4 and Kimi K2.7 Code need the Workers Paid plan (or AI Gateway credits). llama-3-pro and llama-3-fast used to route to a local Ollama, which Felix no longer ships, and are kept so manifests naming them still resolve. @cf/meta/llama-3.3-70b-instruct-fp8-fast is priced too but has no default route: Workers AI serves it with a 24K window, smaller than an agent's prompt with a skill catalogue.

A streaming turn is one model call. POST /chat/stream emits deltas from the same request that produces the turn's tool calls, usage and stop reason, so the text a client watches arrive is the text that gets saved. A provider integration that implements only the text-oriented stream() still falls back to streaming for display and calling the model again for the authoritative turn.

Side requests made during a turn — compaction summarising, memory extracting facts, inbound screening scoring, branch summarisation — opt out of the conversation's prompt cache. Each carries a completely different prefix, so sharing the thread's cache identity churns the cached prefix the next real turn would have hit, and writes a cache entry that is never read again.

Model calls retry rate limits and transient upstream failures with backoff, honouring Retry-After up to a ceiling; a 429 that reports a spent quota or a billing problem is returned straight away, since that will not clear inside the request. spec.model.fallbacks still switches models once retries are exhausted. Recalled memory facts are rendered as a per-run prelude rather than folded into the system prompt, so the cached prompt prefix stays stable across turns.

Everything Felix knows about a model — context window, max output, price, accepted request parameters, thinking support, modalities — lives in one record per family in felix/model_catalog.py, resolved by the longest key appearing in the model id. Request shaping, /v1/models, and cost estimation are all views over it. The current Claude generation takes adaptive thinking plus output_config.effort, while pre-4.6 models take a fixed budget_tokens. A thinking level is sent as the level's budget where a model takes one, and as an effort where it takes that instead — minimal and low as low, then medium, high, xhigh and max by name, with xhigh clamped to high on a model without that tier, and everything above high sent as high for OpenAI's reasoning_effort. A spec.model.thinking_budget with no level works on both: where an effort is needed it takes the effort of the highest level whose budget it reaches (1,024 → medium, 2,048 → high, 8,192 → xhigh, 32,000 → max).

An id with no exact entry defaults in two directions on purpose: the request shape assumes the current generation, because sending a parameter a model has removed is a hard 400 while omitting an optional one is not, and the context window stays conservative, because over-advertising a window invites a request the model will reject.

Extended thinking is stateful once tools are involved: the provider signs each thinking block, and a later turn replaying a tool call has to replay the signed reasoning that produced it. Thinking blocks are captured off the response, persisted on the session event, and replayed ahead of the tool_use blocks on the next request. A block whose signature was not captured is dropped rather than sent, because an unverifiable signature rejects the whole turn.

Decision models

Some model calls make a decision rather than write text — which tool fits this request, which sub-agent should take it, whether a reply meets a criterion. A decision model answers those as typed questions (Choice, Score, Noul, the vocabulary of felix_ai.decide) and returns calibrated probabilities with a confidence, instead of prose to parse. They are routed separately from chat models, by FELIX_DECISION_ROUTES, and share credentials with the model provider of the same name in FELIX_MODEL_PROVIDER_OPTIONS:

Logical id Provider Wire model Configured with
clef workers_ai (…/accounts/{account_id}/ai/run/@cf/cloudflare/clef) @cf/cloudflare/clef api_key, account_id, optional gateway_id
clef-flash workers_ai (…/ai/run/@cf/cloudflare/clef-flash) @cf/cloudflare/clef-flash as clef
jev typesafe (api.typesafe.ai/v1/systemone) jev-latest api_key
jev-cf workers_ai (…/accounts/{account_id}/ai/run) typesafe/jev api_key, account_id, optional gateway_id

Clef is Cloudflare's open-weight (Apache-2.0) decision model, Jev-API compatible, with a 64K context: $0.24 per million input tokens, or $0.09 for the faster clef-flash, output free. It shares the Workers AI credential the chat routes already use, so a deployment on Workers AI needs nothing new. Jev is TypeSafe's, priced at $0.042 per million input tokens with output free. The llm provider answers the same questions with any chat route — FELIX_DECISION_ROUTES={"haiku-decider":{"provider":"llm","model":"claude-haiku"}} — so nothing depends on a second vendor; it reports its pick with no confidence, because a chat model's self-assessed certainty is not calibrated. Every decision is metered like a model turn and counts against limits.max_cost_usd.

A manifest names its decider once, under spec.decider, and each consumer opts in — manifests/decider-support.yaml switches on every one that fits a support agent, and is the one to copy from:

spec:
  decider: {id: jev, min_confidence: 0.5}
  tools_retrieval: {enabled: true, top_k: 12, decider: true}

A router that names a decider uses it to pick the sub-agent — one Choice over the sub_agents, with the router's system prompt as the instructions — and classifies with its model only when the decider is unsure or unavailable. model.confidence_escalation.decider: true asks the decider whether a reply actually answers the request, instead of escalating on reply length and phrases like "unclear"; a probability below min_confidence escalates. It applies to react and deep, whose loop builds the model the decider reaches; side requests such as compaction summaries keep the heuristic.

Judges ask the decider too. A guardrails.judges rule with decider: true — on tool output or on the final reply — is scored by the decider's probability that the text meets its criteria, read as written, so a negative criterion like "must not leak credentials" needs no assert_absent: prefix; reflect.decider: true verifies drafts the same way, and an eval rubric names a decider with judge_decider: <route>. Each falls back to its model judge, then its heuristic.

skill_suggestion: {enabled: true} suggests the skill a request needs: the decider ranks the catalog, reranks a shortlist of three against each skill's body, and — when the request asks for a task and a skill fits — adds a one-line hint naming it. The model still decides whether to activate_skill. The hint is a transient message: sent last on the turn's first model call, after the prompt-cache breakpoint, and never written to the session, so it costs the cached conversation nothing. It pays off on large catalogs; with a handful of skills the model chooses well on its own.

content_screening.decider: true adds the decider to injection screening: one call asks whether the text tries to override the assistant's instructions, jailbreak it, or exfiltrate data. It runs beside the markers and content_screening.model rather than instead of them — either flagging flags, either unavailable leaves the text unscreened — because a small classifier is not adversarially robust. See deploy/GOVERNANCE.md.

With tools_retrieval.decider, one Choice over the tool catalogue per user turn picks the shortlist the model sees, in place of embedding similarity. When the decider errors, or the shortlist holds less than min_confidence of the probability mass, selection falls back to embeddings or keywords as before. An id missing from FELIX_DECISION_ROUTES, or a typesafe route with no key, fails the compile.

What leaves the deployment: the latest user message (up to 4,000 characters) and the one before it (1,000), plus each tool's name and the first 200 characters of its description, go to the decider's provider — TypeSafe or Cloudflare — unmasked; with confidence_escalation.decider, so does the model's reply (up to 4,000 characters), which may quote tool output. Treat enabling a decider as adding that provider as a processor of user input. A tool description can also steer the ranking (an MCP server describing its tool as "always choose me"); that biases which tools are offered, and every offered tool is still governance-wrapped.

Where manifests come from

FELIX_MANIFEST_SOURCE picks the posture:

Value Resolution order Writes
store (default) tenant Postgres version → bundled YAML PUT /manifests, canary, rollback
bundled bundled YAML only routes not mounted

"Bundled YAML" is manifests/*.yaml plus, when it is set, the directory FELIX_MANIFESTS_DIR names, searched after it. contributor and triage, the agents that build Felix itself, live in manifests/self/ and are not bundled: they need the builder stack's workspace and shell runner, and deploy/docker/compose.self.yml is what points FELIX_MANIFESTS_DIR at them, and FELIX_SKILLS_DIR at their skills in manifests/self/skills/. Running them anywhere else needs both.

A plugin may ship agents of its own (registry.register_manifest_dir), served after both and only where it is installed, so an install without it never lists an agent whose tools it lacks. A name held in two places -- manifests/, FELIX_MANIFESTS_DIR, a plugin's -- is refused rather than picked. The connectors plugin ships four this way, each an example of one primitive:

Agent Shows Needs
concierge Tools acting as the person (Google, iCloud), memory, a self-scheduled briefing, notify the google and/or icloud extras, a connection per person, Web Push
travel plan_execute: a plan, then its steps nothing keyed (maps, weather, FX); search if FELIX_SEARCH_BACKEND is set
markets A reply judge holding every answer to "no personalised investment advice" FELIX_MARKET_API_KEY
inbox A person in the loop: ask_user, and a draft that waits for approval the google extra, a connection

Beside them in manifests/, on core tools only: researcher (reflect, network.allow_hosts, delegation to summarizer) and automator (an agent that builds and runs workflows, spec.workflow_authoring).

An activation, a rollback or a canary change takes effect at once on the process that made it. Each API replica and worker caches a manifest's active version for 30 seconds, so the others follow within that window — a rollback is not instant fleet-wide, and a canary split briefly differs between replicas. The same window covers a name that has no stored version: a bundled manifest's "not in the store" is cached too, so a first publish over a bundled name reaches the other replicas within 30 seconds.

bundled is for a single-tenant or self-hosted deployment with no use for runtime authoring. The write routes are never registered, so the verbs are absent from the app and from /openapi.json rather than present and refusing, and no manifest store is constructed at all. felix doctor reports which posture is active — and, outside development, whether a claim-mode JWT verifier pins FELIX_ALLOWED_TENANTS, whether the OTLP exporter is private or TLS, whether prompts are kept out of spans, and whether the database schema is at the code's Alembic head.

Two things to know before flipping an existing deployment:

  • Stored manifests stop being served. Every tenant collapses onto the image's file, so any per-tenant spec.auth.inbound tightening — required_scopes in particular — is dropped. Five of the fourteen bundled manifests are allow_anonymous: true.
  • pin_compile threads will 409 once. The resolved version becomes null and the content hash becomes the bundled YAML's, which is drift by design.

Manifest capabilities

Sessions and skills:

  • Skills live under skills/ as Agent Skills SKILL.md files; declare them with spec.skills (which adds to the bundled and FELIX_SKILLS_DIR catalogue; set spec.skills_declared_only: true to make the declared names the whole set). spec.personal_skills: read also offers each authenticated caller the live skills in their own library, ahead of the tenant's, so one of theirs shadows a tenant skill of its name for them alone — never a skill the manifest names in spec.skills. It is off by default and refused with skills_declared_only; a durable run keeps the library of the caller who started it; an anonymous caller (and auth_mode=none) has none. A caller reads their own library at /skill-library/~me and, with skills:personal, writes it (within FELIX_SKILL_PERSONAL_MAX_BYTES, 50 MiB by default; see deploy/GOVERNANCE.md), and an administrator can list, read and archive anyone's. spec.personal_skills: write (which needs spec.skill_authoring.enabled) points the agent's authoring there too: create_skill saves into the caller's library and update_skill edits a skill in the library it came from, for a caller holding skills:personal; a caller without a library or the scope is refused, never redirected to the tenant's. An approval of such a save binds the library it goes into, and in publish mode a personal skill that would replace a tenant skill waits for its owner to publish it. Bundled, in every install's catalogue: calculator-help. The developer set the self-build contributor and triage manifests use — felix-architecture, felix-conventions, felix-testing, felix-contributing, felix-self — lives in manifests/self/skills/ and is served only by that stack (FELIX_SKILLS_DIR in compose.self.yml).
  • Session strategies: compacting (token-threshold), windowed:N, summarizing:N (compacting that keeps at least N turns), semantic:N, full_replay — compacting sizes itself to the model's context window unless spec.session.context_window_tokens says otherwise, and compacts once more if the provider rejects a request for length anyway. When the kept window starts mid-turn, that turn's opening user message is kept verbatim (up to 16,000 characters) and its earlier steps get a separate, smaller summary, so the request a long turn is working on is never reduced to a paraphrase
  • Clearing stale tool results: spec.session.clear_tool_results: {keep_turns: 10, min_chars: 1000} (off by default) stubs, in what the model is sent, each older tool result over min_chars or carrying an image. The newest keep_turns to 2 × keep_turns − 1 user messages stay whole: the cut-off moves keep_turns at a time, so the cached prefix changes once a step, not every call. The log keeps every result, a spilled one's stub names its artifact id, and what a caller sent is never rewritten.

A tool declares whether it may be re-run after a crash. A run that dies mid-tool leaves a call with no result, and the harness cannot tell from the outside whether the effect happened, so the call is closed out with an [error/interrupted] result before the thread resumes — without which the provider rejects the whole transcript for an unanswered tool call. replay_safe=True tells the model the call is safe to repeat; the default is that it is not, because re-running a search costs latency while re-running a payment charges twice.

Outbound integrations, all declared on the manifest:

Field Binds to
spec.mcp_servers HTTP or stdio MCP client → server__tool tools; auth: person:<provider> (person:github, person:google) calls a remote one with the token of the person the run acts for. A server that cannot be reached is named to the model and on a job's run; required: true stops the run instead (a job's run errors, a request answers 503), as does a required server binding no tools; within 60s of a successful discovery the cached tool list still compiles, and an outage then shows as tool errors
spec.peers A2A peers → peer__name tools
spec.browser_tools Playwright (via the browser extra)
spec.image_tools Pillow resize, crop, rotate, convert, thumbnail, info and list (via the image extra)
spec.sandboxes / spec.containers Isolated execution
spec.shell_tools Allowlisted argv on the API host, in the workspace checkout — no shell interpreter; background: true adds run_in_background, shell_output and shell_kill
spec.skill_scripts run_skill_script: a script from an active skill's scripts/, under an interpreter both the manifest and FELIX_SKILL_SCRIPT_INTERPRETERS allow, where a shell tool would run
spec.queues Redis list enqueue and dequeue

Warning

stdio MCP is disabled unless FELIX_MCP_STDIO_ALLOWED_COMMANDS names the exact commands allowed (a bare name runs the binary the API's own PATH finds, and a manifest may not set the child's PATH; allowlisting an interpreter or package runner such as uvx/npx lets a manifest run anything through its arguments), and shell tools are disabled unless FELIX_SHELL_ALLOWED_COMMANDS names the argv prefixes allowed, and skill scripts are disabled unless FELIX_SKILL_SCRIPT_INTERPRETERS names the interpreters allowed (and run only host skills' scripts unless FELIX_SKILL_SCRIPT_SOURCES widens it). Manifest-supplied argv is arbitrary code execution. A shell tool's command runs as the API's user and can read the API's environment unless FELIX_SHELL_RUNNER_URL points it at a felix-shell-runner (with FELIX_SHELL_RUNNER_TOKEN), which the builder stack runs in a container holding no secrets — see deploy/GOVERNANCE.md.

Structured output — spec.output_schema is a JSON Schema the agent's answer must match, and the model provider is what enforces it rather than the prompt:

spec:
  output_schema:
    type: object
    properties:
      answer: {type: string}
      confidence: {type: number}
    required: [answer, confidence]
    additionalProperties: false

message.content is then a JSON document on every provider. Tools still work — it is the turn that answers in text that is constrained, not the turns that call a tool on the way there. OpenAI gets response_format, strict when the schema closes every object and requires every property (the only setting under which the shape is guaranteed; the drop to non-strict is logged, and strict goes only to endpoints whose provider row declares it, since it is an OpenAI extension that eleven other providers share this wire without). Anthropic gets native structured outputs (output_config.format) on the models that have them — Fable, Mythos and Opus 5.x, Sonnet 5.x, Opus 4.8, Haiku 4.5 — which hold with extended thinking on, provided the schema is inside their subset: every object closed with additionalProperties: false, and no numeric, string-length, pattern or array-size constraints. Otherwise the schema becomes a tool the model must call, folded back into the reply. Where that cannot be forced — extended thinking on, or Fable 5.1, Mythos 5.1, Opus 5.5 and Sonnet 5.5, which refuse a forced tool choice — the schema is only offered, and the log names why.

Supported on pattern: react and pattern: deep. The composite patterns — router, parallel, groupchat, reflect, plan_execute — compose their answer in a turn that takes no options yet, so a manifest declaring output_schema on one of those is refused at compile rather than quietly answering in prose. A pattern registered by a plugin opts in with register_pattern(..., honours_output_schema=True).

A caller can ask for a shape per request too: POST /v1/chat/completions accepts OpenAI's response_format: {type: json_schema, json_schema: {schema: …}}, so an OpenAI SDK works unchanged. A manifest that declares spec.output_schema overrides it — an agent published with an answer contract keeps answering to it.

Images, on /chat and on /v1/chat/completions, in OpenAI's content-parts shape:

{"role": "user", "content": [
  {"type": "text", "text": "what is in this picture?"},
  {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo="}}
]}

A data: URL is sent to the provider as inline bytes — OpenAI takes the URL verbatim, Anthropic gets a base64 source, since it has no URL form for inline data — and an https:// URL is passed through as a URL for the provider to fetch. A request is bounded by the 1 MiB body limit; there is no upload endpoint yet, so an image arrives with the message that uses it.

Storage and execution:

  • Large tool outputs spill via spec.artifacts: the model gets a preview and pages through the rest with read_artifact, sized by default_window_chars / max_window_chars
  • Durable facts via spec.memory.capture; how-tos via spec.procedural_memory
  • spec.execution.mode: durable enqueues a fiber and returns 202 with a resume_token; a step that keeps failing backs off and is dead after FELIX_FIBER_MAX_ATTEMPTS, as is one that has lost its worker mid-step that many times in a row. Each worker polls for due fibers every FELIX_FIBER_POLL_SECONDS (1.0; 0 leaves only the once-a-minute fiber_scheduler sweep) and advances up to FELIX_FIBER_CONCURRENCY (8) at once, the poll and the sweep together, so a new run starts within about a second and one parked on an approval holds up no other
  • spec.network.credentials: [github] lets http_fetch call an authenticated API without the model ever holding the key: the operator registers it in FELIX_EGRESS_CREDENTIALS (a JSON map of id → {host, path_prefix?, port?, header?, scheme?, secret, tenants}), and the egress transport adds the header to https requests for that exact host and path prefix, each redirect hop judged again; the value is resolved and registered for masking when the agent compiles. The manifest must list the host in network.allow_hosts; an id not registered for the tenant fails the compile. See deploy/GOVERNANCE.md.
  • spec.execution.webhooks: [ops] announces a durable run's end to operator-registered endpoints (FELIX_WEBHOOK_ENDPOINTS, a JSON map of id → {url, secret, tenants, private?, hooks?}): the worker POSTs run.completed|failed|expired|dead with the run view, signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature: v1,…), retries with backoff up to FELIX_WEBHOOK_MAX_ATTEMPTS (8) with each attempt bounded by FELIX_WEBHOOK_TIMEOUT_SECONDS (10, at most 60), and reports each endpoint's state on GET /chat/runs/{token}. A manifest names ids, never URLs; an id not registered for the caller's tenant is 422
  • spec.destinations: {ids: [ops-brief]} binds post, which publishes to shared places the operator registered in FELIX_DESTINATIONS (a JSON map of id → {kind, tenants, links?, link_hosts?, …}; core's webhook kind names a FELIX_WEBHOOK_ENDPOINTS endpoint, the felix-channels plugin adds slack ({channel, conversation}, through a FELIX_CHANNELS app), and a plugin may register more kinds with register_destination_kind) — a team channel for a scheduled brief, say. Only unattended runs (jobs, heartbeats, triggers) post; a conversation's call is refused unless attended: approval holds it for the person. Each post names an edition (brief:2026-10-29), and the ledger (destination_posts) posts one manifest's edition to a destination at most once: a retry or the next firing gets already_posted, and a delivery whose outcome is unknown (a timeout, a 5xx) is maybe_posted and never retried. Secrets are redacted, links stripped unless the registration keeps them (links: keep, or link_hosts), and the text screened. max_per_run (3) bounds a run; approval: true holds each post for a person. An id not registered for the tenant, or a manifest admitting anonymous callers, fails the compile. See deploy/GOVERNANCE.md.
  • spec.state: {max_keys: 50, max_value_bytes: 4096} binds state_get, state_set, state_list and state_delete: a few short text values a scheduled job's runs keep for the next one — a bookmark per source, a ledger of what was already done — read back by key, never recalled by rank. The state is the job's (tenant and job name), so two jobs on one manifest keep their own; any run that is not a job's or heartbeat's firing (a chat, a workflow step, a task child) is refused, and spec.state beside execution.mode: durable does not load. Keys match [a-z0-9][a-z0-9._:-]{0,63}; a new key past max_keys is refused, an overwrite is not. state_set with expected is a compare-and-set ("" for "must not exist yet"), so two overlapping firings cannot silently overwrite each other. A value comes back fenced as data and screened as an untrusted tool's result. The job's writer or an operator reads it over GET /jobs/{name}/state and clears it with DELETE /jobs/{name}/state[/{key}] (audited job.state); deleting the job, or a re-save by another writer, deletes it. See deploy/GOVERNANCE.md.
  • Job health watch: every 5 minutes the worker flags a job that is overdue (enabled, scheduled, due longer than FELIX_JOB_OVERDUE_GRACE_SECONDS (900) ago, even if marked running: a firing moves the due time on) or failing (its last FELIX_JOB_FAILURE_THRESHOLD (3) runs all errors, skipped ones ignored). Each incident is recorded on the job (health on GET /jobs/{name}), counted (felix_job_health_incident{kind}), audited (job.health) and, when FELIX_JOB_ALERT_DESTINATION names a FELIX_DESTINATIONS id — best an "operator": true one, which no manifest may name — posted there once: fixed text naming the error's class, never its text. It clears when the job next succeeds or is disabled. GET /health/scheduler answers 503 once the scheduler's last sweep is older than FELIX_SCHEDULER_STALE_SECONDS (300), none was recorded, or Redis cannot be read: point an uptime monitor at it, not a probe. See deploy/GOVERNANCE.md.
  • POST /triggers/{id} starts a durable run from a signed event: a pushed commit, a failed payment, an alert. The operator registers each trigger in FELIX_TRIGGERS (a JSON map of id → {tenant, manifest, scheme, secret, prompt, events?, scopes?, rate_limit?}, or workflow, inputs and revision in place of manifest and prompt); scheme is standard (Standard Webhooks) or github (X-Hub-Signature-256). The signature is verified before the body is read, a replay gets the first delivery's answer, and each trigger has its own per-minute limit counted only for deliveries that would start a run. Secrets are secret:NAME outside a development install. The run's instruction is the operator's prompt; the sender's payload reaches the model only through the trigger_event tool the manifest lists, as untrusted output, after a marker scan at intake. A trigger may instead name a workflow and map payload fields to its inputs by JSON Pointer (inputs); it must pin the workflow revision it runs, so a later save, a person's or an agent's, starts nothing until the operator pins again. Each input is checked against the input's declared type before the rate limit is spent; the sender's strings, objects and arrays are recorded as untrusted, and every agent step of a triggered run reads what it is given inside a fence of its own. See deploy/GOVERNANCE.md.
  • Talk to an agent from Slack with the optional felix-channels plugin (uv sync --extra channels). The operator binds a Slack app to one tenant and manifest in FELIX_CHANNELS; a mention or a DM starts a durable run as slack:<team>:<user>, a Slack thread is one Felix thread, and the worker posts the answer back when the run ends (the register_run_finished plugin hook). Requests are verified with the app's signing secret; retries are claimed once. See deploy/GOVERNANCE.md.
  • Time tools in every install: time_now (the time in any IANA zone), time_convert (a date-time from one zone to others, saying when daylight saving skips or repeats it) and date_math (add months, weeks, days or hours, or count days, the calendar difference and weekdays between two dates). Local and read-only; a zone left out is FELIX_TIMEZONE.
  • Weather tools from the optional felix-connectors plugin (uv sync --extra connectors): connectors__weather_current, connectors__weather_forecast (up to 16 days) and connectors__weather_alerts (US, National Weather Service), keyless by default (Open-Meteo, FELIX_WEATHER_BACKEND). A manifest lists each one in spec.tools; their answers are screened as untrusted, and an agent's network.allow_hosts must cover the hosts they declare.
  • Maps tools from the same plugin: connectors__geocode, connectors__reverse_geocode, connectors__places_search, connectors__route (driving, walking, cycling) and connectors__timezone_at, keyless by default (OpenStreetMap Nominatim and FOSSGIS OSRM, paced to one request a second; FELIX_MAPS_GEOCODER, FELIX_MAPS_ROUTER).
  • Market tools from the same plugin: connectors__quote, connectors__quote_history and connectors__symbol_search (Finnhub or Alpha Vantage, FELIX_MARKET_BACKEND, keyed by FELIX_MARKET_API_KEY), and keyless connectors__fx_rate (ECB reference rates via Frankfurter, FELIX_FX_BACKEND). Every price carries its source and the time it is from.
  • Wikipedia tools from the same plugin, keyless: connectors__wikipedia_search and connectors__wikipedia_article (an article's lead, its URL to cite and when it last changed, following a redirected title), in any language edition (*.wikipedia.org).
  • A person's own Google, from the same plugin (uv sync --extra google-connectors): Calendar (connectors__calendar_list_events, _find_free_time, _create_event), Gmail (connectors__gmail_search, _read, _draft -- never sent) and Drive (connectors__drive_search, _read), each acting as the person the run acts for with the Google account they connected (/connections/google/start). Requests are built by Google's own client and sent through Felix's egress guard.
  • A person's own iCloud, from the same plugin (uv sync --extra icloud-connectors): Calendar (connectors__icloud_calendar_events, connectors__icloud_calendar_create_event) and Contacts (connectors__icloud_contacts_search), over CalDAV and CardDAV through Felix's egress guard (*.icloud.com), with the Apple ID and app-specific password the person connected (POST /connections/icloud).
  • A person's published calendar feeds, from the same plugin (uv sync --extra ics-connectors): connectors__ics_events reads the .ics links a person connected (POST /connections/ics {label, url}: Outlook's published calendar, Google Calendar's secret iCal address, an iCloud public calendar), each fetched once and kept only if it serves a calendar, sealed in their vault. The hosts a link may name are FELIX_ICS_HOSTS (Outlook, Google Calendar and *.icloud.com by default); the link is never shown to the model.
  • Web Push wakes a subscribed browser — an installed phone app, a backgrounded tab — when a new approval or an agent's question is waiting on a person (/push/*, approvals:read). Off until FELIX_PUSH_VAPID_PRIVATE_KEY and FELIX_PUSH_VAPID_SUBJECT are set; endpoints are limited to FELIX_PUSH_ALLOWED_HOSTS, and a push carries the kind of wait and the thread, never the call
  • A heartbeat is a periodic check-in a person turns on for themselves: the operator writes spec.heartbeat (what to check, a recurring schedule and the timezone a cron one is read in, a model route and max_turns for firings, keep_threads, an optional max_firings_per_day — past it a UTC day's firings, manual ones included, are recorded skipped with no model call; it needs spec.notify), and a person holding heartbeats:write turns theirs on or off with PUT /heartbeats/{manifest} ({enabled} and nothing else), removes it with DELETE, or fires it now with POST /heartbeats/{manifest}/run; GET /heartbeats (heartbeats:read) lists their own, with expires_at when the credential that enrolled it is one no firing can re-check. Each firing runs as that person, unattended, from the manifest's current checklist, and either answers HEARTBEAT_OK quietly or calls notify once — a push to them and an entry in their heartbeat conversation. See deploy/GOVERNANCE.md.
  • POST /chat/stream on a durable manifest streams the run instead: run_accepted → run_status → final, interleaved with session_event frames tailed from the thread's session log, so tool calls and assistant turns arrive as they land, across replicas, with a resumable id: cursor. Completed messages only — token deltas are never persisted, so a durable run never streams them
  • Tool retrieval, semantic sessions, and procedural recall use embeddings when felix-harness[embeddings] is installed

Documentation

User-facing documentation is published at docs.felix.run and authored in the separate felix-run/web repo.

Repository documentation for contributors lives in docs/:

Document Purpose
docs/ROADMAP.md What to build next; status updated in place
docs/RELEASING.md Version bump, changelog, tag, and what CI does
docs/TROUBLESHOOTING.md Recurring failure modes and the actual fix
docs/BACKUP.md What holds state, how to back it up, and the restore drill

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities through SECURITY.md.

License

Apache License 2.0 — see LICENSE and NOTICE. Contributions are accepted under the same license (Apache-2.0 §5).

About

Self-hostable managed agents harness. Author YAML manifests; Felix compiles them into governed agents with durable fibers, memory, skills, eval, approvals, and sandboxes — over OpenAI, A2A, MCP, and SSE. Fork, rewind, and steer runs. Docker, Helm, AWS, or GCP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages