facio

A long-running, human-in-the-loop runtime for reliable AI work.
Built to collaborate with the operator, not to erase the operator.

self-improving · auditable · resumable · approval-gated · multimodal

Quickstart

Prerequisites: Docker 24+ with Compose v2.

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:

# 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 [email protected] --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/:

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

Integrations

References

Detailed documentation is being reorganized. This README stays product-first on purpose.

• CHANGELOG.md for feature history and release changes
• SECURITY.md for the security model and deployment cautions
• CONTRIBUTING.md for validation and contribution workflow
• LICENSE for licensing terms

License

This project is licensed under the GNU Affero General Public License v3.0.

Attribution

This project was inspired by, and reuses selected ideas and implementation approaches from, the MIT-licensed projects Hermes and OpenClaw (ClawHub).