> ## 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. # Workloads: agents in containers > Set up a workload, start a container under it, then read its runs, decide held tool calls, stop a run, and manage its keys and settings. A workload groups AI agents that run in containers, such as CI jobs, servers and sandboxes, under a name you choose. Each container start is a run. Workloads are on the **Workloads** page, under **Monitor**. ## What a workload is A workload is for agents that run in containers rather than on a developer's machine. It uses your organisation's rules and has its own approvers, keys and network settings. A container uses one of the workload's keys to register. Quint checks every tool call in the run against the rules and records it with its decision. While a container runs, it checks in with Quint about every 30 seconds. The dashboard calls each check-in a heartbeat. A stop, a revoked key or a changed network setting reaches a run at its next heartbeat. Inside a container, Quint records tool calls, model exchanges and network connections. It covers agents without a supported hook at the network level only, and it does not record file and process activity in containers. ## The list Before the first workload, the page shows **Set up your first workload** with four steps: **Set up a workload**, **Create a key**, **Build from agent-base and run**, **Runs appear here**. Once a workload exists, four tiles count **Live runs**, **Runs today**, **Blocks today** and **Pending approvals**. Below them each workload has one row. The row shows how many runs it has, when it last ran, whether its network is open (**Observe**) or limited (**Allowlist**), and how many runs it may have at once (**Cap**). A badge says whether the workload is **Active** or **Disabled**. ## Set up a workload Creating and changing workloads, keys and approvers needs Admin or Owner; Read members and Policy Writers can read every workload and run. At the end you have a workload with a key, approvers and the container settings for its first run. Before you start: * Your own rules refuse or hold tool calls only once **Enforcement** is on for your workspace. Until then a run records what they would have done. See [Shadow enforcement](https://docs.quintai.dev/policies/shadow-enforcement.md). * An approval takes two people: the person who starts a run can't approve its held tool calls. Someone trying this alone cannot decide the request, so a second person has to. **1. Open the form** Click **Set up a workload**. The steps are listed down the left: **Basics**, **Notifications**, **Network and limits** and **Connect a container**. **Back** and **Continue** move between the first three. **2. Fill in Basics** * **Name**: lowercase letters, digits and hyphens. It can't be changed later. * **Description**: optional. * **Concurrency cap** (default 20): the most runs that may be live at once. A run over the cap is refused. The form also says how the cap is billed: "Each unit is billed as one container machine, and only on days a run is live." * **Approval wait**: how long a held tool call waits for an approver before it is denied. Pick **2 min**, **5 min**, **10 min** (the default) or **15 min**. Your rules' own limit and the agent's own timeout can make the wait shorter. **3. Choose Notifications** **Notify according to policy** is on by default. While it is on, **Approval requests** are always sent. * For **Blocks**, pick **Don't notify**, **All blocks** or **Only these categories**. A block notice names the rule, its family and the run. It never carries the arguments or the agent's text. * Tick at least one of your **Channels**, or click **Connect a channel**. With a PagerDuty channel chosen, **Also send block notices to PagerDuty** appears. With notifications off, or with no working channel, nobody can be asked to approve. Every tool call a rule would hold is then refused at once. **4. Set Network and limits** Under **Network access** you choose which websites and services the agent can reach. The form explains each choice: * **Network mode**: "Observe: the agent may reach any destination; every connection is recorded. Allowlist: only the destinations below are reachable." * **Allowed destinations** (under **Allowlist**): one per line. "A host, or a wildcard like `*.example.com`; add :443 or :443,8443 to limit the ports." * **Private networks**: **Allowed** (the default) or **Restricted**. "Cloud metadata and Quint's own addresses are always refused." * **Private ranges** (under **Restricted**): at least one address range such as `10.0.0.0/8`. Each range must sit inside `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10` or `fc00::/7`. Most workloads can leave **Timing and limits** closed. It holds three numbers: * **Stop grace** (1 to 20 seconds, default 5): how long the agent gets to finish after a stop. * **Evidence flush timeout** (2 to 60 seconds, default 10): how long Quint then gets to send its last records. * **Process limit** (256 to 65,536, default 4,096): the most programs the agent may run at once. Then click **Create workload**. **5. Create the key** Under **Workload key**, click **Create key**. The key is shown only once. Copy it, store it in your CI secret store as `QUINT_WORKLOAD_KEY`, then click **Done**. **6. Copy the container settings** Use **Copy** on the **Dockerfile**, **docker run** or **Kubernetes** snippet. The **docker run** and **Kubernetes** snippets already carry the workload's name. Then click **Go to workload**. The snippets stay on the workload's **Keys** tab under **Connect a container**. **7. Name the approvers** On the **Approvers** tab, click **Change approvers** and pick the people who may approve or deny this workload's held tool calls. Read members and people who have not accepted their invite can't be picked. Until you save, nobody is an approver, so a held tool call waits until it expires and is then denied. **8. Start a container** Follow [Run an agent in a container with Docker](https://docs.quintai.dev/install/docker.md). Its first requirement is access to the agent-base image, which your Quint contact arranges. For the **Kubernetes** snippet, see [On Kubernetes](https://docs.quintai.dev/install/docker.md#on-kubernetes) on that page. To run Quint in its own containers beside an unchanged agent image, see the [Kubernetes setups](https://docs.quintai.dev/install/containers.md). A run appears on the workload's page when a container starts with one of its keys. If the workload page shows "Applying settings…", start the first container when the notice is gone. See [Change settings later](#change-settings-later). ## The workload page The header shows the workload's name, whether it is **Active** or **Disabled**, and its network mode: * **Observe**: "Every destination is visible, not restricted." * **Allowlist**: "Anything not on your signed allowlist is refused." **Edit settings** needs Admin or Owner. Others see "Admins can change workloads." The page has five tabs. **Approvers** and **History** are shown to Admins and Owners only. * **Overview** has two parts. * The settings: **Notifications**, **Concurrency cap (billing ceiling)**, **Approval hold budget (seconds)**, which is the **Approval wait** in seconds, and **Policy pack**, the rules in use. * The counts: **Live runs**, **Runs today (UTC)**, **Blocks today (UTC)**, **Last run** and **Harnesses, last 30 days**. A harness is the agent program, such as Claude Code. * **Runs**, **Keys** and **Approvers**: see [Use a workload](#use-a-workload). * **History**: who created the workload, changed it or its settings, or set its approvers. Quint needs somewhere to send an approval request. If the workload's notifications are off, or none of its chosen channels is enabled, nobody can be asked. Quint then refuses the tool call at once, and every page of the workload shows "No working channel: approval requests are blocked". Click **Choose a channel** to fix it. Quint does not fall back to another channel. The agent sees: "Blocked: approval requests from this workload are blocked because it has no working notification channel. An admin can choose one in the Quint dashboard." Deleting or disabling a channel on **Integrations** does the same to every workload that is left with no other working channel. ## Use a workload ### Find a run The **Runs** tab lists the workload's runs, newest first, 50 at a time. **Load older runs** shows more. Each row has the run's ID, its **Status**, when it started and ended, and its exit code (the number the container reported when it stopped). Filter by **All**, **Running**, **Ended** or **Lost contact**. **Lost contact** means the run stopped reporting before it said it had ended. Runs are kept for at least 30 days. ### Read a run Click a run's ID. The header names the run and its workload, its status, and a line such as "Ran for 4 min 12 s and ended: the agent finished with code 0". The run has three tabs. **Overview** has four parts: * **Facts**: when the run started and ended, its exit code and **Ended reason**, the agent, the image and the Quint version. * **Events**: how many events Quint stored, sent and dropped. * **Effective values**: the **Stop grace**, **Flush timeout** and **Process limit** the container ran with, and where each came from. * **What this run's evidence does not cover**: what Quint could not see. **Unobserved connections**, also under **Facts**, counts connections Quint could see but not read. **Activity** lists every event Quint stored for the run, newest first, 100 at a time. Each row has a **Time**, a **Type**, what the event concerns (**Tool, model or host**), a **Verdict**, the **Rules** that matched and a **Target**. To see one kind of event, pick it under **Event type**. While the run is live, the list refreshes every 5 seconds. Events are kept for at least 14 days. **Approvals** lists every held tool call of the run: the **Rule** that held it, its **Status** (**Waiting**, **Approved**, **Denied** or **Expired**), when it was held and decided, who decided it, and any **Guidance** the approver gave. **Ended reason** says how the run ended: | Ended reason | Exit code | | - | - | | "The agent exited on its own." | The agent's own code | | "Terminated from the dashboard or by a runtime stop." | 78 | | "The run's credential was revoked." | 77 | | "Heartbeats to the platform failed." | 77 | | "Quint's daemon died or wedged." or "Tampering was detected." | 70 | A run's credential is revoked when its key is revoked or rotated, or when its workload is disabled. ### See a refused connection With **Allowlist**, Quint refuses any connection to a destination that is not on the list. It also refuses private addresses the workload does not allow. On the run's **Activity** tab each refusal is a row of type `HTTP_REQUEST_BLOCKED` with the verdict **blocked**. To list only refusals, pick `HTTP_REQUEST_BLOCKED` under **Event type**. The row's **Tool, model or host** cell names the destination when the container's agent-base image reports it. The images released so far do not, and the cell shows "—". In that case, look in the agent's own output for the address it could not reach. If the agent needs that destination, add it under **Allowed destinations**. ### Decide held tool calls A held tool call waits for one of the workload's approvers for up to its **Approval wait**. Approvers decide it on the **Approvals** page, or from the **Decide** link on the run's **Approvals** tab. See [Decide an approval](https://docs.quintai.dev/dashboard/decide-an-approval.md). Before a tool call can be held and approved, each of these is needed: * **Enforcement** is on for your workspace. Until then your own rules hold nothing: the run records what they would have done. See [Shadow enforcement](https://docs.quintai.dev/policies/shadow-enforcement.md). * The workload has a working channel and at least one approver. * The run says who started it. Otherwise its held tool calls can be denied but not approved. See [Run an agent in a container with Docker](https://docs.quintai.dev/install/docker.md). * The approver is not the person who started the run. An approval takes two people. ### Stop a run A running run's page has **Terminate run**. Admins and Owners can use it on any run. A Policy Writer can use it on runs of a workload that names them as an approver. A Read member sees "Admins and approvers can terminate runs." **1. Click Terminate run** A dialog asks "Terminate this run?" and says what will happen. The stop reaches the container at its next heartbeat, within about 30 seconds. The container then exits with code 78, and the agent's unfinished work is lost. **2. Click Terminate** If you last signed in more than 10 minutes ago, the page says "Sign in again to terminate." Click **Sign in again**, then repeat. Otherwise the header shows **Terminate requested** until the run ends. The ended reason is then "Terminated from the dashboard or by a runtime stop." To stop every run of a workload, disable it (see [Change settings later](#change-settings-later)), or revoke its keys. ### Rotate or revoke a key The **Keys** tab lists each key with its **Prefix**, when it was created, when it **Last started a run** and its **Status** (**Active** or **Revoked**). The buttons are **Create key**, **Rotate** and **Revoke**. * **Rotate** creates a new key, shown once, then revokes the old one. Update your CI secret before the next run. Live runs that registered with the old key stop at their next heartbeat with exit code 77. * **Revoke** stops the runs that use the key at their next heartbeat, with exit code 77. The page confirms that they stop within about 90 seconds. Containers started with the key can't register again. ### Change settings later **Edit settings** opens the same four steps. You can open any step, and one **Save** saves them all. The name can't change. **Basics** gains **Status**: a disabled workload refuses new runs and stops live ones at their next heartbeat. When you change channels, the old ones get one message saying so. When a workload's network settings or **Approval wait** differ from the defaults (**Observe**, **Allowed** and **10 min**), Quint needs a moment to apply a change, usually under a minute. Meanwhile the workload page shows "Applying settings…". It does so after a save, right after the workload is created, and when your organisation's rules are published again, which turning **Enforcement** on also does. While the notice shows: * Running containers keep their current settings, then pick the change up at their next heartbeat. * Don't start a new container yet. With the agent-base images released so far it stops at once, and its log ends with a line containing `variant_not_ready`. If that happens, start the container again when the notice is gone. If the page shows "Settings could not be applied.", click **Retry**. No new container can start until it succeeds. Changes to **Timing and limits** apply to runs that start after the save. ## Where it runs Workloads run in Docker on Linux, in Docker Desktop on Mac, and on Kubernetes. For Docker Desktop on Windows, rootless Docker or Podman, talk to your Quint contact first. ECS Fargate and gVisor are not supported. On Kubernetes, ClusterIP and API-server addresses count as private networks for the **Private networks** setting. ## If this fails | What you see | What it means | What to do | | - | - | - | | "Admins can change workloads." | You are Read or Policy Writer | Ask an Admin or Owner. | | "No run in the last 30 days." | No container has registered recently | Check the key and the snippets under **Keys › Connect a container**. | | One of your own rules did not refuse or hold a tool call | **Enforcement** is off for your workspace, so the run recorded what the rule would have done | See [Shadow enforcement](https://docs.quintai.dev/policies/shadow-enforcement.md). | | "Nobody is set as an approver…" | Held tool calls expire and are denied | Click **Change approvers**. | | "No working channel: approval requests are blocked" | No enabled channel carries approval requests | Click **Choose a channel**. | | An approver sees "The person who started this run cannot approve it." | The run did not say who started it, so nobody can approve its held tool calls. They can still be denied | Set `QUINT_RUN_INITIATOR` for the next run. See [Run an agent in a container with Docker](https://docs.quintai.dev/install/docker.md). | | An approver sees "You started this run, so someone else has to approve its requests." | The approver started the run | Ask another approver. | | The agent reports "Approval timed out after N s" | Nobody decided within **Approval wait** | Decide sooner, or lengthen the wait under **Edit settings**. | | "Settings could not be applied." | Quint could not apply the workload's settings, and no new container can start | Click **Retry**. | | "Admins and approvers can terminate runs." | You are a Read member | Ask an approver, an Admin or an Owner. | | "You need to be an approver for this workload, or an admin, to stop this run." | You are a Policy Writer who is not an approver for this workload | Ask an Admin to add you under **Change approvers**. | | "This run is no longer live." | The run ended before the stop was sent | Nothing to stop. | | The container refuses to start | See the log line | See [Docker: if this fails](https://docs.quintai.dev/install/docker.md#if-this-fails). | ## Next * [Run an agent in a container with Docker](https://docs.quintai.dev/install/docker.md) * [Decide an approval](https://docs.quintai.dev/dashboard/decide-an-approval.md) for what approvers see. * [Alerts in Slack, Teams and PagerDuty](https://docs.quintai.dev/integrations/alerts-in-slack-teams-pagerduty.md) to connect a channel. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.