facio

<p align="center"> <img src="logo/facio-readme-hero.svg" alt="facio" width="100%" /> </p> <p align="center"> <strong>A long-running, human-in-the-loop runtime for reliable AI work.</strong><br/> Built to collaborate with the operator, not to erase the operator. </p> <p align="center"> <em>self-improving · auditable · resumable · approval-gated · multimodal</em> </p> <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Quickstart > **Prerequisites:** Docker 24+ with Compose v2. ```bash curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | bash ``` That's it. The script detects your OS, verifies Docker, fetches the public compose file into `./facio/`, asks for the initial Placet admin email and password, generates any missing secrets, pulls `ghcr.io/placet-io/{placet,facio}:latest`, and runs `docker compose up -d` for you. Facio starts with one agent by default. If you leave the password blank, setup generates one and prints it at the end together with the Placet URL where the Facio agent is available. Default URL: http://localhost:8080. **Variants:** ```bash # Accept all defaults, no prompts curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | bash -s -- --yes # Set the initial Placet admin account from the command line curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | \ bash -s -- --admin-email admin@example.com --admin-password 'change-this-password' # Connect to an existing Placet instance (asks for URL + API key) curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | bash -s -- --external # Connect to an existing Placet instance without prompts curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | \ bash -s -- --external --yes --placet-url https://placet.example.com --placet-api-key hp_your_key # Custom target directory under your home directory curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | FACIO_DIR="$HOME/facio-demo" bash # Debug a setup run with shell tracing curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | FACIO_DEBUG=1 bash -s -- --yes ``` **After install** — manage from `./facio/`: ```bash cd facio ./facio status # show services ./facio logs facio-1 # tail logs ./facio update # pull images and recreate (Facio + Placet) ./facio scale 3 # run three Facio agents ./facio down # stop ``` The first agent is named `Facio Agent`. When you scale, agents use stable internal hostnames (`facio-1`, `facio-2`, ...) and human-readable Placet names like `Facio Agent (#1)`, `Facio Agent (#2)`, ... instead of Docker-generated container IDs. Each agent gets its own data dir under `./volumes/facio/<hostname>/` and auto-registers with Placet over the docker network. **Custom overrides (Traefik, external networks, port bindings, hardening, …):** setup drops a `docker-compose.override.yml.template` next to the compose files as a menu of opt-in snippets (Traefik, external mode port binding, dropping SYS_ADMIN on rootless hosts, …). Copy it to `docker-compose.override.yml`, keep only the sections you need, and run `./facio up`. Docker auto-loads `docker-compose.override.yml` on top of the main `docker-compose.yml`, so the main file stays untouched. In external mode setup bootstraps a minimal `docker-compose.override.yml` for you (just the host port binding) when none exists yet — feel free to edit it. <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Why facio exists Most agent products still optimize for the wrong moment: a short demo where the model looks autonomous for five minutes and nobody asks what happens after the first risky action, partial failure, or half-finished handoff. Facio is built for the opposite situation. It stays around, keeps state, asks when it should ask, continues when the boundaries are clear, and leaves behind enough audit and runtime information that both the operator and the agent can understand what happened. That makes facio useful in the places where normal chat wrappers start to break down: approval-heavy workflows, long-running coordination, personal operator assistance, multi-step execution, and environments where reliability and recoverability matter more than spectacle. > Facio is unrelated to crypto. There is no token, no coin, and no airdrop. <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Use cases that fit facio <table> <tr> <td width="50%" valign="top"> <strong>01 / Approval-heavy operations</strong><br/> Internal tooling, release prep, customer support escalations, incident follow-up, or account workflows where the agent should move fast but still stop before crossing unclear boundaries. </td> <td width="50%" valign="top"> <strong>02 / Personal operator runtime</strong><br/> One persistent agent that keeps context across sessions, learns preferences, remembers bugs and facts separately, and can keep working for weeks instead of starting from zero every day. </td> </tr> <tr> <td width="50%" valign="top"> <strong>03 / Self-debugging assistants</strong><br/> Workflows where the runtime should be able to inspect audit trails, read its own logs, understand recent failures, and recover without the operator manually stitching context back together. </td> <td width="50%" valign="top"> <strong>04 / Secure AI collaboration</strong><br/> Setups that need secret redaction, isolated credential handling, tool policy gates, guardrails, and explicit operator control instead of a model receiving broad silent access. </td> </tr> <tr> <td width="50%" valign="top"> <strong>05 / Tool-rich knowledge work</strong><br/> Research, coding, ops, documentation, and mixed human/agent execution where runtime model switching, MCP tooling, reusable skills, and scripts should stay manageable while the agent is live. </td> <td width="50%" valign="top"> <strong>06 / File-heavy HITL workflows</strong><br/> Reviews, approvals, attachments, structured forms, and iteration chains where plain chat is too weak and the operator needs a real frontend for supervision. </td> </tr> </table> <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## The operating model 1. <strong>Observe</strong> - facio keeps session state, memory layers, history, and runtime context instead of pretending every message is brand new. 2. <strong>Ask</strong> - facio uses explicit HITL tools when risk, ambiguity, or authority boundaries are unclear. 3. <strong>Act</strong> - inside allowed boundaries it can still move quickly, call tools, switch models, use MCP servers, and continue multi-step work. 4. <strong>Record</strong> - audit logs, runtime logs, usage data, session state, and known-bug memory keep the work inspectable. 5. <strong>Resume</strong> - the runtime is designed to continue after interruptions, approvals, retries, or delayed follow-ups instead of collapsing into a dead demo state. This is the core design decision behind facio: useful autonomy inside explicit boundaries, human authority outside them. <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## What you get out of the box - Human-in-the-loop reviews with approvals, selections, text input, and structured forms. - Long-running sessions with resumable turns, iteration budgeting, cron execution, and stable runtime state. - Multi-level memory with dedicated layers for identity, user preferences, durable facts, known bugs, and append-only history. - Runtime model switching plus per-subagent routing for cost, latency, or capability changes while the agent is live. - Dynamic MCP and skill management without reducing the product to static startup config. - Built-in secret storage, secret redaction, credential isolation, and policy-gated tools. - Self-inspection through audit trails, persistent runtime logs, token-usage views, health surfaces, and `read_logs`. - Multimodal work across text, attachments, vision, image generation, and video generation. - A Placet-first workflow with secondary transports for Telegram, Discord, Slack, Email, Microsoft Teams, CLI, OpenAI-compatible chat, and A2A. <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Why Placet is the default frontend Facio is intentionally biased toward [Placet](https://github.com/placet-io/placet). That is not a branding accident. It is a workflow decision. Placet is the surface in this stack that best matches how facio is supposed to be used: - structured approvals instead of vague chat confirmations - form-based HITL instead of brittle prompt parsing - strong handling of file-heavy conversations and review loops - streaming plus operator-facing progress states - management workflows that fit a live runtime instead of a toy bot Other transports still matter and remain supported, but they are secondary when you want the full facio operating model. <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Other ways to run ### Container-first (single agent, no Placet) ```bash docker run --rm -it \ -v ~/.facio:/home/facio/.facio \ ghcr.io/placet-io/facio:latest onboard ``` Then start the runtime: ```bash docker run -d --name facio \ -v ~/.facio:/home/facio/.facio \ -p 18790:18790 \ ghcr.io/placet-io/facio:latest gateway ``` ### Source install ```bash git clone https://github.com/placet-io/facio.git cd facio uv sync --all-extras facio onboard facio agent ``` <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Choose facio when - you want the agent to stay useful after the demo moment - you need approvals, supervision, and explicit operator authority - you want memory, logs, and auditability to survive across sessions - you need runtime flexibility instead of one fixed model or one fixed tool layout - you want an agent that can improve workflows without becoming opaque ## Skip facio when - you only need a stateless chat UI over one model - you do not care about review flows, approvals, or delayed continuation - you want the simplest possible bot instead of an operator runtime <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## Integrations <table> <tr> <td width="33%" valign="top"> <strong>LLM providers</strong><br/> OpenAI · Anthropic · OpenRouter · Azure OpenAI · GitHub Copilot · OpenAI Codex · any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …) via the compat provider. </td> <td width="33%" valign="top"> <strong>Channels</strong><br/> Placet (primary) · Telegram · Discord · Slack · Email · Microsoft Teams · CLI REPL · OpenAI-compatible HTTP · A2A 1.0. </td> <td width="33%" valign="top"> <strong>Tools &amp; protocols</strong><br/> MCP servers (stdio &amp; SSE, runtime add/remove) · workspace skills · custom Python scripts · web fetch &amp; search · exec sandboxed via bwrap · image and video generation · transcription. </td> </tr> <tr> <td width="33%" valign="top"> <strong>Auth &amp; secrets</strong><br/> OAuth flows for channels and skills · HITL credential capture · per-skill credential scopes · `${credentials.KEY}` placeholders · operator-controlled exec env-var whitelist. </td> <td width="33%" valign="top"> <strong>Persistence</strong><br/> Git-tracked workspace · SQLite audit log (WAL) · token-usage rollups · file-based session history · resumable cron jobs · on-disk runtime logs with rotation. </td> <td width="33%" valign="top"> <strong>Management</strong><br/> Bearer-auth `/api/v1/*` for sessions, cron, channels, skills, MCP, audit, usage, policy, settings · agent card override at `workspace/agent-card.json` · slash commands for runtime control. </td> </tr> </table> <p align="center"><img src="logo/facio-readme-separator.svg" alt="" width="100%" /></p> ## References Detailed documentation is being reorganized. This README stays product-first on purpose. - [CHANGELOG.md](CHANGELOG.md) for feature history and release changes - [SECURITY.md](SECURITY.md) for the security model and deployment cautions - [CONTRIBUTING.md](CONTRIBUTING.md) for validation and contribution workflow - [LICENSE](LICENSE) for licensing terms ## License This project is licensed under the [GNU Affero General Public License v3.0](LICENSE). ## Attribution This project was inspired by, and reuses selected ideas and implementation approaches from, the MIT-licensed projects [Hermes](https://github.com/nousresearch/hermes-agent) and [OpenClaw (ClawHub)](https://github.com/openclaw/openclaw).