mroberts/ai-sandbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Target sbx 0.37 clone mode

Browse Source 
sbx 0.29 isolated the agent with --branch, creating a host-side Git worktree.
0.37 removed that flag and reinstated --clone, which gives the agent a private
in-container clone mounted read-only and exposes its commits through a
sandbox-<name> git remote on the host. Setup fails outright against 0.37 with
'--branch is no longer supported'.

Drops the branch name plumbing entirely, since the sandbox now owns the clone
and there is no host branch to name.

Documents the two host prerequisites this surfaced: membership of the kvm
group, because sandboxes are microVMs, and the docker-sbx package rather than
docker-sandbox-bin on Arch derivatives - the latter installs only the CLI,
omitting the microVM kernel, rootfs and nerdbox shim, which makes sbx fall back
to mounting filesystems on the host and fail for any non-root user.
This commit is contained in:
mroberts
2026-07-30 16:12:58 -05:00
parent 890d10a315
commit 4af8c1c153
2 changed files with 24 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+15 -6
View File
@@ -55,7 +55,8 @@ Install these on the **host** — none of them are needed inside the sandbox.
| Tool | Purpose | Install |
| --- | --- | --- |
| [mise](https://mise.jdx.dev/) | Runs the task and distributes it | [Getting started](https://mise.jdx.dev/getting-started.html) |
| [Docker Sandboxes (`sbx`)](https://docs.docker.com/ai/sandboxes/) | Sandbox, secret store, credential proxy | Ships with [Docker Desktop](https://docs.docker.com/desktop/) |
| [Docker Sandboxes (`sbx`)](https://docs.docker.com/ai/sandboxes/) | Sandbox, secret store, credential proxy | [Get started](https://docs.docker.com/ai/sandboxes/get-started/) — Docker Desktop is **not** required |
| KVM + membership of the `kvm` group | Sandboxes are microVMs | `sudo usermod -aG kvm $USER`, then re-login |
| [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), [`jq`](https://jqlang.org/) | `aws configure export-credentials` | Required only when using `--aws-profile` |
| `git`, `sha256sum` | Repository identity | Already present on most systems |
| `xdg-open` / `open` / `$BROWSER` | Opens the token form | Optional — the link is printed if absent |
@@ -73,8 +74,19 @@ mise --version
sbx version
aws --version
jq --version
lsmod | grep kvm # must show kvm_intel, kvm_amd or kvm
id -nG | grep -w kvm # you must be in the kvm group
```
`sbx` requires **0.37 or later** — `--clone` replaced the older `--branch` flag, and
this task uses `--clone`.
On Arch derivatives, install the **`docker-sbx`** AUR package, not
`docker-sandbox-bin`. The latter ships only the CLI binary, omitting the microVM
kernel, rootfs, and `containerd-shim-nerdbox-v1`. Without those, `sbx` has no VM to
boot and falls back to mounting filesystems on the host, which fails with
`operation not permitted` for any non-root user.
### User-level install (recommended)
Adding the task to your personal mise config makes `ai:sbx` available in every Git
@@ -109,7 +121,6 @@ Optional personal defaults:
[env]
AI_SBX_AGENT = "codex"
AI_SBX_MODE = "clone"
AI_SBX_BRANCH = "ai-sbx"
```
Confirm it loaded:
@@ -246,9 +257,8 @@ provider "aws" {
| --- | --- | --- |
| `--aws-profile NAME` | none | Host profile to expose. Repeatable. Trailing `-readonly` stripped inside the sandbox |
| `--agent NAME` | `codex` | Sandbox agent. See `sbx create --help` for the list |
| `--clone` | on | Give the agent a Git worktree on its own branch |
| `--clone` | on | Give the agent a private in-container clone; its commits reach the host via the `sandbox-<name>` git remote |
| `--direct` | off | Mount the host working tree read-write |
| `--branch NAME` | `ai-sbx` | Branch used by `--clone` |
| `--replace` | off | Destroy and recreate an existing sandbox |
### Environment defaults
@@ -257,7 +267,6 @@ provider "aws" {
| --- | --- | --- |
| `AI_SBX_AGENT` | `codex` | `--agent` |
| `AI_SBX_MODE` | `clone` | `--clone` / `--direct` |
| `AI_SBX_BRANCH` | `ai-sbx` | `--branch` |
| `AI_SBX_TOKEN_DAYS` | `30` | token expiry pre-filled on the form (1–366, or `none`) |
## AWS profile naming
@@ -285,7 +294,7 @@ Variants such as `_readonly`, `-ro`, and `-read-only` are **not** stripped.
~/.config/ai-sbx/repos/<digest>/config mode 600, no secrets
```
Holds repository identity, sandbox name, agent, mode, branch, and the approved host
Holds repository identity, sandbox name, agent, mode, and the approved host
profile names — no secrets. The GitHub token lives in the `sbx` secret store; AWS
credentials exist only inside the sandbox and only until they expire.
tasks/ai/sbx
+9 -23
View File
@@ -5,7 +5,6 @@ PROGRAM="ai:sbx"
CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/ai-sbx"
DEFAULT_AGENT="${AI_SBX_AGENT:-codex}"
DEFAULT_MODE="${AI_SBX_MODE:-clone}"
DEFAULT_BRANCH="${AI_SBX_BRANCH:-ai-sbx}"
DEFAULT_TOKEN_DAYS="${AI_SBX_TOKEN_DAYS:-30}"
# GitHub accepts these as query parameters on the token creation form. A write
@@ -51,9 +50,10 @@ Setup options:
written into the sandbox.
--agent NAME Sandbox agent. Default: codex
--direct Mount the host working tree read-write.
--clone Give the agent a Git worktree on its own
branch. This is the default.
--branch NAME Branch used by --clone. Default: ai-sbx
--clone Give the agent a private in-container clone
of the repository, mounted read-only.
Its commits reach the host through the
sandbox-<name> git remote. This is the default.
--replace Replace the existing sandbox.
Examples:
@@ -289,7 +289,6 @@ load_config() {
[[ -n "${CONFIG_AGENT:-}" ]] ||
die "Agent is missing from $REPO_CONFIG_FILE"
CONFIG_BRANCH="${CONFIG_BRANCH:-$DEFAULT_BRANCH}"
declare -p CONFIG_AWS_PROFILES >/dev/null 2>&1 ||
CONFIG_AWS_PROFILES=()
@@ -298,8 +297,7 @@ load_config() {
save_config() {
local agent="$1"
local mode="$2"
local branch="$3"
shift 3
shift 2
local -a profiles=("$@")
mkdir -p "$REPO_CONFIG_DIR"
@@ -310,7 +308,6 @@ save_config() {
printf 'CONFIG_SANDBOX=%q\n' "$SANDBOX_NAME"
printf 'CONFIG_AGENT=%q\n' "$agent"
printf 'CONFIG_MODE=%q\n' "$mode"
printf 'CONFIG_BRANCH=%q\n' "$branch"
printf 'CONFIG_AWS_PROFILES=('
local profile
@@ -514,10 +511,10 @@ create_sandbox() {
--name "$SANDBOX_NAME"
)
# Clone mode gives the agent a Git worktree on its own branch, so its
# commits never land on whatever the host has checked out.
# Clone mode gives the agent its own in-container clone, so its commits
# never land on whatever the host has checked out.
if [[ "$CONFIG_MODE" == "clone" ]]; then
create_args+=(--branch "$CONFIG_BRANCH")
create_args+=(--clone)
fi
create_args+=(
@@ -531,7 +528,6 @@ create_sandbox() {
setup_command() {
local agent="$DEFAULT_AGENT"
local mode="$DEFAULT_MODE"
local branch="$DEFAULT_BRANCH"
local replace=false
local -a aws_profiles=()
@@ -551,11 +547,6 @@ setup_command() {
mode="clone"
shift
;;
--branch)
(($# >= 2)) || die "--branch requires a value"
branch="$2"
shift 2
;;
--direct)
mode="direct"
shift
@@ -581,7 +572,7 @@ setup_command() {
validate_aws_profile "$profile"
done
save_config "$agent" "$mode" "$branch" "${aws_profiles[@]}"
save_config "$agent" "$mode" "${aws_profiles[@]}"
if sandbox_exists; then
if [[ "$replace" == true ]]; then
@@ -610,7 +601,6 @@ Repository: $REPOSITORY
Sandbox: $SANDBOX_NAME
Agent: $agent
Mode: $mode
Branch: $branch
Run it with:
@@ -666,10 +656,6 @@ status_command() {
printf 'Agent: %s\n' "$CONFIG_AGENT"
printf 'Mode: %s\n' "$CONFIG_MODE"
if [[ "$CONFIG_MODE" == "clone" ]]; then
printf 'Branch: %s\n' "$CONFIG_BRANCH"
fi
printf 'Token days: %s\n' "$DEFAULT_TOKEN_DAYS"
printf 'AWS profiles (host -> sandbox):\n'