Chainguard Workspaces on

Chainguard Workspaces overview

Thu, 08 Oct 2026 00:00:00 +0000

Chainguard Workspaces moves development, and the coding agents that do it, off your laptop. The chainctl develop command opens a session: a Linux microVM in Chainguard’s cloud with your repository checked out, the tools your repository needs, and, by default, Claude Code. You work in it from your own terminal.

A coding agent that runs on your laptop can read your SSH keys, cloud credentials, and browser sessions, and every package it installs runs with the same access. In a session, the agent works in a separate VM that holds no long-lived credentials. When the agent pushes to GitHub or calls Claude, the request leaves the VM without a credential, and your laptop or Chainguard adds one on the way out.

Get started with Chainguard Workspaces

Thu, 08 Oct 2026 00:00:00 +0000

A Chainguard Workspaces session is a VM on Chainguard’s infrastructure, not on your laptop, for one of your GitHub repositories. When you run chainctl develop in your repository’s directory, chainctl creates a session, syncs your checkout into it, and opens a shell in it. There you can build, test, and run Claude Code as you would on your laptop. When you detach and come back later, your files and running processes are as you left them. To learn how sessions work, including how your directory gets into one and how a session isolates your code, refer to the Chainguard Workspaces overview and How Chainguard Checks and Chainguard Workspaces isolate your code.

Manage Chainguard Workspaces sessions

Thu, 08 Oct 2026 00:00:00 +0000

A Chainguard Workspaces session lasts beyond a single terminal. You can detach from it and return later, keep it running while an agent works, run more than one terminal in it, copy text out of it, or open several sessions on the same repository. This page explains how to do each of these with chainctl develop.

The examples on this page use $ORGANIZATION for the name of your Chainguard organization. If you belong to only one organization, you can omit --parent.

Configure a Chainguard Workspaces session's environment

Thu, 08 Oct 2026 00:00:00 +0000

A Chainguard Workspaces session’s environment is the set of packages installed in its VM and the network access it has. Packages come from Chainguard’s package repositories: your organization’s Private APK Repository and the public Wolfi and Extra Packages repositories. This page explains where a session’s environment comes from and how to change it.

A session’s environment is fixed when the session is created. If your repository’s .chainguard/develop.yaml or .chainguard/ci.yaml file changes afterward, existing sessions keep the environment they started with. When you return to a session that you opened from a local directory, chainctl reminds you of the change. To use the new environment, open a new session with chainctl develop --new.

Manage Chainguard Workspaces session credentials

Thu, 08 Oct 2026 00:00:00 +0000

A Chainguard Workspaces session holds no long-lived credentials: its VM stores no API keys, tokens, or registry logins. Instead, the session reaches each service through a local hostname, and the credential is added to the request outside the VM. This page explains what a session can reach by default, how to change it, and which credentials a session can’t supply.

A check in Chainguard Checks can get short-lived credentials through a workload identity, which a session can’t use. Refer to Workload identities and trust.

Let Chainguard Workspaces sessions act on GitHub as you

Mon, 12 Oct 2026 00:00:00 +0000

By default, a Chainguard Workspaces session reaches GitHub through the Chainguard App with access to specific repositories, as described in Manage session credentials. If you connect your GitHub account, the sessions you create afterward act on GitHub as you instead, unless your organization’s user_github policy bans it. They act through the Chainguard Develop GitHub App (chainguard-develop), which is separate from the Chainguard App that runs Chainguard Checks. A session that acts as you can do the following:

Use Claude Code in a Chainguard Workspaces session

Thu, 08 Oct 2026 00:00:00 +0000

A Chainguard Workspaces session is a place for a coding agent to work with less risk to your laptop. The agent runs in the session’s VM, which holds no long-lived credentials, and it reaches Claude with your own Claude credential, which stays outside the VM. This page explains how to run Claude Code in a session, and how to let an agent on your laptop work in one.

Claude Code is the only coding agent that sessions supply a model credential for. You can install other coding agents in a session, but sessions don’t send them a credential. Every session writes a guide that any agent can read, as described in The session’s guide for agents.

chainctl develop command reference

Mon, 12 Oct 2026 00:00:00 +0000

The chainctl develop command opens and manages Chainguard Workspaces sessions. This page lists each chainctl develop command, with its flags, output formats, exit codes, and the roles it needs. For how the commands fit together, refer to Manage sessions.

The generated chainctl develop reference has the help text of the latest chainctl release. If this page and the generated reference disagree about a command’s flags, the generated reference is right. To read the help for the version you have installed, run chainctl develop --help, or add --help to any command on this page. You can shorten chainctl develop to chainctl dev. If your installation of chainctl doesn’t recognize a command or flag on this page, update chainctl.

Troubleshoot Chainguard Workspaces

Thu, 08 Oct 2026 00:00:00 +0000

This page describes common problems with Chainguard Workspaces sessions and how to fix them. If your problem isn’t listed here, ask in the #workspaces-questions channel in the Chainguard community Slack.

chainctl doesn’t list the develop command

chainctl 0.2.390 and earlier don’t list the chainctl checks and chainctl develop commands in chainctl --help. You can still run them, and --help on either one shows its full help. Later releases list both, and the chainctl reference documents them.