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.

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 page. You need a cluster that meets the requirements, the Quint admission webhook 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 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.

   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.

   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.

   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.

   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):

   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.

​

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.
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 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
• Restricted setup for namespaces that enforce restricted.