sbx/shell-kit repository overview

⁠shell

A sandbox with no agent installed, launched as a login shell: bash, git, apt, the Docker CLI with compose and buildx, curl, gh, jq, make, build tools, Python 3, Node with npm, Go, a headless JDK and uv, built from Ubuntu by the kit's own recipe. No Docker engine: for one, use the shell-docker kit, the same image with containerd and dockerd on top.

This kit is the shell agent built into sbx, extracted as a kit. Its credentials and its launch command are the built-in's, so a sandbox created from the kit behaves as sbx run shell does, with three differences: it reaches only the hosts it declares below rather than whatever the host policy grants, it refreshes the apt index when its image is built rather than on every boot, and it ships no Docker engine (the shell-docker kit does).

⁠Usage

A kind: sandbox kit is named as the positional, with no --kit flag and no agent argument:

sbx run docker.io/sbx/shell-kit:latest

Or from a git URL targeting this repo:

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

Or from a local clone:

sbx run ./shell/

shell still names a built-in agent, and that limits how this kit can be run today. sbx run --kit <this kit> shell never works: the positional resolves to the built-in and the kit is rejected for being a sandbox where a mixin was expected. Released sbx builds also refuse the forms above with agent "shell" is already registered; on those, run a copy of the kit under another name.

⁠Docker

The image carries the Docker CLI, compose and buildx, but no engine, so docker commands need a daemon to talk to. For Docker-in-Docker use the shell-docker kit, which builds FROM this image and adds containerd and dockerd:

sbx run docker.io/sbx/shell-docker-kit:latest

⁠Provider credentials

Eight services, all optional. Bind the ones you use on the host and leave the rest; nothing here needs a key to start.

sbx secret set openai

The real values stay on the host. Seven of the eight are proxy-managed, so their variables carry a sentinel in the container and the proxy swaps the real value in at request time. GH_TOKEN is declared without being populated: nothing in the container holds the token, and gh and git see the variable unset. On github.com the token is sent as Basic auth with the username x-access-token, because git's smart-HTTP transport rejects Bearer; the other GitHub hosts take Bearer.

⁠Installing packages

apt-get install works straight away. The image is built with the apt index already refreshed, so there is no apt-get update to run first and nothing reaching the network at boot to do it for you. CI rebuilds the image nightly, so a long-lived pull can still meet a superseded version; apt says so plainly and sudo apt-get update fixes it.

⁠Network

The allow list is the eighteen hosts above plus the five apt sources the base ships: archive.ubuntu.com, security.ubuntu.com, ports.ubuntu.com, download.docker.com and cli.github.com. These sources support package installs and subsequent index refreshes.

This is the one deliberate addition to the spec over the built-in agent, which declares no allow list and inherits whatever the host policy grants. A kit cannot do that: it reaches exactly what it declares, so a credential whose host is not listed could never be used.

Deliberately absent: the language package registries (npm, PyPI, the Go module proxy) and the Docker registry hosts docker pull needs (registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com). The built-in agent declares no allow list at all, so the list above is already a deviation, and it stays at the minimum that makes this kit's own declarations work. Under a permissive host policy none of this restricts you; under deny-all, widen the policy for that sandbox or compose a kit that declares what it needs.

⁠Launch command

No entrypoint, which is the point: a sandbox kit that names no binary gets a shell. command: ["-l"] makes it a login shell, so ~/.bash_profile runs and sources ~/.bashrc, where the image sets the prompt.

⁠Image

docker.io/sbx/shell-image, built from the Dockerfile beside the spec and rebuilt nightly by CI, for linux/amd64 and linux/arm64. The recipe builds the whole image from Ubuntu: the toolchain (git, gh, jq, make, build tools, Node with npm, Python 3 with pip, Go, a headless JDK, uv), the non-root agent user with passwordless sudo, and the Docker CLI with compose and buildx. No agent and no Docker engine are installed. Owning the recipe is what lets this image become the base other kits build on; docker.io/sbx/shell-docker-image is the first, adding the engine.