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 |
- Manifests —
felix/v1YAML; the agents inmanifests/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,
--mockCI path - Deploy — lean Docker, Helm, AWS, or GCP
- 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 setFELIX_DEFAULT_MODEL_ID=gpt-4.1..env.examplelists the rest. jqfor the examples below (optional).
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 keyPut your model key in .env: FELIX_ANTHROPIC_API_KEY, or FELIX_OPENAI_API_KEY plus
FELIX_DEFAULT_MODEL_ID=gpt-4.1.
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 keyValidate 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"}]}' | jqFrom 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.
make up # migrates, then api :8080, worker, scheduler, pgvector, Valkey (fs object store)
curl -s http://localhost:8080/health | jqThe 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.
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?"}]}' | jqOr 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"}]}' | jqquick 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.
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, groupedRun 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.
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 portsDocker 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.
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, exportersTo 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.
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=duckdbClient → 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 |
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_STOREtos3,gcs,fs,memory, or a backend you register - Set
FELIX_SECRETS_BACKENDtoenv,file,aws,gcp, or a backend you register - A manifest's
secret:NAMErefs resolve only namesFELIX_MANIFEST_SECRETSlists for the tenant (a JSON map of name →[tenant, …]or"*"; empty allows none). Felix's own secrets — anyFELIX_*name, the provider and sign-in keys,DATABASE_URL,REDIS_URL— are refused whatever it says.PUT /manifestsanswers422for 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 serverFELIX_MCP_PERSON_AUTHlists for that provider and tenant ({"github": [{"url": …, "tenants": […]}]}; empty allows none).PUT /manifestsanswers422for 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
persistencewhen usingfs, so/datasurvives restarts - Production JWT and api_key deploys need
FELIX_CONSUMER_SHARED_SECRETforPOST /internal/* - Retention: the worker's nightly sweep prunes
audit_events,usage_events, finishedfibersanda2a_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-writtentaskmemories untouched this long are forgotten, not deleted — restorable withPOST /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, sinceattachments/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/rewindwithrestore_files, bytes and ledger row, counted from each file's last change in its thread;FELIX_FILE_CHECKPOINT_MAX_BYTES_PER_TENANTcaps the content kept, 256 MiB;FELIX_FILE_CHECKPOINTS=falserecords none); a manifest'sgovernance.retention_daysshortens the audit TTL for its own rows - Memory per person: a person is
issuer|subject, so an API key'ssuband 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 untilfelix 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:writespan everyone (seedeploy/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 anadmin) must decide; seedeploy/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 defaultfsstore 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.
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.
| 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.
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.
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.
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.inboundtightening —required_scopesin particular — is dropped. Five of the fourteen bundled manifests areallow_anonymous: true. pin_compilethreads will 409 once. The resolved version becomesnulland the content hash becomes the bundled YAML's, which is drift by design.
Sessions and skills:
- Skills live under
skills/as Agent SkillsSKILL.mdfiles; declare them withspec.skills(which adds to the bundled andFELIX_SKILLS_DIRcatalogue; setspec.skills_declared_only: trueto make the declared names the whole set).spec.personal_skills: readalso 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 inspec.skills. It isoffby default and refused withskills_declared_only; a durable run keeps the library of the caller who started it; an anonymous caller (andauth_mode=none) has none. A caller reads their own library at/skill-library/~meand, withskills:personal, writes it (withinFELIX_SKILL_PERSONAL_MAX_BYTES, 50 MiB by default; seedeploy/GOVERNANCE.md), and an administrator can list, read and archive anyone's.spec.personal_skills: write(which needsspec.skill_authoring.enabled) points the agent's authoring there too:create_skillsaves into the caller's library andupdate_skilledits a skill in the library it came from, for a caller holdingskills: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-buildcontributorandtriagemanifests use —felix-architecture,felix-conventions,felix-testing,felix-contributing,felix-self— lives inmanifests/self/skills/and is served only by that stack (FELIX_SKILLS_DIRincompose.self.yml).
- Session strategies:
compacting(token-threshold),windowed:N,summarizing:N(compacting that keeps at least N turns),semantic:N,full_replay—compactingsizes itself to the model's context window unlessspec.session.context_window_tokenssays 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 overmin_charsor carrying an image. The newestkeep_turnsto2 × keep_turns − 1user messages stay whole: the cut-off moveskeep_turnsat 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: falsemessage.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 withread_artifact, sized bydefault_window_chars/max_window_chars - Durable facts via
spec.memory.capture; how-tos viaspec.procedural_memory spec.execution.mode: durableenqueues a fiber and returns202with aresume_token; a step that keeps failing backs off and isdeadafterFELIX_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 everyFELIX_FIBER_POLL_SECONDS(1.0; 0 leaves only the once-a-minutefiber_schedulersweep) and advances up toFELIX_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 otherspec.network.credentials: [github]letshttp_fetchcall an authenticated API without the model ever holding the key: the operator registers it inFELIX_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 innetwork.allow_hosts; an id not registered for the tenant fails the compile. Seedeploy/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 POSTsrun.completed|failed|expired|deadwith the run view, signed per Standard Webhooks (webhook-id,webhook-timestamp,webhook-signature: v1,…), retries with backoff up toFELIX_WEBHOOK_MAX_ATTEMPTS(8) with each attempt bounded byFELIX_WEBHOOK_TIMEOUT_SECONDS(10, at most 60), and reports each endpoint's state onGET /chat/runs/{token}. A manifest names ids, never URLs; an id not registered for the caller's tenant is422spec.destinations: {ids: [ops-brief]}bindspost, which publishes to shared places the operator registered inFELIX_DESTINATIONS(a JSON map of id →{kind, tenants, links?, link_hosts?, …}; core'swebhookkind names aFELIX_WEBHOOK_ENDPOINTSendpoint, thefelix-channelsplugin addsslack({channel, conversation}, through aFELIX_CHANNELSapp), and a plugin may register more kinds withregister_destination_kind) — a team channel for a scheduled brief, say. Only unattended runs (jobs, heartbeats, triggers) post; a conversation's call is refused unlessattended: approvalholds it for the person. Each post names anedition(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 getsalready_posted, and a delivery whose outcome is unknown (a timeout, a 5xx) ismaybe_postedand never retried. Secrets are redacted, links stripped unless the registration keeps them (links: keep, orlink_hosts), and the text screened.max_per_run(3) bounds a run;approval: trueholds each post for a person. An id not registered for the tenant, or a manifest admitting anonymous callers, fails the compile. Seedeploy/GOVERNANCE.md.spec.state: {max_keys: 50, max_value_bytes: 4096}bindsstate_get,state_set,state_listandstate_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, ataskchild) is refused, andspec.statebesideexecution.mode: durabledoes not load. Keys match[a-z0-9][a-z0-9._:-]{0,63}; a new key pastmax_keysis refused, an overwrite is not.state_setwithexpectedis 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 overGET /jobs/{name}/stateand clears it withDELETE /jobs/{name}/state[/{key}](auditedjob.state); deleting the job, or a re-save by another writer, deletes it. Seedeploy/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 lastFELIX_JOB_FAILURE_THRESHOLD(3) runs all errors, skipped ones ignored). Each incident is recorded on the job (healthonGET /jobs/{name}), counted (felix_job_health_incident{kind}), audited (job.health) and, whenFELIX_JOB_ALERT_DESTINATIONnames aFELIX_DESTINATIONSid — best an"operator": trueone, 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/scheduleranswers 503 once the scheduler's last sweep is older thanFELIX_SCHEDULER_STALE_SECONDS(300), none was recorded, or Redis cannot be read: point an uptime monitor at it, not a probe. Seedeploy/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 inFELIX_TRIGGERS(a JSON map of id →{tenant, manifest, scheme, secret, prompt, events?, scopes?, rate_limit?}, orworkflow,inputsandrevisionin place ofmanifestandprompt);schemeisstandard(Standard Webhooks) orgithub(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 aresecret:NAMEoutside a development install. The run's instruction is the operator'sprompt; the sender's payload reaches the model only through thetrigger_eventtool the manifest lists, as untrusted output, after a marker scan at intake. A trigger may instead name aworkflowand map payload fields to its inputs by JSON Pointer (inputs); it must pin the workflowrevisionit 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. Seedeploy/GOVERNANCE.md.- Talk to an agent from Slack with the optional
felix-channelsplugin (uv sync --extra channels). The operator binds a Slack app to one tenant and manifest inFELIX_CHANNELS; a mention or a DM starts a durable run asslack:<team>:<user>, a Slack thread is one Felix thread, and the worker posts the answer back when the run ends (theregister_run_finishedplugin hook). Requests are verified with the app's signing secret; retries are claimed once. Seedeploy/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) anddate_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 isFELIX_TIMEZONE. - Weather tools from the optional
felix-connectorsplugin (uv sync --extra connectors):connectors__weather_current,connectors__weather_forecast(up to 16 days) andconnectors__weather_alerts(US, National Weather Service), keyless by default (Open-Meteo,FELIX_WEATHER_BACKEND). A manifest lists each one inspec.tools; their answers are screened as untrusted, and an agent'snetwork.allow_hostsmust cover the hosts they declare. - Maps tools from the same plugin:
connectors__geocode,connectors__reverse_geocode,connectors__places_search,connectors__route(driving, walking, cycling) andconnectors__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_historyandconnectors__symbol_search(Finnhub or Alpha Vantage,FELIX_MARKET_BACKEND, keyed byFELIX_MARKET_API_KEY), and keylessconnectors__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_searchandconnectors__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_eventsreads the.icslinks 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 areFELIX_ICS_HOSTS(Outlook, Google Calendar and*.icloud.comby 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 untilFELIX_PUSH_VAPID_PRIVATE_KEYandFELIX_PUSH_VAPID_SUBJECTare set; endpoints are limited toFELIX_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 recurringscheduleand thetimezonea cron one is read in, amodelroute andmax_turnsfor firings,keep_threads, an optionalmax_firings_per_day— past it a UTC day's firings, manual ones included, are recordedskippedwith no model call; it needsspec.notify), and a person holdingheartbeats:writeturns theirs on or off withPUT /heartbeats/{manifest}({enabled}and nothing else), removes it withDELETE, or fires it now withPOST /heartbeats/{manifest}/run;GET /heartbeats(heartbeats:read) lists their own, withexpires_atwhen 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 answersHEARTBEAT_OKquietly or callsnotifyonce — a push to them and an entry in their heartbeat conversation. Seedeploy/GOVERNANCE.md. POST /chat/streamon a durable manifest streams the run instead:run_accepted→run_status→final, interleaved withsession_eventframes tailed from the thread's session log, so tool calls and assistant turns arrive as they land, across replicas, with a resumableid: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
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 |
See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities through SECURITY.md.
Apache License 2.0 — see LICENSE and NOTICE. Contributions are accepted under the same license (Apache-2.0 §5).