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

# Kubernetes: standard setup

> Install the quint-sidecar Helm chart so an agent pod runs beside Quint in a namespace that allows the privileged Pod Security level.

> [!NOTE]
>
> Quint on Kubernetes is early access. The Quint container images, the Helm charts and the admission webhook are not available for download. Your Quint contact gives you each of them, with the image digests for your release, so talk to your Quint contact before you plan an install.

At the end of this page your agent runs in a Kubernetes pod beside Quint, and its runs appear on the [Workloads](https://docs.quintai.dev/dashboard/workloads.md) page. You need a cluster that meets the [requirements](https://docs.quintai.dev/install/containers.md#requirements), the [Quint admission webhook](https://docs.quintai.dev/install/admission-webhook.md) running in it, `kubectl` and `helm`, and the **Admin** or **Owner** role in the Quint dashboard. Ask your Quint contact for the `quint-sidecar` chart and the image digests for your release.

## What the chart runs

The chart renders your agent container, unchanged, and three Quint containers in this order. The webhook refuses any other order.

| Container | What it does |
| - | - |
| `quint-netlock` | Sets the pod's network rules, checks them, and exits. Runs as root with `NET_ADMIN` only. |
| `quint-qhelper` | Keeps running and holds the right to cut the pod off. Runs as root with `NET_ADMIN` only. |
| `quint-sidecar` | Enrols the run, fetches the workload's signed policy, starts Quint's proxy on `127.0.0.1:9090` and checks that the agent can reach nothing else. Runs as user `10001` with no privileges. |
| your agent | Starts after `quint-sidecar` passes its startup check. Runs as `agentUID` with no privileges. |

The chart sets the agent's `HTTPS_PROXY`, `HTTP_PROXY` and `ALL_PROXY` to `http://127.0.0.1:9090`, and its CA bundle variables, such as `SSL_CERT_FILE`, to `/quint/ca/ca-certificates.crt`. If the agent unsets the proxy variables, its traffic is dropped.

**1. Set up the workload and its key**

On the [Workloads](https://docs.quintai.dev/dashboard/workloads.md) page, set up a workload and create a key. The workload's name is the value you give as `quint.workload`. Save the key to a file, `workload.key`.

**2. Create and label the namespace**

The `quintai.dev/governed=true` label sends every pod in the namespace to the admission webhook.

```bash theme={"dark"}
kubectl create namespace agents
kubectl label namespace agents pod-security.kubernetes.io/enforce=privileged quintai.dev/governed=true
```

**3. Store the workload key**

The chart takes the key from an existing Secret, never as a value. Only `quint-sidecar` mounts it; the agent never sees it.

```bash theme={"dark"}
kubectl -n agents create secret generic quint-workload-key --from-file=key=./workload.key
```

**4. Install the chart**

The `quint-sidecar` chart, the two Quint images and their digests come from your Quint contact. They are not available for download.

Pin both Quint images by digest. The webhook admits Quint images pinned by digest only, and only the digests it was started with.

```bash theme={"dark"}
helm install my-agent ./quint-sidecar -n agents \
  --set agentUID=10002 \
  --set quint.workload=ci-agent \
  --set quint.workloadKeySecret.name=quint-workload-key \
  --set images.sidecar.digest=sha256:<quint-sidecar digest> \
  --set images.qhelper.digest=sha256:<quint-qhelper digest> \
  --set agent.image.repository=registry.example/my-agent --set agent.image.tag=1.0
```

`workload.kind` is `Job` by default, one pod for one run. `Pod` and `Deployment` work too. In a values file, quote the user ID: `agentUID: "10002"`.

**5. Declare your agent's harness version**

Quint can't see inside your agent image, so tell it which agent harness and version the image ships. Quint accepts only the versions it knows. Before you set this, ask your Quint contact which harness versions your Quint release knows, and build your agent image with one of them.

```yaml theme={"dark"}
quint:
  harnessVersions:
    claude-code: "<a version Quint knows>"
```

Quote every version, and list the version the image really ships. You can list up to 16 harnesses.

* **If you set a version Quint knows,** an action that matches a rule asking for approval waits for an approver.
* **If you leave this out,** every rule that asks for approval denies the action straight away, because Quint can't tell how long the harness will wait for an answer.
* **If you list a version Quint doesn't know,** the Quint sidecar refuses to start, so the agent container never starts and the pod stays cut off.

**6. Install the status policy once per cluster**

The webhook does not judge pod status updates. A Kubernetes ValidatingAdmissionPolicy, `quint-status-annotations`, refuses status updates that add, change or remove Quint's `quintai.dev/*` annotations, or add container runtime annotations. Install it in exactly one release with `--set statusPolicy.create=true`, or apply it with the webhook's own command (`quint-admission` comes from your Quint contact):

```bash theme={"dark"}
quint-admission webhook-config --service-namespace quint-system --status-policy | kubectl apply -f -
```

Without it, a status update can change Quint's annotations on a pod without being checked.

**7. Check the run**

Open the workload on the **Workloads** page. A run appears on the first container start. Quint also records a status on the run, such as **contained** or **unverified**, which the page does not show. See [Status recorded for runs](https://docs.quintai.dev/install/containers.md#status-recorded-for-runs).

## What your agent can't do

* **Serve kubelet probes or a Service.** The agent can reach only `127.0.0.1:9090`, so `httpGet`, `tcpSocket` and `grpc` probes time out. The chart refuses them; use `exec` probes.
* **Run as root or add privileges.** The chart writes the agent's security settings itself. `agent.securityContext` accepts only `runAsGroup`, `readOnlyRootFilesystem`, `seLinuxOptions` and `appArmorProfile`.
* **Use a pod `fsGroup` or, in this setup, pod-level `supplementalGroups`.** Give the agent its group with `agent.securityContext.runAsGroup`.
* **Mount `hostPath` or inline `csi` volumes.** Agent volumes may be `emptyDir`, `configMap`, `secret`, `persistentVolumeClaim`, `downwardAPI` and `projected` (from `configMap`, `secret` or `downwardAPI` only).

To give the agent a writable volume without `fsGroup`, use an `emptyDir`, a PersistentVolume already owned by the agent's user ID, or a PersistentVolumeClaim whose StorageClass sets the owner at mount time (for example SMB CSI `mountOptions: [uid=10002, gid=10002]`, or EFS CSI access-point `uid` and `gid`).

## Upgrades

The webhook admits only the Quint image digests it was started with, so add the new digests to the webhook before you upgrade the chart's images. The new chart, images and digests come from your Quint contact. Leave `workload.terminationGracePeriodSeconds` at 90 seconds or more, so a run has time to stop.

## If this fails

| What you see | What it means | What to do |
| - | - | - |
| `helm install` fails with a reason | The chart refused a value before anything reached the cluster | Fix the value the message names. |
| The pod is refused when it is created | The admission webhook refused it | Read the reason in the error, or in the Job or Deployment events. See [What the webhook refuses](https://docs.quintai.dev/install/admission-webhook.md#what-the-webhook-refuses). |
| The agent container never starts | `quint-sidecar` has not passed its startup check, often because it can't reach the Quint API | Check [network policies](https://docs.quintai.dev/install/containers.md#network-policies) and the `quint-sidecar` logs. |
| `quint-sidecar` restarts and the pod stays cut off | A restarted sidecar does not resume the run; the pod stays closed and the run is lost | Delete the pod. Its Job or Deployment starts a new run. |

## Next

* [The Quint admission webhook](https://docs.quintai.dev/install/admission-webhook.md)
* [Restricted setup](https://docs.quintai.dev/install/kubernetes-restricted.md) for namespaces that enforce `restricted`.


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