<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.
- Central agent versioning for memory, skills, scripts, MCP, policy, cron, channels, and other agent-owned control files, with checkpoints, history, diffs, and rollback.
- Self-improvement reviews with proposal reports, validation checks, approval gates, automatic triggers, and versioned apply/rollback.
- 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 · OpenCode Zen Go · 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 versions, and improvement runs · 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>

## Runtime control commands

Facio exposes operator commands through supported channels, including Placet, CLI, and the OpenAI-compatible chat surface. Common runtime commands include:

| Command                     | Purpose                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `/goal` and `/subgoal`      | Manage persistent multi-turn objectives and their checklist state.                           |
| `/reflect`                  | Run Reflection immediately against unprocessed history and memory context.                   |
| `/reflection-log [sha]`     | Inspect the latest Reflection change or a selected central agent version.                    |
| `/reflection-restore [sha]` | List or restore Reflection-related central agent versions.                                   |
| `/improve`                  | Run an intelligent read-only self-improvement review and create a proposal only when useful. |
| `/improve status`           | List recent self-improvement runs and their current states.                                  |
| `/improve diff [id]`        | Preview stored diff artifacts for the latest or selected self-improvement proposal.          |
| `/improve apply [id]`       | Apply the latest or selected proposal, creating central version checkpoints when available.  |
| `/improve cancel [id]`      | Cancel the latest or selected proposal.                                                      |
| `/improve rollback <id>`    | Roll back an applied self-improvement run.                                                   |

Self-improvement can also be triggered automatically after goal completion, repeated tool errors, user corrections, or on the configured schedule. Reviews use read-only tools to inspect memory, known bugs, skills, scripts, instructions, policy, runtime inventory, structured tool-usage history, logs, and pending tracked version-store changes; proposed file changes remain gated until explicitly applied.

## Versioning and self-improvement API

When the management API is enabled, Facio exposes the central versioning and self-improvement surfaces under the same bearer-authenticated `/api/v1/*` API as the rest of management:

| Endpoint                                         | Purpose                                                                                                          |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `GET /api/v1/agent/versions`                     | List central agent versions.                                                                                     |
| `POST /api/v1/agent/versions/checkpoint`         | Create a manual checkpoint when tracked agent state changed.                                                     |
| `GET /api/v1/agent/versions/{sha}`               | Inspect one central agent version.                                                                               |
| `GET /api/v1/agent/versions/{sha}/diff`          | Return a redacted diff for a version.                                                                            |
| `POST /api/v1/agent/versions/{sha}/rollback`     | Restore tracked agent-owned files to a version and rehydrate MCP, policy, and cron runtime state where possible. |
| `GET /api/v1/improvement/runs`                   | List self-improvement runs.                                                                                      |
| `POST /api/v1/improvement/runs/{runId}/approve`  | Approve and optionally apply a run.                                                                              |
| `POST /api/v1/improvement/runs/{runId}/reject`   | Reject a run.                                                                                                    |
| `POST /api/v1/improvement/runs/{runId}/rollback` | Roll back an applied run.                                                                                        |

Self-improvement settings live under `agents.defaults.self_improvement` and can also be managed through the settings API. The main controls are `enabled`, `mode`, `auto_triggers`, `interval_h`, `scopes`, `max_iterations`, optional `model_override` / `provider_override`, and `validation_level`.

GitHub backup sync is opt-in under `agents.defaults.github_backup`. If it is unset or disabled, Facio does not call GitHub and keeps using only the local GitStore. To enable remote sync, set `FACIO_GITHUB_BACKUP_ENABLED=true` plus optional `FACIO_GITHUB_BACKUP_OWNER=<owner>` and `FACIO_GITHUB_BACKUP_REPO=facio-backup`, or `FACIO_GITHUB_BACKUP_REMOTE_URL=https://github.com/<owner>/<repo>.git`. On startup, Facio checks the GitHub repo and creates it as private when it is missing (`FACIO_GITHUB_BACKUP_CREATE_REMOTE=true`, `FACIO_GITHUB_BACKUP_PRIVATE=true` by default). Push/pull authentication uses `GH_TOKEN`, `GITHUB_TOKEN`, or `FACIO_GITHUB_TOKEN` from the environment, and can also use a Placet secret named `GITHUB_TOKEN` by default. Secrets stay in the CredentialStore outside the workspace git repository.

<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).
