Skip to main content
Formation is a Go service with a bundled web dashboard and PostgreSQL storage. Start the service first, then create agents through the dashboard. A new database starts with no agents.

​
Before you start

You need:
  • A PostgreSQL database reachable by the service, with permission to apply the repository’s migrations.
  • A stable public HTTPS URL for the dashboard and connector webhooks, with TLS handled by your hosting platform or reverse proxy.
  • A securely stored MESH_AGENT_MASTER_KEY before saving credentials. Preserve the same value across restarts and restores, outside the database.
  • Access to the public Formation container image, or access to the source repository to build it yourself.
The release image is ghcr.io/texturehq/formation:latest. For repeatable deployments, pin an image digest or a commit tag produced by the repository’s image workflow. The current workflow builds Linux AMD64 images.

​
Start the service

Supply your database URL and master key through your hosting platform’s secret settings or shell environment. The following assumes DATABASE_URL and MESH_AGENT_MASTER_KEY are already set:
Replace https://mesh.example.com with your installation’s actual URL and route it to the container. Formation listens on HTTP_ADDR; it does not read a platform’s PORT variable. Migrations run at startup by default. Agent state and encrypted credentials live in PostgreSQL, so preserve the database when replacing a container. Check GET /health for process liveness, then open the dashboard. Liveness does not verify that every connector, model provider, or execution backend is working.

​
Essential configuration

Agent names, model selections, and connector credentials are configured in the dashboard, not as per-agent environment variables. The process-level OPENROUTER_API_KEY is a legacy fallback, not the normal setup path: it is used only with local authentication, only for agents inheriting instance defaults, and only until instance model defaults are saved in the dashboard. For advanced deployment options, consult the repository’s environment example (repository) and configuration loader (repository).

​
Create your first agent

Open the public URL and follow Get started. With the default local authentication mode, the first setup creates the administrator account. If your deployment uses external authentication, follow that configuration’s sign-in flow instead. Set up and verify one connector before enabling additional tools or background work. A basic conversational agent does not require a remote execution backend. Code execution and browser tools have their own provider requirements; see Tools and capabilities.

​
Operate and upgrade

Owners can inspect the build, database state, and key fingerprint in Settings → About this install. The build commit can be absent when the binary was built without version metadata. Before upgrading, back up PostgreSQL and keep the master key available separately. Review durable intake and turn checkpoints for worker drain and recovery constraints. Older binaries may not understand newer database migrations or checkpoints; see upgrade and rollback guidance. Use Secrets and recovery for backups and key rotation, Telemetry for trace/log export, and Error tracking for failure reporting.