Cut your environment setup time in half with Chunk sidecar snapshots

When you’re building with AI, you can get a lot done in 30 seconds. Waiting minutes for CI feedback on your latest change can feel like an eternity.

Chunk sidecars are designed to give you feedback fast, running your full test suite against the same Linux environment as CI, directly inside the agentic loop. Traditional CI pipelines can take five or ten minutes to catch a basic lint error or failing unit test. One of the biggest reasons is environment spin-up: provisioning a remote machine, installing dependencies, getting to a state where your tests can actually run. With snapshots, you do that work once and cache the result.

A snapshot freezes your sidecar environment after setup and stores it in CircleCI’s cloud. Sidecars already spin up faster than a full CI pipeline, and snapshots cut that time in half or better. Every subsequent boot starts from that cached state instead of from scratch.

In this tutorial you’ll create a sidecar, snapshot it, boot from the snapshot, and share it across the org so everyone gets the same fast, pre-configured environment from day one.

Just getting started with sidecars? Check out Run your first microbuild in 5 minutes.

Prerequisites

• A CircleCI account and a personal API token. Create the token in the CircleCI app under User Settings → Personal API Tokens.
• Homebrew, to install the Chunk CLI.
• Your CircleCI org ID (Organization Settings → Overview).
• A GitHub repository. You can also follow along using our sample app.

Getting faster feedback with Chunk sidecar snapshots

Sidecar setup is straightforward. Create a sidecar, let Chunk install the runtime and dependencies, and run the suite once to confirm everything works. Snapshot that state and you’re done.

Set up the project

Below, you’ll explore two paths to setting up sidecars: an agent-first flow that prompts your Claude Code agent to handle most of the setup, and a manual flow that shows how Chunk sidecars work under the hood.

Download the demo repo you’ll use for this example and install via npm:

git clone https://github.com/CircleCI-Public/circleci-demo-javascript-react-app
cd circleci-demo-javascript-react-app
npm install

Automatic setup with agent onboarding

Install the Chunk CLI and initialize the project:

brew install CircleCI-Public/circleci/chunk

Authenticate to the Chunk CLI using your CircleCI personal access token. Run the command and it will prompt you to input your token:

chunk auth set circleci

Now we’re ready to initialize Chunk:

chunk init

chunk init reads the repo, detects the stack, and writes .chunk/config.json.

You will also need to provide Chunk with your CircleCI org ID. Be sure to do this after running chunk init or it will be overwritten:

chunk config set orgID <your-org-id>

Then open Claude Code in the project and run the /chunk-sidecar skill:

claude
/chunk-sidecar

The skill takes over from there. It creates a sidecar, installs the runtime and dependencies, runs the suite to validate, and snapshots the result. When it finishes, your environment is captured as a snapshot and committed to the project, ready to boot from.

Now we have the Chunk CLI installed and a sidecar set up, validated, and snapshotted with a copy of our environment. All ready for us to use.

Boot from the snapshot in seconds

With the environment saved, a new sidecar skips the install. We can time the whole trip, from boot to a green suite using this command:

# WARM start → ~25s
time ( chunk sidecar create --org-id <your-org-id> \
  --image <your-snapshot-id> && chunk validate test --remote )

Restoring the snapshot takes a few seconds longer than a bare boot, because it brings back 261 MB of dependencies with no reinstall. From a fresh sidecar to a green test, the snapshot path took about 25.8 seconds.

Just for comparison, let’s see how long it takes to spin up a sidecar from scratch without our snapshot:

# COLD start → ~59s
time ( chunk sidecar create --org-id <your-org-id> && \
  chunk sidecar setup && chunk validate test --remote )

It took around 59.7 seconds booting from scratch. The snapshot is roughly 2.3 times faster. Both paths pay the same sync and Jest startup. What the snapshot removes is the install.

Share it with your team

A snapshot lives in CircleCI’s cloud, scoped to the org. There’s no image file to host and no registry to stand up. Sharing a snapshot means sharing a string. The cleanest way to share it is to commit the ID into the project config:

chunk config set validation.sidecarImage <your-snapshot-id>

✓ Set validation.sidecarImage to <your-snapshot-id>

With the ID committed to the repo, a teammate on the same org can clone the project, run chunk sidecar create --image <snapshot-id>, and land in the same validated environment you built, in seconds, without the install. A new hire skips first-day setup entirely.

The snapshot works for AI agents too. validation.sidecarImage is the image chunk validate boots, so an agent’s automatic checks start from the snapshot as well. Every agent gets your pre-configured environment to validate its work in.

The image isn’t frozen forever, either. When dependencies change in a way that matters, like a new package or a runtime bump, you can re-install, snapshot again, and repoint validation.sidecarImage at the new ID. Everyday code edits ride along on sync and don’t need a new snapshot.

Manual sidecar snapshot setup (optional)

If you prefer to set up your sidecar snapshots manually, follow these steps. If you already prompted your agent to complete the setup above, you can skip this section.

Install the CLI:

brew install CircleCI-Public/circleci/chunk

Inside the repo, chunk init reads the project and writes its config:

chunk init

Detected repository: CircleCI-Public/circleci-demo-javascript-react-app
Detected package manager: npm
Detected command: test (npm test)
✓ Wrote .chunk/config.json
✓ Wrote .claude/settings.json
✓ Project initialized

Chunk detects the npm and Jest stack and registers npm test as the validation command.

Manually create a sidecar from scratch

First, create a sidecar and check what it ships with:

chunk sidecar create --org-id <org-id> # REPLACE <org-id> with your actual CircleCI organization ID
chunk validate --remote --cmd "cat /etc/os-release | head -1; node --version"

✓ Created sidecar (d07eb7ca…)
PRETTY_NAME="Ubuntu 24.04.4 LTS"
sh: 1: node: not found

From here Chunk takes over. chunk sidecar setup reads the project, installs the runtime and the dependencies, and hands back a ready box:

chunk sidecar setup

Running setup step "system": curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs …
✓ Step "system" complete
Running setup step "install": npm install
added 1672 packages, and audited 1673 packages in 40s
✓ Step "install" complete
Setup complete. Verify the sidecar is working correctly, then snapshot it:
chunk sidecar snapshot create --name <snapshot-name>

setup is where Chunk does the work in two steps: a system step that installs the Node version the project pins in its CircleCI config, then an install step that runs the project’s dependency install from .chunk/config.json.

Installing roughly 1,673 packages took about 40 seconds on a cold cache. The sidecar runs the same Linux as CI, so a test that passes here passes there too.

Manually save the environment as a snapshot

Once the dependencies are installed and the tests pass, you can capture the whole environment:

chunk sidecar snapshot create --name node-react-snapshot

✓ Created snapshot <your-snapshot-id>
✓ Deleted sidecar <your-sidecar-id>

A snapshot turns that environment into an artifact: a frozen image of the sidecar with every dependency installed, so the next boot starts from work you already paid for.

Two things to know. First, snapshot create deletes the source sidecar once the image is saved, so the snapshot ID is your handle from here on.

Second, because snapshots are org-visible, you should never bake credentials into the image. Inject them at runtime instead.

Speed up your inner dev loop

In this demo, skipping the install saves 34 seconds of setup time. On a production project with a massive dependency tree, that footprint stretches into minutes. When you multiply those minutes by every developer, every branch, and every single session, you are looking at hours of reclaimed engineering time every week.

With Chunk sidecar snapshots, that setup cost is paid once, by whoever sets it up, and never again.

Ready to accelerate your development loop? Chunk sidecars are available now on any CircleCI plan, including the free tier. Sign up for a CircleCI account, install the Chunk CLI, and snapshot an environment worth keeping.