Getting Started

The quickest path is Docker-first. The setup script prepares a local Facio environment, starts Placet, registers the first agent, and avoids requiring a local Python install or hand-made runtime directories.

Use this page to get a working system, then read Runtime and Security before connecting sensitive tools or channels.

Docker ready

Run setup

Open Placet

First task

Prerequisites

Docker 24+ with Compose v2.
A shell that can run the setup script.
Model or provider credentials for the first real task.
Enough local ports available for the quickstart services.
A choice between bundled Placet for the fastest local start or external Placet for connecting an existing operator surface.

Installation

Use the quickstart script from the Facio repository when setting up a fresh local environment.

curl -fsSL https://raw.githubusercontent.com/placet-io/facio/main/quickstart/setup.sh | bash

The default path installs into ./facio/, starts bundled Placet, and creates the first agent as Facio Agent. If you leave the initial password blank, setup generates one and prints it with the local Placet URL when it finishes.

For unattended local evaluation, pass --yes. For an existing Placet instance, run the script with --external and provide the Placet URL plus API key. For production-like environments, treat quickstart as an evaluation path and create a reviewed deployment plan before connecting sensitive systems.

Setup mode	Use it when
Bundled Placet	You want the fastest local evaluation with dashboard and agent together.
External Placet	Your team already has a Placet instance or wants a shared operator surface.
Custom directory	You want the generated compose files and volumes somewhere other than `./facio/`.

First agent run

After startup, open Placet, choose the Facio agent, configure a provider if needed, and begin with a low-risk task such as summarizing a document, reading a repository file, or drafting a review checklist.

Keep the first task small. The goal is to verify model access, tool routing, session persistence, logs, and approval behavior before adding sensitive integrations.

Good first tasks:

Summarize a document or README.
Draft a checklist from a small set of files.
Ask the agent to explain what it can see and what it would need approval for.
Trigger a harmless tool call so you can inspect logs and audit events.

After install

The quickstart includes a small host-side helper for the local Docker Compose stack. Use it from the install directory to inspect services, view logs, update images, scale agents, and stop the environment.

Task	Command shape
Show services	`./facio status`
Tail logs	`./facio logs facio-1`
Pull images and recreate	`./facio update`
Run multiple agents	`./facio scale 3`
Stop the stack	`./facio down`

Scaling keeps stable agent names and hostnames so management callbacks remain predictable. Additional agents get their own data directories under the quickstart volumes. Treat the quickstart helper as local operations tooling, not as a replacement for a reviewed production deployment plan.

The setup also ships an override template for common deployment changes such as external port binding, reverse-proxy labels, network choices, or container hardening. Keep the main Compose file unchanged and put local changes in docker-compose.override.yml.

Security baseline

The official Docker path runs the agent as a non-root user, drops broad capabilities where the host allows it, uses a sandbox for shell execution, keeps credentials outside the workspace, redacts known secrets from logs and tool output, and relies on explicit channel allow lists for access control.

For a real rollout, review which credentials are exposed to shell commands, which channels are enabled, which data directories need backup, and which actions require Placet approval before they affect external systems.

Common setup issues

Docker is not running or cannot pull the required images.
A required port is already used by another service.
Provider credentials are missing or scoped incorrectly.
The configured model is not available for the selected provider.
Browser, tool, or channel integrations need explicit credentials before use.
External Placet cannot reach the agent management URL because host binding or reverse proxy settings are incomplete.