docker/sbx-kit-paperclip repository overview

⁠paperclip

A standalone workload kit (kind: workload, schemaVersion: "3") for Paperclip⁠ — the open-source app for managing AI agents at work: a Node.js server + React UI that orchestrates a team of agents ("if OpenClaw is an employee, Paperclip is the company").

The kit uses a pre-baked sandbox image: Node 22 and the pinned paperclipai package (server, built UI, embedded PostgreSQL binaries) ship inside the image, built on the claude-code template so the claude_local adapter has Claude Code available out of the box. A new sandbox serves the web UI in seconds.

⁠Usage

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

Or from a git URL targeting this repo:

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

sbx ports <sandbox> --publish 3100/tcp   # then open the printed host port

On attach the entrypoint applies the resolved Anthropic auth state (see How auth works⁠) and then runs paperclipai onboard --yes — idempotent: first boot writes config (instance, agent JWT secret, secrets key) under ~/.paperclip and starts the server; later boots just start the server. The kit runs in authenticated mode (upstream's Docker default) with a generated, persisted BETTER_AUTH_SECRET — create your account on first UI visit. (Paperclip's zero-auth local_trusted mode hard-requires a loopback bind, which the sandbox port-forwarder can't reach.)

⁠Published ports

PostgreSQL (distro, not Paperclip's bundled embedded-postgres) stays on loopback :54329 inside the sandbox.

The sandbox runtime publishes the declared port on an ephemeral host port at start time — find it with sbx ports <sandbox-name>. If you'd rather pin the host port to a fixed value, the classic sbx ports <sandbox-name> --publish 3100:3100/tcp still works alongside the declared ephemeral binding.

⁠How auth works

Agent adapters spawn provider CLIs in-container; the Anthropic wiring (a com.docker.sandbox/credential@1 apiKey, with proxyManaged: true) lets the sandbox proxy inject the real key on egress for the claude_local adapter, so the container only ever holds a sentinel. Other provider keys (OpenAI, Gemini, …) can be added as sandbox secrets or configured in the UI.

⁠API key vs Claude subscription (OAuth)

claude_local runs the Claude Code CLI, so the CLI's own precedence decides the wire format — and Anthropic rejects either credential shape sent in the wrong header. An API key goes out as x-api-key; a subscription login goes out as Authorization: Bearer with the OAuth beta headers. The kit declares both credential shapes and the host's credential decides which one materializes:

An API key wins when the host has one. Without the oauth: block a host whose only Anthropic credential is a subscription login would get no usable credential at all: the API-key sentinel would reach Anthropic unswapped and every claude_local run would 401.

The OAuth path needs no translation step, because the file the engine materializes is the store the adapter's own "subscription login" path reads. It holds sentinels, not real tokens; the proxy swaps them on egress to api.anthropic.com and performs the refresh against platform.claude.com when the access token nears expiry.

What the kit has to do is get out of the way. ANTHROPIC_API_KEY is set to the proxy-managed sentinel unconditionally — the injection is declared by the kit, not by whether a credential exists — which would pin the CLI to API-key mode. So paperclip-anthropic-auth.sh runs at every container start and drops the sentinel in the two cases where it is wrong: a subscription login, and no credential at all (otherwise the adapter's environment test reports an invalid key for a credential that never existed). It writes the decision to ~/.paperclip/anthropic-auth.env, which the entrypoint wrapper sources; a ~/.profile hook carries it into sbx exec -- sh -lc '…' shells too.

The discriminator is the materialized credential file, not SBX_CRED_ANTHROPIC_MODE — that variable reports none for a subscription login just as it does for no credential at all, so nothing may key off it.

Do not authenticate from inside the sandbox. A claude /login or claude setup-token run in the container writes a real token into ~/.claude/.credentials.json, which defeats proxyManaged: true: from there it is readable by the agent and by anything the agent runs, and this kit's allowlist includes hosts it could be sent to. Keep credentials host-side.

Telemetry is opted out at the source (PAPERCLIP_TELEMETRY_DISABLED=1); telemetry.paperclip.ing is deliberately not in the kit's com.docker.sandbox/network-policy@1 allow list.

⁠Content

Unlike a kind: mixin kit, which is an overlay that lands on someone else's root filesystem, a kind: workload kit's layers are the root filesystem — so this kit carries the whole environment, built from paperclip.dockerfile⁠ in this directory:

paperclip (the kit's own layers)
└── FROM docker/sandbox-templates:claude-code
    ├── Node 22 (paperclip requires >= 20)
    └── paperclipai @ pinned version   npm global install:
        ├── @paperclipai/server + built React UI
        ├── distro PostgreSQL (not the bundled embedded-postgres, whose
        │   arm64 binaries fail to load under the sandbox microVM's
        │   16KB-page kernel)
        └── /usr/local/bin/paperclipai symlink

There is no longer a separately published docker.io/sbx/paperclip-image for a sandbox.image: field to point at: a v3 Kit is one OCI image carrying both the declarations and the content, published at docker.io/docker/sbx-kit-paperclip (see Usage⁠ above). ../paperclip-mixin⁠ is the same app as an overlay you layer onto a shell base instead — read its README first, because an overlay cannot carry PostgreSQL or the Claude Code CLI.

⁠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. There is no kit-specific build script or workflow; CI builds and publishes this image the same way it does for kiro/copilot.

⁠Building locally

cd paperclip && docker buildx build . -f paperclip.yaml --output type=cacheonly
./scripts/test-kit.sh paperclip

The descriptor is the build target: its # syntax=docker/sandbox-kit:3 line dispatches the kit frontend, which validates the descriptor, builds paperclip.dockerfile as the content and attaches the published descriptor to the result. Building the recipe on its own — docker build -f paperclip/paperclip.dockerfile -t paperclip:local paperclip — gives you the content and no kit, and it also needs PAPERCLIP_VERSION passed by hand, since the descriptor is what supplies the pin.

scripts/test-kit.sh builds the kit into a throwaway OCI layout and judges the result with kit-tck. There is no separate image to build first: the descriptor is the build target, and the frontend validates it on the way.

The paperclipai release is the kit's version arg, declared in paperclip.yaml and handed to the recipe as the PAPERCLIP_VERSION build arg — so it is validated against the calendar-version pattern, baked into the image, and expanded into provides: ["paperclip@…"], which is what stops the provide claiming a release the image does not ship. Override it at install time with --kit-arg version=2026.MDD.P, or for a local build with --build-arg PAPERCLIP_VERSION=2026.MDD.P.

⁠Debugging

sbx exec <sandbox> -- tail -f /home/agent/.paperclip/instances/default/logs/*.log
sbx exec <sandbox> -- curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3100/
sbx exec <sandbox> -- paperclipai doctor

See docs/recipe-prebaked-image-kit.md⁠ for the general pattern this kit follows.