[fctl-sh]

This sets up the repository: the default sandbox image for fctl sessions moves here from hyperstructure/fctl (its images/agent, as hyperstructure/fctl#39 left it), with the workflow that publishes it to ghcr.io/hyperstructure/sandbox for arm64 and amd64, and what people and agents need to change it. hyperstructure/fctl#39 makes fctl hosts pull the image from there and removes the image from fctl.

What's here

• The image: Dockerfile, provision.sh (which also provisions fctl's Lima VM) and check.sh (the layout fctl and images built FROM this one rely on: the agent user, sudo, the PATH, the tools), unchanged from fctl but for their comments and one ShellCheck note. They sit at the root, where fctl host image build finds them in an archive of main. .dockerignore sends only provision.sh to the build.

• Image workflow: builds each architecture on a native runner (ubuntu-24.04, ubuntu-24.04-arm), pushes it by digest, checks it with check.sh and tags both as one image: :<fctl version> for every fctl release, plus :<major>.<minor> and :latest when that release is the newest they cover. Each image is main with that release of fctl (from fctl.sh) and the newest Claude Code, labelled with both versions, the commit and the date. Only main publishes:

  • every hour, the newest fctl release's image when there is none yet or it predates the last change to the image (fctl's Release workflow can't start workflows here, so this is what notices a release);
  • on a push to main that changes the image, at once;
  • every day at 05:41 UTC, also when Claude Code has a newer release than the image, or the image is a week old;
  • by hand: gh workflow run image.yml (-f version=0.3.0, -f force=true).

  Pull requests that change the image build and check both architectures without publishing.

• Lint (ShellCheck, and actionlint at a pinned, checksummed version) and Commits (pull request titles are Conventional Commits, with fctl's rules). Dependabot updates the actions once a month.

• README.md for people who use the image: what's inside, the tags and when they're rebuilt, the labels, the layout, building on it and building it, the licenses. AGENTS.md (and CLAUDE.md) for agents and people who change it: what fctl relies on, the conventions, the flow. Skills: change-the-image, publish and commit. SECURITY.md asks for private reports. MIT, like fctl.

For a person

1. Merge this. The Image workflow on main then publishes ghcr.io/hyperstructure/sandbox:0.3.0, :0.3 and :latest (fctl 0.3.0 is the newest release), which creates the package.

2. Make the package public: the organization's Packages → sandbox → Package settings → Change visibility. A package starts private even when its repository is public, and fctl hosts pull without signing in. The organization's settings must allow public packages.

3. Make the repository public and apply its settings. Until it's public, the hourly check spends the organization's Actions minutes for private repositories (a minute per run, about 12 hours a month); in public repositories they're free. The session's token can't change settings, so here they are, as on hyperstructure/fctl where they apply (squash merges with the title and description, branches deleted on merge):

   R=hyperstructure/sandbox
   gh repo edit $R --visibility public --accept-visibility-change-consequences
   gh repo edit $R \
     --description "The sandbox fctl's agents run in: Debian with Claude Code, git, the GitHub CLI, Python, Rust, Node.js, TypeScript and Bun, for arm64 and amd64." \
     --homepage https://fctl.sh \
     --add-topic fctl,claude-code,sandbox,docker,container-image,ai-agents \
     --enable-issues --enable-wiki=false --enable-projects=false --enable-discussions=false \
     --enable-squash-merge --enable-merge-commit=false --enable-rebase-merge=false \
     --squash-merge-commit-message pr-title-description \
     --delete-branch-on-merge --allow-update-branch
   # Security: private vulnerability reports (SECURITY.md asks for them), Dependabot alerts and fixes, secret scanning.
   gh api -X PUT repos/$R/private-vulnerability-reporting
   gh api -X PUT repos/$R/vulnerability-alerts
   gh api -X PUT repos/$R/automated-security-fixes
   gh repo edit $R --enable-secret-scanning --enable-secret-scanning-push-protection
   # Workflows get a read-only token unless they ask for more (the Image workflow asks for packages: write).
   gh api -X PUT repos/$R/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=false

   Optionally, protect main. Rulesets need the repository to be public on the organization's plan. This one requires pull requests (squash only, no approvals required, so a person can merge their own), the Lint and Commits checks (not Image, which runs only when the image changes), and no force pushes or deletion; repository admins can bypass it:

   gh api repos/$R/rulesets --input - <<'JSON'
   {"name":"main","target":"branch","enforcement":"active","conditions":{"ref_name":{"include":["~DEFAULT_BRANCH"],"exclude":[]}},"bypass_actors":[{"actor_id":5,"actor_type":"RepositoryRole","bypass_mode":"always"}],"rules":[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"pull_request","parameters":{"required_approving_review_count":0,"dismiss_stale_reviews_on_push":false,"require_code_owner_review":false,"require_last_push_approval":false,"required_review_thread_resolution":false,"allowed_merge_methods":["squash"]}},{"type":"required_status_checks","parameters":{"strict_required_status_checks_policy":false,"required_status_checks":[{"context":"Conventional Commits"},{"context":"ShellCheck and actionlint"}]}}]}
   JSON

4. Then merge feat(host): pull the sandbox image from GHCR instead of building it fctl#39. Hosts of the release after 0.3.0 pull their version's tag, which this repository publishes within the hour after the release.

GitHub turns off scheduled workflows in public repositories after 60 days without activity, warning by email first; gh workflow enable image.yml -R hyperstructure/sandbox turns the Image workflow back on (the publish skill).

Verification

• This pull request's Image run: both architectures built natively (amd64 in 2m56s, arm64 in 2m20s) and check.sh passed in each with fctl 0.3.0 and Claude Code 2.1.302 (run). Lint and Commits pass.
• The planning step, run locally against stubbed fctl.sh, downloads.claude.ai and registry responses, decides correctly in 19 cases: a pull request; hourly with no image (build), a current image with an older Claude Code (skip), an image built from the last change (skip) and one from before it (build), an index without annotations (build); daily with an older Claude Code or a week-old image (build) and a current one (skip); a push after a change (build); dispatches of 0.2.0 (no :0.2, as 0.2.1 exists), v0.2.1 (:0.2), a current image with an older Claude Code (build), a forced rebuild, another branch (build without publishing), a version fctl.sh doesn't have and a malformed one (errors); and odd answers from fctl.sh and downloads.claude.ai (errors).
• The title check passes feat: add PostgreSQL's client, fix(image): put Bun on login shells' PATH (#12), ci(deps): bump the actions group with 3 updates (Dependabot's), feat!: … and build(deps): …, and rejects a title without a type, an unknown type, a full stop, 76 characters, an empty description and Feat:.
• With fctl: fctl host image build from feat(host): pull the sandbox image from GHCR instead of building it fctl#39, with a stand-in docker, builds this checkout (--source) and a git archive of it served like GitHub's archive of main.
• Not verified here: pushing to GHCR with the workflow's token, creating the package and its visibility. They need packages: write on main, so merging this is their test.

Refs hyperstructure/fctl#2

Session: https://app.fctl.sh/s/ses_01M57B991V0YYBRJFN0WKEW118