Skip to content

Document busy keep-running and the Claude login Chainguard holds - #4269

Merged
tylerpaxton merged 1 commit into
mainfrom
tp.wc-docs-0383
Oct 21, 2026
Merged

Document busy keep-running and the Claude login Chainguard holds#4269
tylerpaxton merged 1 commit into
mainfrom
tp.wc-docs-0383

Conversation

@tylerpaxton

@tylerpaxton tylerpaxton commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

This PR updates the Chainguard Workspaces and Chainguard Checks docs to match chainctl 0.2.388. Two changes in recent releases change how sessions behave after you detach:

  • A session created with chainctl 0.2.383 or later keeps running while it's busy, such as during a build, a Claude Code turn, or a run-ci run. It parks after it's been idle for 10 minutes, and no later than 24 hours after you last detach. The session menu's default detach option is now Detach — keep running while busy.
  • chainctl develop claude login lets Chainguard hold a Claude login for your sessions. Chainguard then sends the session's host short-lived access tokens from it, whether or not you're attached, so Claude Code keeps working while you're away.

The pages also raise the minimum chainctl version to 0.2.386.

Changes

  • overview.md: how detached sessions keep running while busy, the third credential source (a login Chainguard holds), and how busy time counts against the monthly allowance.
  • getting-started.md: the new default detach option, and chainctl develop claude login as an alternative to logging in to Claude Code on your laptop.
  • manage-sessions.md: the session menu's detach options, what counts as busy, the busy command (new section, "Mark a session busy"), --keep park, which detach options keep the terminal serving your laptop's credentials, and the idle and busy states in chainctl develop list.
  • session-environment.md: every session has the busy command.
  • credentials.md: the owner source, when a session gets your Google Cloud refresh token, and which detach options keep serving.
  • coding-agents.md: a new "Let Chainguard hold your Claude login" section, a rewritten "Keep Claude Code working while you're away" section, the provider-selection order, and a new "Keep a credential from your laptop working" section.
  • chainctl-develop-reference.md: the chainctl develop claude commands and their output, the --keep park value, the owner source, and the new JSON fields.
  • troubleshooting.md: new entries for a Claude login held by Chainguard that doesn't work, chainctl develop claude login failures, and sessions that parked while an agent was working. It also updates the stored-login renewal and the monthly allowance entries.
  • run-checks.md: a run-ci run keeps a detached session busy.
  • how-it-works.md: the detached and parked session states, and how a held Claude login reaches the session's host.
  • set-up.md: the new minimum chainctl version, and a note that updating doesn't change existing sessions.

For the reviewer

  • Version gates. Keeping a session running while it's busy and the Claude login Chainguard holds both arrived in chainctl 0.2.383. The pages say that sessions created with "chainctl 0.2.382 or earlier" don't keep running while busy, because the idle policy is set when a session is created and can't change. The minimum is 0.2.386 because that release places a --keep duration's hold as the attach opens, so the session gets your Google Cloud refresh token from the start, as credentials.md describes.
  • Detach option names. The new default option, Detach — keep running while busy, starts with the same words as the timed options, but it places no hold, so the terminal you detach from stops serving your laptop's credentials. Wherever a page says the terminal keeps serving, it names Detach — keep running 4h and Detach — keep running for… instead of "a Detach — keep running option".
  • "Idle" wording. The pages say that a session "parks after it's been idle for 10 minutes", which matches the idle state in chainctl develop list. Quoted CLI output, such as parks after 10m quiet, stays as chainctl prints it.

How this was checked

  • Behavior, defaults, messages, and limits come from chainguard-dev/mono at the v0.2.388 tag. That includes the session menu's detach options, the hold and serving rules, the busy probe's CPU and network thresholds, the resume gate when the monthly allowance is used up, the Google Cloud credential mode, and the list state strings. The release that introduced each feature was confirmed against the v0.2.382 through v0.2.388 tags.
  • A review pass checked each page for accuracy against that source and for style. Each accuracy finding was checked against that source before it was applied.
  • pre-commit (all content hooks) and markdownlint-cli2 pass on the changed files.
  • A link check over the changed files found no broken internal links or anchors.

🤖 Generated with Claude Code

@tylerpaxton @claude
Document busy keep-running and the Claude login Chainguard holds
5e9f47f 
Match chainctl 0.2.388. A session created with chainctl 0.2.383 or
later keeps running after you detach while it's busy, and parks after
it's been idle for 10 minutes, no later than 24 hours after you last
detach. Document what counts as busy, the busy command, --keep park,
the new default detach option, and how list shows busy and idle
sessions.

Document chainctl develop claude login, status, and logout, the owner
credential source, and how a session gets fresh Claude access tokens
whether or not you're attached. Update the Google Cloud refresh token
rules, add troubleshooting for parks and the held login, and raise the
minimum chainctl version to 0.2.386.

Name the timed detach options wherever a terminal keeps serving after
you detach, since "Detach — keep running while busy" doesn't, and
fix other accuracy and wording issues found in review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Oct 20, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
chainguard-docs-preview Ready Ready Preview Oct 20, 2026 8:57pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
chainguard-docs Ignored Ignored Oct 20, 2026 8:57pm UTC

Request Review

@tylerpaxton tylerpaxton mentioned this pull request Oct 20, 2026
Merged
@tylerpaxton
tylerpaxton marked this pull request as ready for review October 21, 2026 15:08
@tylerpaxton
tylerpaxton requested a review from a team as a code owner October 21, 2026 15:08
@tylerpaxton
tylerpaxton merged commit 4568922 into main Oct 21, 2026
13 checks passed
@tylerpaxton
tylerpaxton deleted the tp.wc-docs-0383 branch October 21, 2026 15:08
tylerpaxton added a commit that referenced this pull request Oct 21, 2026
@tylerpaxton @claude
Merge main into tp.wc-docs-dan-fixes
bb5d6f6 
Resolve the conflicts left by squash-merging #4269 to this branch's
side. Main's copies of those files match #4269's original commit, so
the net change against main is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tylerpaxton added a commit that referenced this pull request Oct 21, 2026
@tylerpaxton @claude
Address review comments on the Checks and Workspaces docs (#4271)
f835966 
This PR addresses the review comments on #4171 and #4172 that arrived
after they merged, except the ones that main already covers. It builds
on #4269 and should merge after it. Until #4269 merges, this PR's diff
also includes #4269's commit, so review only the last commit on the
branch.

Some comments got different wording from what they suggested, because
the code changed after the review or works differently than described.
Those cases are listed under **Not changed**.

## Changes

### Chainguard Checks

- `chainctl-checks-reference.md`:
- New `chainctl checks failures` and `chainctl checks attempts` sections
and table rows, and a pointer from `logs --attempt` to `attempts`.
- A rewritten `chainctl checks cancel` section: `--force` for runs that
GitHub started, who can cancel a run, how to cancel a pull request's
run, and what GitHub shows afterward. It replaces the line that said you
can't cancel pull request runs.
- `migrate` takes an optional `--dry`, and the section says what running
without it does: up to six test runs, which need a role and use the
Checks allowance.
- `accept-terms` says `owner` or `limited_owner`, the `limited_owner`
paragraph also covers `migrate` without `--dry`, and the `--workflow`
rows fit both layouts.
  - An `{#id}` on every heading.
- `configuration.md`:
- The single-file layout can hold more check files beside `ci.yaml`, and
the file table has a row for other `.yaml` files in `.chainguard/`.
- `requested_checks_agent` goes only in `ci.yaml` or
`ci/env/default.yaml`, and `deps.yaml` joins the `develop.yaml` row.
- Packages come from the Wolfi and Extra Packages repositories and your
organization's Private APK Repository.
- New sections: "How commands run," "Variables that Chainguard Checks
sets," and "Git in a check's VM."
- Network access describes HTTPS interception and the cases where the
host's own certificate is kept.
- Triggers states the rule for `needs` and `from` across triggers, with
an example and a `{#triggers}` anchor.
- Advisory checks and Run on request point to the rule that a pull
request can't weaken its own checks.
- Resources says a check's VM has no KVM device, and Timeouts says two
hours.
- `github.md`:
- Closing or merging a pull request doesn't cancel its run, and
`chainctl checks cancel --force` stops it.
- Only checks that don't pass or that report something get their own
GitHub check, and `<file>` is the defining file's name in either layout.
- A pull request keeps the base branch's setting for a check until it
merges, and a stricter change applies on the same pull request.
- A rerun from `chainctl` shows **Re-run requested by *IDENTITY_ID* via
chainctl**.
- `identity-and-trust.md`:
- A check that uses an identity keeps its base branch's `when.expr`
conditions until the pull request merges. This is a new row in "Which
runs get an identity," and the paragraph on what a condition protects is
rewritten.
- Ring `2` for an identity that the default branch doesn't define
applies only when the default branch has a `trust` section.
- A running check loses an identity within about 10 minutes after an
`identities.yaml` change and about 18 minutes after a `trust` change. A
new paragraph says what happens to the check.
- `variations-services-caches.md`: a new "Run Docker" section, a `with`
example that also sets `PGPORT` for the check, the trigger rule for
`from`, and a `root` check that can use the Go build cache.
- `troubleshooting.md`: a new "A check fails with a certificate error"
section, a trigger row that quotes `does not support trigger`, `owner`
or `limited_owner` in the terms row, a cache row that allows `root` with
`gobuild`, and "A check stops after two hours" in place of the 50-minute
section.
- `overview.md`: HTTPS interception, which checks get their own GitHub
check, and the two-hour limit.
- `getting-started.md`: which checks get their own GitHub check, and why
to require only the summary check.
- `migrate-from-github-actions.md`: a Background processes row, the
two-hour limit, a Go cache row for `root` checks, and a link from the
services row to "Run Docker."
- `run-checks.md`: for `the guest is held by another controller`, attach
and run `run-ci`, or run the command again after the session parks. A
session runs on arm64 only if its resource class pins arm64.

### Chainguard Workspaces

- `coding-agents.md`:
- An unattended agent can also push to the checkout's other github.com
remotes where the Chainguard App is installed, with separate advice for
narrowing internet access and push access.
- A new "The session's guide for agents" section, which replaces "brief"
across the page.
- A new "Share skills and instructions from your laptop" section, and a
fix to the paragraph that said `chainctl` doesn't copy them.
- `github-as-you.md`: a workflow that the session pushes gets a
`GITHUB_TOKEN` that can do what the session can't do directly. "Protect
your branches" adds a push ruleset on `.github/workflows/**/*` and
turning off GitHub Actions approvals.
- `manage-sessions.md`:
  - A new "Copy text from a session" section.
- What happens when your laptop sleeps or goes offline, and that a
`--keep` hold starts when you attach.
- Returning to a session that's still parking, and what a park drops and
keeps.
  - The 6-day renewal and what it does to credentials.
- **Share from laptop** and **Status** rows in the session menu table,
and a link to the new session states table.
- `overview.md`: what the `.git` sync sends, how it treats symbolic
links and special files, where packages come from, and a pointer to
clipboard copy.
- `session-environment.md`:
- The environment change reminder applies only to sessions opened from a
local directory.
- `develop.yaml` can name a `gobuild` cache but not `services`, and
`from` names only a check file or an environment file.
  - The warm cache example drops `--check`.
- The order a `--check` session takes its size from, and arm64 only from
a resource class that pins it.
  - Packages come from Chainguard's package repositories.
- `chainctl-develop-reference.md`: a new "Session states" table that
maps each JSON `state` value to the `STATE` column.
- `troubleshooting.md`: a new "Returning to a session takes several
minutes" section, and the `missing: terms.accept` bullet no longer says
"only."

### Get started

- `set-up.md`: accepting terms and `--parent` take `owner` or
`limited_owner`. `init` picks your only Starter or Team organization
whatever your role, then stops with `missing: terms.accept`. A new
prerequisite covers people who already belong to an organization.
- `how-it-works.md`: the 6-day renewal waits while you're attached,
which checks get their own GitHub check, HTTPS interception, and the
glossary entry for a check.

## For the reviewer

- **Changes beyond the comments.** Three things changed in production
after #4172 merged, and the new text would have contradicted the old, so
this PR updates them on every page:
- A run can take up to two hours, not 50 minutes. The troubleshooting
anchor is now `#a-check-stops-after-two-hours`, its one inbound link is
updated, and the error row quotes the current message, `workflow run
exceeded its execution deadline`.
- A check that passes without reporting anything gets no GitHub check of
its own.
- A check that runs as `root` can use the Go build cache without `user:
build`.
- **Share from laptop.** The new section in `coding-agents.md` goes
beyond its comment. The old text said a session never takes your
laptop's skills or `CLAUDE.md`, which is no longer true. Drop the
section if you'd rather document the feature separately.
- **Anchors.** On existing headings, each added `{#id}` matches the slug
Hugo already generates, so no inbound link changes except the renamed
two-hour heading.
- **Examples not run as written.** The Docker service files are adapted
from a working configuration, and the `keytool` command from the VM's
certificate setup, but neither has been run as written in a customer's
check. That `git commit` fails without a Git identity follows from Git's
behavior, and wasn't tried in a check's VM.

## Not changed

- The `viewer` role for `sandbox.user` teammates (#4171, #4172): #4265
already removed it.
- The `chainctl checks failures` paragraph in
`inspect-and-run-checks.md` (#4172): #4203 already added it, so this PR
adds only the reference sections.
- `chainctl develop claude login` (#4171): #4269 documents it.
- The `coding-agents.md` copy of the `held by another controller` advice
(#4171, #4172): #4259 removed it, so the fix is only in `run-checks.md`.
- The attach guide wording (#4171): `chainctl` remembers the first
attach per laptop, not per session, so the page is right.
- Exited terminals and the `R` key (#4171): a terminal closes when its
command exits, as the page says, so `R` has nothing to restart.
- Laptop sleep timings (#4171): the page leaves out the suggested
90-second and 11-to-12-minute figures, because noticing a sleeping
laptop can take several minutes, and a busy session now keeps running
instead of parking.
- Setting a session's architecture in its environment (#4171):
`environment.arch` is still refused, so arm64 comes only from the
resource class.
- Not counting `github-actions[bot]` reviews (#4171): GitHub has no such
setting, and turning off GitHub Actions approvals already stops them.
- The `migrate` flags `--ref`, `--max-proves`, and `--parity` (#4172):
they apply only without `--dry`, which the page advises against during
the beta.
- `failures` as the next step after `run-ci` (#4172): `run-ci` creates
no run for `failures` to read.
- `SHELL` in the variables table (#4172): checks don't get it, because
it's set only for an interactive terminal.
- "Reserved" `CHAINGUARD_` and `CG_` prefixes (#4172): nothing enforces
a reservation, so the page advises against the prefixes instead.
- A GitHub token in the `when.expr` rule (#4172): checks get no GitHub
token during the beta.
- `guardener.admin` in role lists: it also holds `terms.accept`, but
role lists name only `owner` and `limited_owner`.

## Found but not fixed here

- The `chainctl checks list` section says it lists only runs started
with `chainctl checks run`, and several pages say you can't rerun runs
after merging. `chainctl` 0.2.388 lists every run, and Chainguard Checks
reruns the newest finished postsubmit run. The fix touches `github.md`,
`troubleshooting.md`, and `inspect-and-run-checks.md`, and needs a check
of whether **Re-run** on GitHub works for a postsubmit run.
- `set-up.md` says a personal email address can't create a Chainguard
organization. Production has allowed it since October 10.
- `variations-services-caches.md` says only `gobuild` stores data and
that `gobuild: {}` takes no settings. The `gomod` cache and the `key`
and `size` settings are deployed.
- Several pages say a pull request's checks run on the commit GitHub
would create by merging. Chainguard Checks now creates that merge commit
itself.
- `identity-and-trust.md` doesn't cover AWS workload identities, which
are deployed.
- Resource classes in `.chainguard/ci/resources/<name>.yaml` files are
deployed but not documented.

## How this was checked

- Each fix was checked in chainguard-dev/mono: at the `v0.2.388` tag for
`chainctl` commands, flags, and output, and at the commit deployed to
production on October 20 for server behavior, limits, and production
settings. On the released `chainctl` 0.2.388, only `--help` was run.
- Each comment was compared with current main first, so this PR doesn't
repeat fixes from #4203, #4217, #4259, #4263, or #4265.
- The GitHub settings in `github-as-you.md` were checked against
GitHub's documentation.
- A review pass checked each changed page for accuracy and style, and
each accuracy finding was checked in code before it was applied.
- `pre-commit` and `markdownlint-cli2` 0.23.3 pass, and all 537 internal
links and anchors on the Checks, Workspaces, and get-started pages
resolve.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@matthewhelmke matthewhelmke mentioned this pull request Oct 22, 2026
Merged
matthewhelmke added a commit that referenced this pull request Oct 22, 2026
@matthewhelmke @claude
Match the getting-started minimum chainctl version to the set-up page (…
e8890e3 
…#4292)

Both getting-started pages say readers need `chainctl` 0.2.382 or later,
but the set-up page they link to says 0.2.386, the minimum since #4269.
A reader with 0.2.382 through 0.2.385 meets the quick start's
requirement but not the set-up page's. This changes both pages to
0.2.386.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview – chainguard-docs-preview — 5e9f47fc Deployed Oct 20, 2026 by vercel[bot]
View deployment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@matthewhelmke matthewhelmke matthewhelmke approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@tylerpaxton @matthewhelmke