Known gaps
The open items of Spinbox’s security model, from spin’s docs/security/README.md at 51f7e0dea. The numbers are its rules.
What no line keeps yet. Each is a design change, not a patch, which is why it is here.
- A team’s network policy reaches what its admins say. Where an installation sets
team_network_policies, any team’s admin - and every person administers their personal team - can let that team’s workspaces reach any destination past the node drops, whatever the installation’s own policies allow. The setting is the whole control; there is no ceiling a team’s policy is held under. - I12 through a proxy holds as the proxy does. The proxy is asked to connect to the address that was checked, and one that connects elsewhere is the operator’s choice, as the proxy is. The storage endpoint an admin sets is deliberately exempt: an S3 inside the installation’s own network is the normal deployment.
- A name a policy allows is held to what DNS and the client say. An address serving many names
is open to all of them once one is allowed; a rule that checks SNI (
netpolicy.Rule.VerifySNI) narrows that for a client that names the host it wants, and passes a tenant that names an allowed host to reach another behind the same address (domain fronting). Only a brokered rule that injects, whose proxy holds each request’sHostto the name, keeps a tenant to it. The resolver takes upstream only what a policy names (network.Fabric.asks), so a name is a channel only to whoever answers one a policy allows: a wildcard over a domain that strangers can publish under is a way out, by its questions as by its addresses. - Every host writes
layers/. A layer is content-addressed, create-only and locked, and opened only through a manifest its writer signed, so a host can add layers nothing reads - and pay for them - and change none. Under the volumes it writes only its own subtree of each, never the grant or the descriptor (bucketpolicy.For), and nothing there is served without its holder’s signature and grant. A host a volume left keeps that credential for up to a quarter of an hour, which the store cannot end early: it reads the volume as it held it - and a snapshot asked for before the move, which the new holder seals under the version it was asked at - and adds commits and HEADs under its own subtree that no restore takes, each counted as it is passed over and every request in the bucket’s access log (I8). - A key a host was given opens what it sealed until the volume is re-keyed. A volume’s key never turns, and an honest host forgets it when the volume leaves; one running other code keeps it. Revoking a host marks every volume it was granted for a re-key, which runs once the workspace is stopped: until then the layers that key opens are open to whoever holds it, and the re-key deletes the volume’s snapshots with it, being exactly what that key opens.
- A move between a detach and its attach is the old host’s. A grant is made over the HEAD the
volume’s history reaches when the control plane places it, so what the host it left wrote in
that window - seconds, when the move is one
RecoverWorkspace- is history the new holder starts from. - I14 and I15 in a development installation. A developer’s runner is not root: its QEMU and its qemu-img run as itself, with nothing of root’s to keep from them, and a kernel without core scheduling runs machines side by side on one core’s siblings. Such an installation places on any host; only a production one requires what each host says it keeps.
- What a host says it keeps is the host’s word. On AWS that is the word of a runner build the host proved it booted (I13), on the image whose kernel has all three; a self-hosted host’s is believed as its registration token is.
- I16 tells a store’s clients apart by port, not by what each asks. Neither Quickwit nor the metric store’s writes take a key, so the kernel refuses a connection by the caller’s group, and a client let through a port has all of it: the collector reaches the whole of Quickwit’s gRPC, which carries Quickwit’s own services beside the logs it is sent, and Grafana can write samples as well as read them. Root on the control plane’s machine can drop the table; that root is the installation already.
- Which release of the CLI a person runs. A CLI behind its installation replaces itself with
the release the control plane names (
internal/selfupdate), andspin updatedoes so for any release it names, an older one included. Only what the release workflow signed and attested of that very version is installed, checked offline before it replaces anything, so a control plane cannot have a CLI run a binary of its own. It can havespin updateinstall an older signed one, with whatever that one got wrong; the automatic update only ever moves forward. - A workspace’s owner sees who opens its pages. Signing in to a workspace’s host gives that host a session for that workspace alone, which the API refuses, and a page on the host can read how it got there. So its owner can act as the visitor on their own workspace and nowhere else, and learns that the person visited.
- Workspaces are one site to a browser unless
ws.<domain>is on the public suffix list. A dashboard cookie is host-only and the API refuses it from another origin, and the proxy asks as nobody for another workspace’s page, byOrigin,Sec-Fetch-SiteandReferer. A link followed from another workspace still carries the visitor’s session on the workspace it opens, as a top-level navigation has to:SameSite=Laxsends it on a link from any site, so that listing does not change it. What the listing does change is what a tenant’s page can do with cookies of its own: until then it can set one withDomain=<domain>, orDomain=ws.<domain>, which reaches the dashboard’s host and every other workspace. A browser that sends noSec-Fetch-Siteis not told apart from a tool on a plainGET. Sessions issued through a workspace before this release can reach the whole account until they expire. - I17 and I18 hold against a stolen session, not against the tenant, nor a guest. Root in a guest is anybody let in - its owner and each guest alike: it can rewrite the drop-in. Sealing keeps everyone else out; it does not keep the people let in from the machine they were let into.
- A browser’s session key logs in for twelve hours with nobody asked. Code running on the
dashboard’s origin, or malware in the browser, uses the key its passkey enrolled
without a prompt until it runs out (
sshkeyserver.SessionKeyLife); deleting it from the person’s keys ends it at the next session. - A person’s first passkey is their session’s to register. A stolen session registers one for
somebody who has none yet, and adds keys and lets guests in with it. It holds for anybody who
registered one before: past the first, a passkey adds another (
RegisterPasskey). A person who lost every passkey is cleared by an admin and registers again from their GitHub login, so an admin’s session can do the same for anybody. - A synced passkey is as safe as what syncs it. Whoever gets into a person’s Apple or Google account, or their password manager, holds their passkey and asserts as them. It is a third party outside the control plane and the operator, accepted so that a person has one passkey rather than one per browser. A security key stays on the device.
- The dashboard’s code is the terminal’s. The terminal runs in the dashboard’s page, served by the control plane with the rest of the bundle, so a control plane running other code reads and types into every terminal its people open, as root in the guest, and uses their session keys. It holds those keys’ twelve hours anyway; a page on an origin of its own bought nothing once a session key, not a signature per document, let a person in.
- What is typed in an overlaid Agent frame reaches T3 Code. The dashboard frames the agent’s page and can lay words over it: typing goes to the client, as the agent’s user.
- A guest is let into the guest by the same certificate as the owner. The control plane
decides who logs in, not what a login may do: a guest is root, and changes nothing the control plane holds -
middleware.guestMay- but can change the machine itself. Sharing a workspace is trusting the guest with it. - A person’s agent CLI credentials are one, for all their workspaces. Claude Code’s and Codex’s
credentials files are kept as the person’s (
agent_credentials, sealed) and handed to every workspace they own, so one login signs in each (supervisorserver.pushCredentials,agentcredentials.Keeper). So whoever runs code in one of them - the agent itself, led there by what it read, or a dependency the workspace installed - holds the provider token of every one, and a change it sends replaces the copy they all use, until the person logs out or revokes it at the provider. Only a workspace its owner’s alone is handed any or has one taken from it (workspaces.owners_alone,supervisorserver.holdsCredentials): made of an image, of a snapshot or clone of a workspace of theirs that is so too, or of the prebuild of a project they may open, mounting an agent’s home only such workspaces mounted (agent_volumes.owners_alone), never naming a guest, and never a prebuild’s build. A prebuild’s disk holds what the repository’s code did in its build, which is no more than that code does as root in a workspace opened straight from the repository; the build, which nobody watches and every member opens, is handed nothing. A copy of another person’s snapshot, and every workspace and home made before the mark was kept, get none, and the person signs in there as before. Its supervisor takes out what it held once the control plane withholds it, as a guest is let in (agentcredentials.Keeper.Withhold). What does not leave with the files: a guest let in while the agent was signed in may read what the machine kept of them - freed blocks of the agent’s home, and the memory of a CLI the agent’s stopped server did not end. - A workspace reaches the client API through its host. The host’s relay (
internal/runner/cprelay) carriesspin.v1from the guest, whatever the workspace’s network may reach, on the caller’s own credential and never the host’s, with nothing the host says of a stream: so an agent in anofflineworkspace drives others, and the control plane’s address and CA stay out of the guest. What it opens to a tenant is the API anyone on the network has, through a host, and the exchange (I26); a host’s few connections per machine bound how much. - A guest trusts the egress root its control plane hands it. Every registration hands the
installation’s root, and the guest puts it in its trust store (
handler.InstallEgressCA): a root there reads what the guest’s TLS clients send through a proxy that holds it. Only the egress proxy of the host the workspace runs on is issued under it, and that host is one the control plane can open a root shell on anyway; nothing an owner says narrows it. - Logs leave as the installation says. A guest’s journal and a machine’s console are collected
while the installation’s policy collects them (
LogCollection,HostPolicy.collect_console), and the agent’s thread index is reported always: titles, paths and times, never a message. An owner has no say over it, so an installation admin’s session - stolen or not - reads every collected journal: a decision, not an oversight. - A key deleted, or a guest taken out, keeps the sessions already open. The next session is
refused, and a certificate already made holds its five minutes (
sshca.DefaultCertValidity); sshd ends no session a certificate opened when the certificate expires. - The agent’s client is trusted as the proxy serves it.
agents.<domain>, which the dashboard frames, is the release’s signed files on the proxy image’s verity root, under a Caddyfile spin-boot carries, so the control plane does not change it; a proxy running other code serves any code in that frame. - The published key set is the identity key’s first version and the keys the proxy’s document
lists, as the proxy serves it.
id.<domain>is written on the proxy from the first version ofidentity/issuer.json, each key underidentity/keys/whose kid the document Terraform writes lists (identity.KeySet), and each one’s CA, signed by its key; so a key the control plane makes and the apply does not list publishes nothing, and the control plane’s exchange verifies against the same set. A proxy running other code publishes any key set; an apply listing a kid the control plane printed trusts what the control plane made then. A self-hosted installation serves none. - I19 holds the identity key to the image a host booted, not to the host. Every host shares the key it signs with, the newest listed: a runner running other code signs for any subject. A self-hosted installation has no key service, and its control plane keeps the key it grants.
What this does not protect
Section titled “What this does not protect”The control plane holds what it needs to serve people. What follows is what it could do with that if someone ran their own code with its permissions. This is an assumption the design is checked against, not a finding: no way of doing that is known, and no outside test has looked for one yet. Below, “it” is such a control plane.
- The storage layer holds nothing against it. The control plane mints every credential and grants every key, so it could clone any snapshot to a workspace of its own on an attested runner.
- It can let anybody into any workspace. It keeps every workspace’s CA, sealed under its own key, and decides whose key a certificate is over: who logs in is its word (ADR-0031). A passkey holds a stolen session to the person; it holds nothing against this.
- I18 and I19 do not hold against a control plane that uses a host. It can open a root shell
on any host (
OpenHostShellCommand): both keys are its own, and the host checks only the time and the keys’ shape. Emptying the host first, the approval and the recording are the control plane’s own code, which other code would skip. Root on a host reads and writes every workspace on it, memory included, and is answered by the key service as that host is. Holding the shell to a key the control plane does not have is not built: a lost key would leave a host with no way in during an incident, and it would only narrow what is described here (CLAUDE.md). - It can open every connected person’s forge tokens. The control plane holds the access and refresh tokens sealed under its own key, and with them could act on the forge directly, as each person, within the app’s permissions (contents and pull requests, read and write) and the repositories that person reaches where the app is installed. Nothing on a host stands in the way, and the app installed on selected repositories and the forge’s branch rules are the only limit. A refresh token it copied can outlive it until the person’s authorization ends.
- It can open every person’s agent CLI credentials. Their Claude Code and Codex tokens are
sealed under its key (
agent_credentials), as the forge’s are, and with them it could use each person’s provider account directly, until the person logs out or revokes them at the provider. - Machines the control plane’s role starts. Auto Scaling asks that role for
ec2:RunInstanceson the runners’ launch template, and under that grant a call that names the template and other user data starts the machine with the other user data, tried on AWS on 2026-11-04; holding the instance toec2:IsLaunchTemplateResourcedid not stop it. User data is not measured, so such a machine might attest as a runner under a document the control plane chose; whether it does has not been tried. It is told, not stopped: a rule emailssecurity_emailswithin minutes of the call. - It decides what a guest applies of its owner’s. The settings are what it keeps (I18), and whether a workspace is its owner’s alone is its word, which withholds their own settings where it says no and nothing where it says yes.
- I21 holds against a confused deputy, not this. The control plane tags the
session, so other code in it could tag it with any team, and it holds every value it reads in the
clear, as it does a sealed one. The tag is only as good as who may tag a secret: a principal of
the account that can tag one
spin-team-idhands it to that team. Its role takes the control plane’s credentials from anywhere while they last, so a reference is read off the machine where a sealed value is not: that needs the attested key. - The domain an identity is named under is the control plane’s word. It comes with the host’s policy, and it can change it - which a relying party refuses, since the issuer it names publishes another key set: denial, not a widening. Who an identity is given for is the installation’s list of audiences alone, which the control plane writes. A member of a parent team is no member of a team below it: a team’s members are its own.
Generated by task reference from spin/docs/security/README.md at 51f7e0dea.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

