Publishing the image

The Image workflow (.github/workflows/image.yml) publishes ghcr.io/hyperstructure/sandbox from main only. Its first job, "What to build", decides whether there is anything to do and says why in the run's summary; then each architecture builds on a runner of its own (amd64 on ubuntu-24.04, arm64 on ubuntu-24.04-arm), is pushed by digest and checked with check.sh, and the last job tags the two as one image.

When it runs

Every build installs that fctl release from https://fctl.sh/releases and the newest Claude Code (https://downloads.claude.ai), and passes both versions to check.sh.

fctl's Release workflow (.github/workflows/release.yml in hyperstructure/fctl) starts the run for each release as soon as the release is on fctl.sh, as the organization's fctl-actions GitHub App, and its Sandbox image job waits for it: a failed run fails that job, and its summary links the run. Runs here go one at a time, and GitHub keeps only one of them waiting, so a newer run cancels the release's while it waits; the job then starts it again, up to three times. To stop a release's run for good, cancel that job first. "What to build" gives fctl.sh two minutes to show a release. GitHub starts the hourly run hours late at times, so it is only the fallback.

Tags and labels

• <version> (0.4.0): the release's image. Hosts of that version pull it.
• <major>.<minor> (0.4): moves only when the build is the newest patch of its minor. fctl's releases count up one patch at a time and fctl.sh keeps them all, so the workflow asks fctl.sh for the next patch.
• latest: moves only for the newest release, the one fctl.sh's latest names.

A release later than the one fctl.sh's latest names moves both without asking: fctl.sh caches latest for a minute, and the release's own run can start before that minute is out.

The image and its index carry org.opencontainers.image.version (fctl's version), sh.fctl.claude-code.version, org.opencontainers.image.revision (the commit built) and org.opencontainers.image.created. The workflow reads them back to decide whether an image is current.

Running it by hand

It takes write access to Actions on this repository (people have it; fctl sessions don't, so ask a person):

gh workflow run image.yml -R hyperstructure/sandbox                     # the newest release, if needed
gh workflow run image.yml -R hyperstructure/sandbox -f version=0.3.0    # another release
gh workflow run image.yml -R hyperstructure/sandbox -f force=true       # even when current
gh run list -R hyperstructure/sandbox --workflow image.yml --limit 3
gh run watch -R hyperstructure/sandbox ID --exit-status

Checking what's published

With Docker:

docker buildx imagetools inspect ghcr.io/hyperstructure/sandbox:0.3.0   # linux/amd64 and linux/arm64
docker buildx imagetools inspect --raw ghcr.io/hyperstructure/sandbox:0.3.0 | jq .annotations
docker run --rm -i ghcr.io/hyperstructure/sandbox:0.3.0 sh -s < check.sh

Without Docker (an fctl session), from the registry's API:

token=$(curl -fsS "https://ghcr.io/token?scope=repository:hyperstructure/sandbox:pull" | jq -r .token)
curl -fsS -H "Authorization: Bearer $token" \
  -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://ghcr.io/v2/hyperstructure/sandbox/manifests/latest |
  jq '{annotations, platforms: [.manifests[].platform | "\(.os)/\(.architecture)"]}'
curl -fsS -H "Authorization: Bearer $token" https://ghcr.io/v2/hyperstructure/sandbox/tags/list

The kernel

The Kernel workflow (.github/workflows/kernel.yml) publishes ghcr.io/hyperstructure/sandbox-kernel, the kernel of fctl's Firecracker sandboxes, from main only, the same way: it builds each architecture on its own runner, boots it with kernel/check.sh where the runner has KVM (amd64's), pushes both by digest and tags them as one image, <kernel/VERSION> and <major>.<minor>. It runs when a push to main changes kernel/ and that version isn't published yet; a published version is never built again, since hosts pin it and keep what they pulled, so a change to the build takes a new version (6.18.59-2). gh workflow run kernel.yml runs it again after a failure. Check what's published as for the image, with sandbox-kernel in its name.

When something fails

Publishing happens only after both architectures passed check.sh, so a failed run leaves the published tags as they were (and an untagged digest behind, which is harmless).

• "What to build" fails: fctl.sh or downloads.claude.ai didn't answer as expected; the error says what came back. Rerun it later.
• check.sh says the Claude Code version differs: a Claude Code release landed between planning and building. Rerun the run.
• check.sh fails otherwise, or the build does: the image is broken, often by a change upstream (an installer or a package moved). Fix it in a pull request (the change-the-image skill); its own Image run shows the fix works.
• The push is denied: the package must give this repository write access (the package's settings → Manage Actions access). It has it when this workflow created the package.
• Hosts can't pull it ("unauthorized", "denied"): the package must be public. A package starts private when the workflow first creates it; a person makes it public in the package's settings (Danger zone → Change visibility), and the organization must allow public packages.
• fctl's Sandbox image job failed: its summary links the run it started here, and the items above say what to do. A fix merged to main publishes the newest release's image at once. When the job failed before it started a run, its token is at fault: fctl's release skill says what to do, and meanwhile gh workflow run image.yml -R hyperstructure/sandbox -f version=X.Y.Z builds the image.
• The workflow stopped: GitHub turns off scheduled workflows in a public repository after 60 days without activity, and emails a warning first; fctl's Release workflow can't start it then either. A person turns it back on with gh workflow enable image.yml -R hyperstructure/sandbox, then runs it by hand. Meanwhile a new fctl release has no image of its own, and its hosts start sessions from latest.

Never delete a published version that has a tag: hosts pull by tag, and a broken one is fixed by a rebuild.