From df6f7e492586f370449c8649cf2d197628021798 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 18 Aug 2026 20:23:21 +0530 Subject: [PATCH 1/2] docs: add the runners page and the Aug 18 changelog entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dashboard's runner policy dialogs had nowhere to send an operator. Every field there is an assignment with a default and a range, and the form can state the degraded verdict but not explain it. The new page covers enrolment, the two environment variables a host reads, every policy field with its default and range, the three ways to stop a runner deliberately, and the limits — allowlist egress unenforced, no-sandbox refused outside development, and a self-declared capability report. The changelog entry leads with the one-step install, and names the upload source on the platform fleet library, the mounts vocabulary, the model price labels, and the development-runner lease failure. Co-Authored-By: Claude Opus 5 (1M context) --- changelog.mdx | 19 ++++++++++++ docs.json | 6 ++++ runners.mdx | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+) create mode 100644 runners.mdx diff --git a/changelog.mdx b/changelog.mdx index 07bd1ad..94bf72e 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,6 +7,25 @@ description: "Stay up to date with the latest agentsfleet product updates, new f agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## Installing a fleet is one step + + The install flow asked you to name the fleet, then asked again to confirm it. A name already in use failed the whole install at that second step. Install now runs from the card straight through to the live states, and the server renames a taken default for you by adding a three-digit suffix. Asking for a duplicate name yourself is still refused with `UZ-AGT-006`, because that one you meant. + + ## What's new + + - **A renamed install tells you its new name.** The response carries the name that was stored, and the dashboard shows that name rather than the one it started from. + - **The platform fleet library takes a bundle from your computer.** **Admin → Fleet library → Create fleet library** now offers the same GitHub and upload sources the workspace dialog already had. An uploaded entry records no repository and still lands as a draft, so publishing stays a separate act. + - **A runner policy dialog shows what is already mounted.** The paths `agentsfleetd` mounts on its own are listed as read-only rows, so you can see the baseline before adding to it. The screen says "mounts" throughout; the wire field is unchanged. + - **Model prices read as `Input`, `Cached`, and `Output`,** in United States dollars per 1 million tokens. + - **Runners have a page.** [Runners](/runners) covers enrolment, every policy field with its default and range, and what makes a runner stop taking work. + + ## Bug fixes + + - **A development runner no longer fails every lease with `runner_crash/HostResolutionFailed`.** The sandbox's readable-path set is derived from the same bind list the child is handed, so the files needed to resolve a host name are inside the sandbox. Operator mounts also reach the child at the mode they were assigned, read-only or read-write. + - **Dialog buttons say `Create`.** The button that opens the dialog keeps its noun, such as **Create fleet library**, so the two are no longer the same words in two places. + + ## A revoked integration grant stays revoked diff --git a/docs.json b/docs.json index 8320ea1..5014d0c 100644 --- a/docs.json +++ b/docs.json @@ -74,6 +74,12 @@ "workspaces/managing" ] }, + { + "group": "Runners", + "pages": [ + "runners" + ] + }, { "group": "Cost control", "pages": [ diff --git a/runners.mdx b/runners.mdx new file mode 100644 index 0000000..b165c47 --- /dev/null +++ b/runners.mdx @@ -0,0 +1,86 @@ +--- +title: Runners +description: What a runner does, the policy you assign it, and when it stops taking work. +type: explanation +audience: operator +verified: 2026-08-18 +product_version: 0.26.2 +executable: false +--- + +# Runners + +## What it is + +A runner is a host that runs your fleets. It takes work from `agentsfleetd`, runs it inside a sandbox, and reports the result back. + +You enrol every runner from the dashboard. The host holds one token and nothing else. It never holds a database credential, a cache credential, or vault access. + +## Why it exists + +Fleet code has to run on a machine somewhere. Keeping that machine outside the control plane means a compromised host cannot read another tenant's data. + +Runners are replaceable. When one stops answering, its unfinished work goes to another runner, so no event is lost. + +## How it behaves + +### Enrolling a host + +Open **Admin → Runners → Add runner** and fill in the policy. `agentsfleetd` mints a runner token and shows it once. Copy it before you close the dialog, because it is never shown again. + +Put that token on the host, then start `agentsfleet-runner`. The host reads two variables: + +| Variable | What it sets | Default | Valid values | +|---|---|---|---| +| `AGENTSFLEET_API_URL` | The control plane the runner asks for work. | none, required | URL beginning with `http://` or `https://` | +| `AGENTSFLEET_RUNNER_TOKEN` | The runner's identity, such as `agt_rtest00000000`. | none, required | The token the dashboard showed once | +| `RUNNER_STORAGE_HOME` | Where the host keeps its own scratch files. | a host-local path | An absolute directory path | + +No policy value is read from the host. A runner that carried its own isolation setting could disagree with the dashboard, and nothing would compare the two. + +### The policy you assign + +Policy travels down from the dashboard. Change it under **Admin → Runners → Edit policy** and the host applies it on its next heartbeat. Nobody logs in to the host. + +| Field | What it sets | Default | Valid values | +|---|---|---|---| +| Isolation | How strongly the host separates a running fleet from itself. | Landlock | Landlock, Nested container, None | +| Network policy | What the sandbox may reach on the network. | Allow all egress | Allow all egress, No egress, Allowlist egress | +| Allowlist | Registry hosts the sandbox may reach, as `host` or `host:port`. | empty | Up to 32 comma-separated host names | +| Workers | How many events the host runs at once. | 1 | 1 to 64 | +| Mounts | Extra host directories the sandbox can read or write. | the daemon's own baseline paths | Up to 16 absolute paths, each read-only or read-write | + +The three isolation settings differ in what enforces the boundary: + +| Isolation | What it means | +|---|---| +| Landlock | The Linux kernel restricts which files the fleet can touch. | +| Nested container | The fleet runs inside a container on a Linux host or virtual machine. | +| None | No sandbox. Development builds only. | + +### When a runner stops taking work + +A runner reports what its kernel can actually enforce on every heartbeat. `agentsfleetd` compares that report against the policy you assigned. + +When the host cannot meet the assignment, the runner is marked **degraded** and is sent no work. The reason names the one missing piece, such as cgroup controllers not delegated. Fix that piece, or lower the assignment, and the next heartbeat clears the mark. + +You can also stop a runner deliberately: + +- **Cordon** stops new work reaching it. +- **Drain** lets its current work finish, then leaves it idle. +- **Revoke** ends its token, so the host's next request is refused. + +A runner that simply disappears needs no action. Its work expires and another runner takes it. Work already reported is never run twice. + +## Limits + +- **Allowlist egress is not enforced yet.** A runner assigned it reads degraded and takes no work until that enforcement ships. Use No egress or Allow all egress today. +- **None is refused outside development.** A release build of `agentsfleetd` rejects it at startup. +- **Raising Workers past the count the host started with needs a restart.** Lowering it takes effect on the next heartbeat. +- **A host can lie about what it enforces.** The capability report is self-declared, so treat placement as something you decide, not something the host proves. + +## Related pages + +- [Install a fleet](/fleets/install) +- [Run and control a fleet](/fleets/running) +- [Manage secrets](/fleets/secrets) From 393f063bfc1b1be5eaf09b2fe1fbeb053191f94c Mon Sep 17 00:00:00 2001 From: Kishorekumar Neelamegam Date: Wed, 19 Aug 2026 09:25:34 +0530 Subject: [PATCH 2/2] Update runners.mdx Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- runners.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runners.mdx b/runners.mdx index b165c47..fb78bbf 100644 --- a/runners.mdx +++ b/runners.mdx @@ -28,7 +28,7 @@ Runners are replaceable. When one stops answering, its unfinished work goes to a Open **Admin → Runners → Add runner** and fill in the policy. `agentsfleetd` mints a runner token and shows it once. Copy it before you close the dialog, because it is never shown again. -Put that token on the host, then start `agentsfleet-runner`. The host reads two variables: +Put that token on the host, then start `agentsfleet-runner`. The host reads two required variables and one optional variable: | Variable | What it sets | Default | Valid values | |---|---|---|---|