> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Run the Formation service and prepare a new installation for agent setup.

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:

```sh theme={null}
docker run --rm -p 8080:8080 \
  -e DATABASE_URL \
  -e MESH_AGENT_MASTER_KEY \
  -e PUBLIC_URL=https://mesh.example.com \
  -e HTTP_ADDR=:8080 \
  -e MESH_ENV=production \
  ghcr.io/texturehq/formation:latest
```

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

| Variable | Requirement or default |
| - | - |
| `DATABASE_URL` | Required PostgreSQL connection string. |
| `PUBLIC_URL` | Required externally reachable base URL. Used for connector callbacks. |
| `HTTP_ADDR` | Defaults to `:8080`. |
| `MESH_ENV` | Defaults to `development`; set it for your deployment. |
| `MESH_AGENT_MASTER_KEY` | Required to store and decrypt credentials. An empty database can boot without it. |
| `MESH_AUTO_MIGRATE` | Defaults to `true`. Disabling it requires a separate migration process. |
| `MESH_TRUSTED_PROXIES` | Optional comma-separated proxy IPs or CIDRs. Configure these behind a proxy so rate limits use the actual client address. |
| `MESH_CLOUDFLARE_API_TOKEN` | Optional managed web vendor account. With `MESH_CLOUDFLARE_ACCOUNT_ID`, makes web search, page reading and the browser available to every agent at boot; an install owner's own Cloudflare account takes precedence when connected. See [Web capabilities](/runtime/web-capabilities.md). |
| `MESH_CLOUDFLARE_ACCOUNT_ID` | The 32-character account ID the managed token belongs to. Required when the token is set; ignored alone. |

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)](https://github.com/TextureHQ/formation/blob/main/.env.example)
and [configuration loader (repository)](https://github.com/TextureHQ/formation/blob/main/internal/config/config.go).

## Create your first agent

Open the public URL and follow [Get started](/quickstart.md). With the default local
authentication mode, the first setup creates the administrator account. If your
deployment uses [external authentication](/external-authentication.md), 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](/runtime/tools.md).

## 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](/runtime/durable-intake.md) and
[turn checkpoints](/runtime/turn-checkpoints.md) for worker drain and recovery
constraints. Older binaries may not understand newer database migrations or
checkpoints; see [upgrade and rollback guidance](/hosted-rollback.md).

Use [Secrets and recovery](/secrets-and-recovery.md) for backups and key rotation,
[Telemetry](/telemetry.md) for trace/log export, and
[Error tracking](/error-tracking.md) for failure reporting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.