facio

After install — manage from ./facio/:

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.

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.

Use cases that fit facio

The operating model

1. Observe - facio keeps session state, memory layers, history, and runtime context instead of pretending every message is brand new.
2. Ask - facio uses explicit HITL tools when risk, ambiguity, or authority boundaries are unclear.
3. Act - inside allowed boundaries it can still move quickly, call tools, switch models, use MCP servers, and continue multi-step work.
4. Record - audit logs, runtime logs, usage data, session state, and known-bug memory keep the work inspectable.
5. Resume - 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.

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.

Why Placet is the default frontend

Facio is intentionally biased toward 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.

Other ways to run

Container-first (single agent, no Placet)

docker run --rm -it \
  -v ~/.facio:/home/facio/.facio \
  ghcr.io/placet-io/facio:latest onboard

Then start the runtime:

docker run -d --name facio \
  -v ~/.facio:/home/facio/.facio \
  -p 18790:18790 \
  ghcr.io/placet-io/facio:latest gateway

Source install

git clone https://github.com/placet-io/facio.git
cd facio
uv sync --all-extras
facio onboard
facio agent

Choose