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

> Deploy the formae agent to a Kubernetes cluster with the formae Helm chart.

The [one-command bootstrap installer](/documentation/guides/install-agent)
currently targets AWS. To run the agent in Kubernetes, deploy it with the formae
Helm chart. This is the interim manual path until Helm lands in the bootstrap
installer.

## Prerequisites

* A Kubernetes cluster.
* Helm 3.x.
* `kubectl` configured for your cluster.
* The formae CLI on your local machine (see the
  [Quick start](/documentation/get-started/quickstart)).

## Install from source

The formae Helm chart is installed from its source repository:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
git clone https://github.com/platform-engineering-labs/formae-helm.git
cd formae-helm
```

Standalone (SQLite, good for evaluation):

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
helm install formae . -f examples/formae-only.yaml
```

With PostgreSQL:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
helm install formae . -f examples/formae-db.yaml \
  --set postgresql.auth.password=<your-password>
```

Full monitoring stack (requires Prometheus and Grafana):

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
helm install formae . -f examples/formae-db-grafana.yaml \
  --set postgresql.auth.password=<your-password>
```

## Example values files

| File                              | Description                          |
| --------------------------------- | ------------------------------------ |
| `formae-only.yaml`                | SQLite, ephemeral storage            |
| `formae-only-persistent.yaml`     | SQLite with PVC                      |
| `formae-db.yaml`                  | In-cluster PostgreSQL                |
| `formae-db-grafana.yaml`          | PostgreSQL + Grafana + OTel          |
| `formae-external-db.yaml`         | External PostgreSQL                  |
| `formae-external-db-grafana.yaml` | External PostgreSQL + Grafana + OTel |
| `formae-aurora.yaml`              | Aurora Data API                      |

See the
[chart README](https://github.com/platform-engineering-labs/formae-helm) for all
configuration parameters.

## 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 cluster.

For quick access, port-forward the agent service. The agent then answers on
`http://localhost:49684`, which is exactly where the `default`
[profile](/documentation/guides/manage-profiles) already points, so no profile
setup is needed:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
kubectl port-forward svc/formae 49684:49684
```

With the port forward running, check connectivity and apply from your machine:

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

For persistent access without port-forwarding, expose the agent with an ingress
or a `LoadBalancer` service, then add a
[profile](/documentation/guides/manage-profiles) whose `cli.api.url` is that
endpoint, on port `49684`:

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

Then target it per command:

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

## Adding plugins beyond the defaults

To add plugins the base image does not ship, build a derived image, push it to a
registry the cluster can pull from, and override the chart's image on
`helm install`:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
helm install formae . -f examples/formae-only.yaml \
  --set image.repository=<your-registry>/formae-extended \
  --set image.tag=<your-tag>
```

## Next steps

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