How Chainguard Checks and Chainguard Workspaces isolate your code

Chainguard Checks runs your pull request checks, and Chainguard Workspaces runs your development sessions and coding agents, in microVMs that hold none of your long-lived credentials. This page collects the security model of both products in one place, for security reviewers who need to decide whether to allow them and for coding agents that need the rules. It describes how each product isolates code, where credentials come from, what code can reach on the network, who decides what a pull request gets, and how runs and sessions move through their lifecycles. A glossary at the end defines the terms both products use.

For sign-up and roles, refer to Set up Chainguard Checks and Chainguard Workspaces.

Note: Each product is in beta.

Isolation

Each check, and each session, runs in its own microVM built on Chainguard OS:

Chainguard treats the code in every VM as hostile, so the VM is the boundary that holds it:

• Chainguard puts no credential in the VM in a form its code could spend elsewhere. Credentials are added outside the VM, as described in Credentials.
• No host directory is mounted in the VM. Chainguard streams your repository, or the directory you sync to a session, into it.
• A session’s snapshot is sealed and bound to its owner, so a copy of it can’t restore anyone else’s session.

A check starts with nothing from earlier runs unless it declares a cache. Even then, a run gets a cache only from a cache pool that your default branch defines for the run’s ring.

In a session, run-ci runs your checks inside the session’s own VM, not in fresh VMs, so its environment can differ from a pull request run. Only Chainguard Checks, which runs each check in a fresh VM, decides what GitHub shows. Refer to How run-ci differs from a pull request run.

Credentials

Neither product puts a long-lived credential in the VM. Where a check or session needs access, the credential is added to its requests outside the VM.

Code in the VM can’t read the real credentials, but it can use them. Each request it sends carries the credential’s access, and anything it creates with that access, such as a Google Cloud service account key, outlives the check or session. Grant each workload identity only the access its checks need, and review a session’s credentials before you let an agent work in it unattended. Refer to Manage session credentials.

For a check’s workload identity, and for your Google Cloud credential in a session, a proxy outside the VM swaps in the real credential only on requests that it has verified over TLS as going to an allowed host. For a check’s Chainguard identity, the proxy also refuses opaque TLS tunnels to Chainguard hosts, and sends each request only to the host whose TLS name it verified.

Sessions can’t use workload identities, so run-ci skips checks that use one.

Two credentials sit outside these controls:

• A credential that you paste into a session, or that a tool there stores, such as with aws configure or npm login, stays on the session’s disk or in its memory, and in its snapshot when it parks. Any program in the session can read it. Do that work on your laptop instead.
• If you connected your GitHub account, sessions you create afterward act on GitHub as you, through the Chainguard Develop GitHub App. They can push, approve pull requests, and merge as you, and neither an egress list nor chainctl develop creds limits them. Refer to Protect your branches.

Network

Both products use the same network.egress allowlist, but they read a missing network key in opposite ways:

A session that uses the default environment, a .chainguard/develop.yaml file, or a file’s top-level environment reaches the open internet, because none of these can set network. To restrict a session, open it on a check that has an egress list. Refer to Network access.

Whatever a check or session allows, it never reaches cloud metadata endpoints, loopback addresses, or private IP ranges.

The egress list doesn’t apply to a session’s credential hostnames, such as http://github/ and http://claude/, so a session with a narrow list can still push to GitHub and use Claude Code. Google Cloud is different, because its requests go to Google’s own hosts: a check that uses a Google Cloud workload identity, and a session that uses your Google Cloud credentials with an egress list, must list sts.googleapis.com and the Google APIs they call.

To see which hosts a check tried to reach, and whether Chainguard Checks allowed each one, open the check’s run page from its Details link on GitHub. Refer to A check can’t reach a host.

Trust

Chainguard Checks reads the rules that limit a pull request, such as which checks gate it, which identities it can get, and how far it’s trusted, from branches the pull request can’t change. The pull request controls only what its checks run:

A pull request can add checks and change what they run, but it can’t weaken its own gate:

• A change that makes a check advisory, or makes it run only on request, takes effect after the pull request merges. Until then, the check keeps blocking.
• A change that removes a check, or stops it from running for this pull request, fails the summary check with Run creation failed.
• A change that leaves no presubmit checks fails the same way when the base branch has any.

Refer to Change checks in a pull request.

Rings

Chainguard Checks places each run in a ring, based on the trust section on your default branch:

An identity’s ring is the lowest ring that gets the identity. Only the account that opened the pull request counts: who pushed its commits, who reviewed it, and whether it comes from a fork don’t change the ring. Without a trust section, every open pull request whose base branch an identity allows gets that identity, including pull requests from forks, which run without approval. Refer to Limit which pull requests get an identity.

Run lifecycle

A run is one pass of a repository’s checks for one commit. The following table follows a pull request run from start to finish:

A new push to the pull request cancels the current run and starts a new one at stage 1. After a change merges, each new commit on your default branch gets its own run in ring 2, which reports Chainguard Checks (postsubmit). Refer to Use Chainguard Checks on GitHub.

Session lifecycle

A session moves through the following states:

However a session is used, its VM runs for at most 6 days at a stretch. Then Chainguard parks the session and resumes it right away, the same way the session menu’s Restart the host option does, so a session in long use isn’t cut off.

You can delete a session in any state. Anything you didn’t push is lost. A parked session counts toward your session limit until it expires or you delete it. Refer to Manage Chainguard Workspaces sessions.

Glossary

Chainguard App

The GitHub App that you install on your GitHub organization or personal account. It delivers pull request events to Chainguard Checks, and by default it fetches and pushes a session’s repository.

Chainguard Develop

A separate GitHub App, chainguard-develop. After you connect your GitHub account with chainctl develop github login, the sessions you create act on GitHub as you through this app instead of through the Chainguard App.

Check

One named entry under checks in your .chainguard/ci.yaml file or a file in .chainguard/ci/. On GitHub, each check reports as presubmit / <file> / <check>.

Park

To save a session’s memory and disk to a snapshot and stop its VM. A parked session resumes where it left off.

Ring

The trust level of a run: 2 for runs after merging, 1.<subring> for pull requests from accounts you trust, and 0 for every other pull request. Rings decide which runs get workload identities and caches.

Run

One pass of a repository’s checks for one commit: a pull request’s test merge commit, or a new commit on your default branch. Each run reports one summary check. The word also appears in messages such as Run creation failed and in capability names such as sandbox.run.list.

Session

A Linux microVM in Chainguard’s cloud that chainctl develop opens, with your repository at /work.

Variation

One entry in a check’s foreach list. Each variation runs in its own VM, and all of a check’s variations report as one GitHub check.

Workload identity

Short-lived credentials that Chainguard Checks gives a check while it runs, for Google Cloud or Chainguard. Sessions don’t get them.

Several names in chainctl and in the configuration don’t match the product names: