docker/sbx-kit-kiro repository overview

⁠kiro

A standalone workload kit (kind: workload, schemaVersion: "3") for Kiro CLI⁠, AWS's agentic coding CLI. The kit runs kiro chat --trust-all-tools as the entrypoint, registers the sandbox MCP gateway, and authenticates through Kiro's interactive device flow.

Kiro was previously a built-in sbx agent, run as sbx run kiro. This kit replaces that, and is backed by a base image built from the kiro.dockerfile⁠ in this directory rather than by the docker/sandbox-templates release train.

The declarations live in kiro.yaml⁠; the recipe beside it is found by the filename-stem convention. To layer Kiro onto a shell base you already have, use ../kiro-mixin⁠ instead.

⁠Prerequisites

A Kiro account. There is no API-key or environment-variable path — Kiro authenticates only via device flow, which needs a browser on your host.

⁠Usage

sbx run "docker.io/docker/sbx-kit-kiro:latest"

Or from a git URL targeting this repo:

sbx run "git+https://github.com/docker/sbx-kits-contrib.git#dir=kiro"

Or with a local clone of this repo:

sbx run ./kiro/

The trailing kiro is required, not redundant: for workload kits, sbx enforces that the agent name matches the name the kit provides.

⁠Authentication

On first launch the entrypoint checks kiro-cli whoami. When you are not yet authenticated it starts the device flow:

1. Kiro prints a URL and a verification code.
2. Open the URL on your host and enter the code.
3. Approve the request.
4. Return to the terminal — Kiro continues automatically.

Auth state is stored in ~/.local/share/kiro-cli/data.sqlite3 inside the sandbox, so it survives restarts of the same sandbox but not recreation.

To re-run the login explicitly:

sbx run ./kiro/ --name <sandbox-name> -- login --use-device-flow

⁠Passing arguments

The entrypoint defaults to chat --trust-all-tools. Flags are appended after the defaults, so -- --resume runs kiro chat --trust-all-tools --resume. A bare word instead replaces the defaults, which is why -- login --use-device-flow works.

⁠Network policy

The network-policy@1 capability covers Kiro's own hosts and the apt sources the base image ships with (needed because the startup hook runs apt-get update, which fails wholesale if any configured source is unreachable).

Kiro needs two hosts, not one: cli.kiro.dev serves the install/update script, which then fetches the versioned binary from prod.download.cli.kiro.dev. Both are listed — the initial install happens at image build time, but kiro-cli reaches them again for version checks and self-update.

v3 policy is phase-scoped: install is open only while lifecycle install hooks run and is closed before the agent starts, and runtime is the agent's steady state. Kiro's three own hosts appear in both, because the install hook runs kiro-cli setup --no-confirm at create and it has not been confirmed from a live run whether that command touches the network — while the runtime need is established. Listing them twice reproduces the old flat list's reachability in each phase rather than guessing which one to starve. The apt hosts are runtime only (startup hooks run at boot, inside the runtime phase), as are the AWS endpoints (the device flow happens when the launcher runs).

⁠MCP

When a gateway is reserved, sandboxd injects MCP_GATEWAY_URL and MCP_SENTINEL_TOKEN_NAME, and the kit's startup hook writes ~/.kiro/settings/mcp.json pointing at the gateway. The sentinel is not a credential — the proxy substitutes the real token per request, keyed by name. The hook is a no-op when MCP is not enabled.

Both variables are listed in the hook's env:, because v3 hook environments are deny-by-default: a hook sees only the names it declares, plus the platform baseline (PATH, HOME, and the handful a shell introduces itself). Without that list the hook would see neither variable, take its no-op branch on every boot, and silently never register the gateway.

⁠Base image

Unlike a kind: mixin kit, which layers onto an existing image, a kind: workload kit's layers are the root filesystem — so its recipe names the image the sandbox boots from. This kit builds and publishes its own, from kiro.dockerfile⁠ and start.sh in this directory.

The image is docker.io/sbx/kiro-image, built on docker/sandbox-templates:shell-docker, so it carries a Docker engine and requests Docker-in-Docker.

The -image suffix distinguishes the base image from the kit itself: the kit itself is published as an OCI artifact at docker.io/docker/sbx-kit-kiro (see Usage⁠ above). The name is derived from the kit directory and enforced repo-wide — see PUBLISHING.md⁠.

There is no flavour suffix and no dockerless variant. The sandbox templates distinguish kiro from kiro-docker because a user picks a template directly, but a kit picks its own image — so the Docker-in-Docker detail never reaches the user, just as sbx run kiro already resolves to the Docker flavour today. And a workload kit's layers are the one root filesystem, so a second image would be unreachable without a second kit to consume it.

⁠Building and publishing

How the image is named, tagged, verified and pushed is the same for every kit in this repo that builds its own image — see PUBLISHING.md⁠ for the pipeline, the tagging scheme, the coordinates, and the Docker Hub OIDC setup. Only the kiro-specific parts are below.

The nightly rebuild earns its keep here in particular: Kiro is installed from its latest channel — there is no supported way to pin it, see Building locally below — so a rebuild is the only way a new Kiro release reaches users of this kit, and nightly picks up every published version rather than a weekly sample. It also catches drift in the floating base image.

⁠Building locally

cd kiro && docker buildx build . -f kiro.yaml --output type=cacheonly

The descriptor is the build target, not the recipe. Its # syntax=docker/sandbox-kit:3 line dispatches the kit frontend, which validates the descriptor, builds kiro.dockerfile as the content by the filename-stem convention, and attaches the published descriptor to the result — so building kiro.dockerfile directly would give you an ordinary image and no kit.

The build needs egress to cli.kiro.dev (install script) and prod.download.cli.kiro.dev (the binary it fetches).

BASE_IMAGE is the only build arg, so the base can be re-pointed or digest-pinned without editing kiro.dockerfile: --build-arg BASE_IMAGE=… accepts a tag or a digest.

There is deliberately no version arg, which makes this kit the exception among the agent kits in this repo — the others pin their tool and publish provides: ["<tool>@<version>"]; kiro's provides: ["kiro"] stays unversioned. The install cannot be pinned:

• The installer's whole option surface is two flags. Its own show_help lists --help, -h and --channel CHANNEL Specify a release channel (default: stable), and parse_args ends in *) error "Unknown option: $1", so an unrecognized spelling is refused rather than quietly accepted.

• It reads no version from the environment. A channel is not a release.

• The paths it builds spell the release as the literal latest:

  local channel_base_url="${BASE_URL}/${CHANNEL}"
  MANIFEST_URL="${channel_base_url}/latest/manifest.json"
  download_url="${channel_base_url}/latest/$filename"
  

  Copy

Bypassing it does not improve matters. Versioned archives do exist — https://prod.download.cli.kiro.dev/stable/<version>/kirocli-x86_64-linux.zip answers 200 for 2.19.0 through 2.22.1 — but no versioned manifest does: stable/<version>/manifest.json and stable/manifest.json both answer 403, and only stable/latest/manifest.json is served, describing the current release alone. A pinned download would therefore have no published checksum once latest moved past it, while the installer used today does verify one. Abandoning the vendor's install path and its integrity check to buy a version string is the wrong trade, and pinning the provides without pinning the install would be worse still — it would assert a release the content may not have.

The cost, stated rather than hidden: SPEC-v3 §9.2 gives an unversioned provide the descriptor's version:, so this kit publishes [email protected] — its own release number wearing Kiro's name. That answers a bare requires: ["kiro"], which is the only constraint honestly answerable here, and it will wrongly satisfy a kiro >= 1.0. Re-check the installer when bumping the kit; the day it grows a version flag, or a versioned manifest appears, this becomes a version arg like the siblings'.