Set up Chainguard Checks and Chainguard Workspaces

Chainguard Checks runs your repository’s CI on every GitHub pull request, with each check in its own microVM. Chainguard Workspaces runs your development work, and the coding agents that do it, in a remote microVM session that holds none of your long-lived credentials. You can use either product on its own, but they’re built to work together, and you set them up together: one command, chainctl develop init, turns on both. This page explains what the products share, then walks you through signing up and giving teammates access.

Note: Each product is in beta.

What the products share

How they work together

A typical loop uses both products:

1. Open a Workspaces session on your repository, and let Claude Code make a change.
2. Run run-ci in the session to run your repository’s checks against the change. Refer to Run checks before you push.
3. Push the change and open a pull request. Chainguard Checks runs the same checks and reports the result on the pull request.
4. If a check fails, read why from the session with chainctl checks failures, fix the change, and push again. Refer to Inspect pull request runs.

Prerequisites

Before you begin, make sure you have the following:

• A GitHub account that can install GitHub Apps on the personal account or organization that owns your repository. To install the app on an organization and link it, you need the owner role on that organization.
• A local clone of a repository on github.com that you can push to.
• A work email address. A personal email address, such as a Gmail address, can’t create a Chainguard organization.

Install or update chainctl

You sign up with chainctl, and you use it with both products: chainctl checks for Chainguard Checks and chainctl develop for Chainguard Workspaces. If you don’t have it yet, follow the chainctl installation guide.

Chainguard Checks and Chainguard Workspaces need chainctl 0.2.382 or later. Earlier releases can’t sign you up as this page describes or run Claude Code in a session. Both products change often during the beta, so if you already have chainctl, update it to the latest release:

sudo chainctl update

If you installed chainctl with Homebrew, run brew upgrade chainctl instead. Refer to Updating chainctl for details.

Install the Chainguard App

The Chainguard App is a GitHub App that connects your repositories to Chainguard. Chainguard Checks receives pull request events and reports results through it, and by default, Workspaces sessions fetch and push your repository through it. Guardener uses the same app.

1. Go to the Chainguard App installation page.
2. Choose the personal account or organization that owns your repository.
3. Choose All repositories, or select the repositories you want to use with Chainguard Checks or Chainguard Workspaces.
4. Review the requested permissions and select Install.

Installing the app doesn’t change your repositories. Chainguard Checks runs only on repositories that have a .chainguard/ci.yaml file, after you link the account in the next step.

Sign up with chainctl develop init

The chainctl develop init command signs you in, creates a free Chainguard Starter organization if you don’t have one, and turns on Chainguard Checks and Chainguard Workspaces. Each product gets its own free monthly allowance, which resets on the first day of each month (UTC). For what each allowance includes, refer to Availability and limits for Chainguard Checks and for Chainguard Workspaces.

Run the command in an interactive terminal, because it opens your browser and asks questions as it goes:

chainctl develop init

To create an organization, sign in with a work email address, using a password or a Google account. A personal email address, such as a Gmail address, can’t create one, and neither can other sign-in methods, such as GitHub or GitLab.

The command does the following:

1. Signs you in through your browser, and registers a new Chainguard identity if you don’t have one.
2. Picks the Chainguard organization to use:
   • If you don’t belong to one, it asks your name, company, job title, and whether you want updates from Chainguard, then creates one, named after your email domain.
   • If you belong to exactly one organization on the Starter or Team plan, it uses that one.
   • Otherwise, it stops and asks you to choose an organization with --parent.
3. Asks you to accept the terms that Chainguard Checks and Chainguard Workspaces are offered under, if your organization hasn’t accepted them yet: the Code Analysis Terms, the Secured Platform Terms, the Master Service and License Agreement, and, for the GitHub link, the Guardener Terms of Service and Data Privacy Agreement.
4. If your organization isn’t linked to a GitHub account yet, asks which one to link. Link the account that owns your repository: press Enter to link your own GitHub user, or enter the name of a GitHub organization where you have the owner role, such as acme, not a URL. The command opens your browser so you can authorize the link. If the Chainguard App isn’t installed on the account, the command offers to open the installation page, then authorizes and links the account again.
5. Turns on Chainguard Checks and Chainguard Workspaces with their monthly allowances, and prints each product’s limits. If Chainguard already granted your organization an allowance, the command keeps it.
6. Offers to connect your GitHub account, if you haven’t yet and your organization allows it, so that the Workspaces sessions you create act on GitHub as you. The connection uses Chainguard Develop, a GitHub App separate from the Chainguard App. If you run the command in your repository’s directory, it also offers to install Chainguard Develop on the GitHub accounts your repository needs. Chainguard Checks doesn’t need this connection, so you can decline and connect later with chainctl develop github login, as described in Let sessions act on GitHub as you.

When you authorize the link, GitHub might ask you to authorize single sign-on for your GitHub organizations. If you’re linking your own GitHub user, select Continue. To link an organization that uses SAML single sign-on, authorize single sign-on for that organization.

A GitHub account can be linked to only one Chainguard organization at a time. If the account you choose is already linked to another Chainguard organization, chainctl develop init names the account and, in an interactive terminal, asks for a different one to link. To move the account to your organization instead, press Ctrl+C to stop the command, and then refer to Moving a GitHub organization to a different Chainguard organization.

If chainctl develop init stops with an error, refer to chainctl develop init fails.

Answer questions ahead of time

You can answer some of the command’s questions with flags:

For example, to link the acme GitHub organization:

chainctl develop init --github-org acme

For every flag, refer to the chainctl develop init reference.

Use an organization your company already has

If your company already has a Chainguard organization, chainctl develop init can’t create a second one for your email domain. Ask one of its owners to add you, as described in Give teammates access. An owner can then turn on both products in it, replacing $ORGANIZATION with the organization’s name:

chainctl develop init --parent $ORGANIZATION

If the organization already has Chainguard Checks or Chainguard Workspaces through your Chainguard account team, the command keeps that allowance.

An organization that has a product through the account team must also accept that product’s terms, which takes the owner role. Until an owner accepts them, Chainguard Checks runs no checks for the organization, so the summary check on each pull request fails with Run creation failed, and no one can open a Workspaces session in it. To accept the terms for one product only, use its own command:

chainctl checks accept-terms --parent $ORGANIZATION
chainctl develop accept-terms --parent $ORGANIZATION

If your GitHub account isn’t linked to the organization yet, link it as described in Getting started with Guardener, which uses the same Chainguard App.

Give teammates access

Your teammates don’t need a Chainguard account to get checks on their pull requests or to read the results on GitHub. A teammate needs a role in your Chainguard organization to open the Chainguard Checks run page, to use chainctl checks commands such as status and rerun, or to open Workspaces sessions. Each teammate opens and manages their own sessions, which count toward your organization’s limits.

A teammate who uses sandbox.user also needs viewer. For more about roles, refer to Overview of roles and role-bindings.

Add a teammate

In a Starter organization, the steps differ, as described in Add a teammate to a Starter organization. If you have the owner role in your organization, invite your teammate and grant them the sandbox.user role as follows. Replace $ORGANIZATION with the name of your Chainguard organization:

1. Create an invite for your teammate with the viewer role. Your teammate needs it as well as sandbox.user, because sandbox.user alone doesn’t let chainctl find your organization. Replace $EMAIL with your teammate’s email address:

   chainctl iam invite create $ORGANIZATION --role viewer --email $EMAIL

2. Send your teammate the invite code that the command prints. Your teammate accepts the invite by logging in with it, replacing $INVITE_CODE with the code:

   chainctl auth login --invite-code $INVITE_CODE

3. After your teammate accepts, list your organization’s role-bindings. The output shows each member’s identity ID next to their email address:

   chainctl iam role-bindings list --parent $ORGANIZATION

4. Grant your teammate the sandbox.user role, replacing $IDENTITY_ID with their identity ID:

   chainctl iam role-bindings create --identity $IDENTITY_ID --role sandbox.user --parent $ORGANIZATION

Your teammate can then install chainctl, as described in Install or update chainctl, and open a session, as described in Get started with Chainguard Workspaces.

Add a teammate to a Starter organization

If you created your organization with chainctl develop init, it’s a Starter organization, and you have the limited_owner role rather than owner. You can’t create role-bindings for other users, so you can’t grant the sandbox.user role, and members read Chainguard Checks results on GitHub instead of on the run page. An invite can give only a role whose permissions you also have, and of those roles, only limited_owner can open sessions.

To invite a teammate, run steps 1 and 2 of Add a teammate. To let your teammate open sessions, use --role limited_owner instead of --role viewer in step 1:

chainctl iam invite create $ORGANIZATION --role limited_owner --email $EMAIL

The limited_owner role also lets its holder manage your organization’s billing and invite or remove members.

Each invite must name your teammate’s email address with --email, and the address must be in your organization’s domain or one of its subdomains.

A coworker whose email address is in your organization’s domain can also ask to join by running chainctl starter request-access, which emails you the request. For details, refer to Request access with chainctl.

Next steps

• Get started with Chainguard Checks: add a .chainguard/ci.yaml file and see your first checks run.
• Get started with Chainguard Workspaces: open your first session.
• Use Claude Code in a session: work with a coding agent in a session.