Terminal
Terminal/Skill
Walks you through setting up a remote CircleCI sidecar for running validation commands in a clean environment.
By CircleCI
Works with
npx skills add circleci-public/skills --skill chunk-sidecar-setupThis skill walks you through setting up a chunk sidecar from scratch. A sidecar is a remote Linux container provisioned on CircleCI. It mirrors your local working tree and runs your build, test, and validate commands in a clean, isolated environment — no local port conflicts, no dependency drift, no "works on my machine."
What you'll have by the end:
chunk validate confirmed passing on the sidecarWork through the stages in order. At each decision point, call AskUserQuestion as specified. Do not skip ahead.
Run these three probes and evaluate the results:
chunk --version 2>&1 || echo "CHUNK_NOT_INSTALLED"
chunk auth status 2>&1
cat .chunk/config.json 2>&1 || echo "{}"
chunk --versionIf the command is not found, stop and explain: "chunk is not installed or not on your PATH. Install it first (e.g. brew install circleci/tools/chunk on macOS), then re-run this skill."
chunk auth statusRead the output carefully — it prints the status of each credential:
| Credential | Required for |
|---|---|
| CircleCI | All sidecar commands (required) |
| GitHub | Validate commands that fetch PRs/issues |
| Anthropic | Validate commands that invoke Claude |
If CircleCI shows "Not set", run the OAuth login yourself — see Logging in below — then re-run chunk auth status and confirm it shows "Configured" before continuing. For GitHub and Anthropic, surface that they're missing but do not block if the user's validate commands don't need them.
OAuth is the default. The user opens a URL, the code comes back over PKCE, and the token lands in the system keychain — no token pasting.
chunk auth login
127.0.0.1 on this machine, so the URL only works from a browser on the same host.Environment, CIRCLE_TOKEN is set and wins over the keychain. Do not log in — treat it as configured.chunk auth set circleci (paste a personal API token) is the fallback for when OAuth fails or the user asks for token auth.Never run echo $CIRCLE_TOKEN, env, printenv, or any command that exposes credential env vars. The chunk auth status output masks tokens — that is the only safe way to check credentials.
After evaluating auth, ask:
AskUserQuestion:
header: "Auth check"
question: "Auth looks good — ready to continue, or do you want to re-check something?"
options:
- "Continue to sidecar setup" ← Recommended
- "Re-run chunk auth status"
→ run chunk auth status again and show output
- "I need to set a credential"
→ for CircleCI, run chunk auth login (see Logging in);
for GitHub or Anthropic, tell user to run chunk auth set <service>
A CircleCI org ID (UUID) is required before creating a sidecar. Interactive org selection does not work in agent sessions, so it must be pre-configured.
cat .chunk/config.json for orgID.test -n "${CIRCLECI_ORG_ID:-}" (do not print the value).AskUserQuestion:
header: "OrgID required"
question: "Your CircleCI org ID isn't configured. What would you like to do?"
options:
- "I have my org ID — enter it now"
→ ask user to paste the UUID
run: chunk config set orgID <id>
- "How do I find my org ID?"
→ explain: "In the CircleCI web app, open Organization Settings (the gear icon
in the left nav). Your org ID is the UUID shown at the top of the page."
then ask for it and run: chunk config set orgID <id>
orgID is already in config or env, tell the user: "OrgID is configured — good to go."AskUserQuestion:
header: "Sidecar name"
question: "Do you want to name your sidecar, or use an auto-generated name?"
options:
- "Auto-generate a name" ← Recommended
description: "chunk picks a fun name like 'happy-quickly-tesla'. Easy to
identify, no typing required."
→ proceed without --name
- "I'll choose a name"
description: "Good if you want something memorable like 'dev' or your username."
→ ask user for the name, then use --name <name> in Stage 4
Create the sidecar:
chunk sidecar create [--name <name>]
This provisions a fresh Linux container on CircleCI. It takes 30–90 seconds. While it starts, explain: "The sidecar is starting up. Once it's ready, we'll sync your local code to it."
Then sync your local working tree:
chunk sidecar sync
Sync mirrors your entire local tree (including staged and unstaged changes) to ~/workspace/<repo> on the sidecar. You never need to commit or push first — the sidecar always sees exactly what's on your disk right now.
After sync, run chunk sidecar current --json and show the user the resolved workspace path so they know where their code lives on the sidecar.
AskUserQuestion:
header: "Dependencies"
question: "How should we install your project's dependencies on the sidecar?"
options:
- "Auto-detect with chunk sidecar setup" ← Recommended
description: "chunk detects your stack (Go, Node, Python, etc.) and runs
the right install commands automatically."
→ run: chunk sidecar setup --dir .
- "I'll specify the install commands"
description: "Run custom commands on the sidecar (e.g. 'go mod download')."
→ ask user for commands
run each via: chunk validate --remote --cmd "<cmd>"
- "Skip — deps are already in the base image"
description: "Your sidecar image already has everything installed."
→ skip to Stage 6
After dependency install, check locally:
ls .circleci/test-suites.yml 2>/dev/null && echo "FOUND" || echo "NOT_FOUND"
AskUserQuestion:
header: "Smarter Testing"
question: "Does this project use CircleCI Smarter Testing (test-suites.yml)?"
options:
- "Yes — install circleci-testsuite on the sidecar"
description: "Installs the circleci CLI and circleci-testsuite plugin so
you can run 'doctor' validation on the sidecar."
→ install circleci CLI and circleci-testsuite:
chunk validate --remote --cmd "curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | sudo bash"
chunk validate --remote --cmd "circleci update install"
(follow any additional circleci-testsuite install steps for the org)
- "No — skip"
→ continue
If test-suites.yml was found locally, recommend "Yes" in the question text.
Do this before running validate. Nothing routes to the sidecar until a command
is marked remote: true in .chunk/config.json, and the sidecar now being up
does not mark anything on its own:
chunk sidecar setup (Stage 5, auto-detect path) marks only install and
gate-role commands.So check what is marked, then mark the rest:
chunk validate --list # tags each command [local|remote, role]
chunk validate --mark-remote # mark all but autofix commands
chunk validate --mark-remote test # or one at a time
--list tags every command with where it runs and its role, so read that before
and after marking rather than guessing.
The bare --mark-remote deliberately skips autofix commands (formatters,
codegen) and prints which ones it left alone. Those rewrite files, and on the
sidecar the edits never come back to the local working tree. Only mark one by name
if the user explicitly wants it running remotely. Already-marked commands report
no change, so re-running is safe.
Confirm the sidecar environment is working:
chunk validate
chunk validate runs all configured commands in .chunk/config.json. Commands marked remote: true run on the sidecar; others run locally. Zero exit = everything passed.
If nothing ran on the sidecar, no command is marked — go back to Stage 6.
If it fails:
chunk validate prints per-command headers and propagates the first non-zero exit.chunk validate --remote --cmd "<install-command>".chunk sidecar sync, re-run chunk validate.When it passes, tell the user: "Validate passed. Your sidecar environment is healthy."
A snapshot saves the current sidecar state as a reusable image. Future sessions create a new sidecar from this snapshot and skip the whole install process — typically 30 seconds to a working environment instead of several minutes.
Always snapshot once validate passes — do not skip this step.
Ask the user for a name:
AskUserQuestion:
header: "Snapshot name"
question: "What should we call this snapshot?"
options:
- "Use repo name + today's date"
description: "e.g. 'chunk-cli-2026-08-12' — easy to identify later."
→ construct name as <repo-basename>-<YYYY-MM-DD>
(read repo name from: basename $(git remote get-url origin) .git)
- "I'll choose a name"
description: "Type a descriptive name like 'go-dev-env' or 'main-snapshot'."
→ ask user for the name
Create the snapshot:
chunk sidecar snapshot create --name <snapshot-name>
Note the snapshot ID from the output. The source sidecar is automatically deleted after a successful snapshot — that is expected behavior. Local active-sidecar state is also cleared; chunk sidecar current will return empty until you launch from the snapshot in Stage 9.
Persist the snapshot ID:
chunk config set validation.sidecarImage <snapshot-id>
This overrides the per-command routing from Stage 6. With
validation.sidecarImage set, chunk validate sends every command to the sidecar
regardless of its remote flag or role — including autofix commands. If the user
needs a formatter to keep rewriting local files, they run it directly (task fmt,
gofmt -w .) rather than through chunk validate. Tell them that here, not after
they wonder where their formatting went.
Create a fresh sidecar from the snapshot — this is the clean environment you'll use going forward:
chunk sidecar create --image <snapshot-id>
chunk sidecar sync
Then re-verify:
chunk validate
This second validate confirms the snapshot boots correctly and your code is in sync.
When Stage 9 validate passes, tell the user:
Setup complete. Here's what was configured:
- OrgID: saved to
.chunk/config.json- Snapshot ID:
<snapshot-id>saved asvalidation.sidecarImagein.chunk/config.json- Active sidecar: running and passing validate
Going forward: run
/chunk-sidecarto start the dev loop. It will detect your snapshot and offer to launch a new sidecar automatically when needed. For the tight loop: sync → validate, repeat with each set of local edits.
Could not select an organization / no interactive terminal — OrgID is missing. Return to Stage 2.chunk auth status. If the CircleCI token is stale or missing, re-run chunk auth login (Logging in). Never dump env vars.permission denied (publickey) on sync or exec — run chunk sidecar add-ssh-key --public-key-file ~/.ssh/chunk_ai.pub. If it persists, tell the user to remove ~/.ssh/chunk_ai* to regenerate the keypair on next use.context deadline exceeded — sidecar is unhealthy. Run chunk sidecar forget and restart from Stage 4 with a new sidecar.chunk sidecar setup — install with chunk validate --remote --cmd "<install>", verify with chunk validate, then re-snapshot (Stage 8 onward).--image won't boot a new sidecar — snapshot IDs are org-scoped. Confirm the new sidecar is being created in the same org as the snapshot. Run chunk sidecar snapshot list to verify available IDs.