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

# Install the agent with Docker

> Run the formae agent as a container from the published image, for local evaluation or a self-managed host.

The [one-command bootstrap installer](/documentation/guides/install-agent)
currently targets AWS. To run the agent anywhere Docker runs (your laptop or a
self-managed host), start it from the published container image. This is the
interim manual path until Docker lands in the bootstrap installer.

## Prerequisites

* The formae CLI on your local machine (see the
  [Quick start](/documentation/get-started/quickstart)).
* Docker installed and running.

The formae agent is published as a container image:

```text theme={"languages":{"custom":["/languages/pkl.json"]}}
ghcr.io/platform-engineering-labs/formae
```

Supported architectures: `linux/amd64` and `linux/arm64`.

## Run with Docker

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
docker run -d -p 49684:49684 ghcr.io/platform-engineering-labs/formae:latest
```

The agent API is available on port `49684`.

## Run a specific version

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
docker run -d -p 49684:49684 ghcr.io/platform-engineering-labs/formae:0.82.0
```

## Custom configuration

Mount a custom config file and point the agent at it with `--config`:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
docker run -d -p 49684:49684 \
  -v /path/to/formae.conf.pkl:/config/formae.conf.pkl:ro \
  ghcr.io/platform-engineering-labs/formae:latest \
  formae agent start --config /config/formae.conf.pkl
```

The config file is Pkl and amends the bundled schema. For example, to point the
agent at PostgreSQL instead of the default SQLite:

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
amends "formae:/Config.pkl"

agent {
  datastore {
    datastoreType = "postgres"
    postgres {
      host = "<postgres-host>"
      port = 5432
      user = "<user>"
      password = "<password>"
      database = "formae"
    }
  }
}
```

See the [Configuration](/documentation/reference/configuration) reference for all
available options.

## Connect your CLI

The CLI runs on your machine, evaluates Pkl locally, and sends the result to the
agent API. No forma files need to be loaded into the container.

When you run the container locally with `-p 49684:49684`, the agent is reachable
at `http://localhost:49684`, which is exactly where the `default`
[profile](/documentation/guides/manage-profiles) already points. So a local
container needs no profile setup at all:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae status agent
formae apply --mode reconcile your-forma.pkl
```

If the agent runs on a remote host, add a
[profile](/documentation/guides/manage-profiles) whose `cli.api.url` is that
host, on port `49684`:

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
cli {
  api {
    url = "http://<remote-host>"
    port = 49684
  }
}
```

Then target it per command:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae status agent --profile docker
formae apply --mode reconcile your-forma.pkl --profile docker
```

## Next steps

* [Manage profiles](/documentation/guides/manage-profiles): switch the CLI between this agent and others.
* [Configuration](/documentation/reference/configuration): agent and CLI options.