Spunto Lite

A local dev-environment control plane — the "Build" pillar of Spunto, collapsed into a single container you run on your own machine. Create projects (devcontainer-style specs), launch Docker workers with VS Code in the browser (code-server), a persistent terminal, lifecycle hooks (postCreate/postStart), secrets, and your own SSH key injected so git push just works.

No cloud, no multi-tenant, no remote agents: one Next.js process talking straight to your local Docker socket.

Quick start

cp .env.example .env          # optional — sane defaults work out of the box
docker compose up -d --build  # or ./start.sh, which does the same

Or run the pre-built image straight from GHCR:

docker run -d --name spunto-lite -p 80:80 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME/.ssh:/host-ssh:ro" \
  -v spunto-lite-ssh-agent:/run/spunto-ssh-agent \
  -v spunto-lite-data:/app/data \
  ghcr.io/spuntodotnet/spunto-lite:latest

Then open http://localhost. Workers appear at http://worker-<id>.localhost (VS Code) and http://worker-<id>-<port>.localhost (forwarded ports); shared services at http://svc-<slug>.localhost. *.localhost resolves to 127.0.0.1 automatically in Chrome/Edge/Firefox.

That works from your browser. From a container — browser-remote, the e2e runner — localhost is the container itself, so the same stack also answers on a real wildcard domain (*.local.spunto.net) served by a bundled CoreDNS, over HTTPS with a local mkcert certificate. See docs/local-domain.md.

How it works

• One Next.js app (App Router) served by a small custom Node server (server.ts) that also reverse-proxies worker subdomains and hosts the terminal WebSocket.
• dockerode → /var/run/docker.sock: workers are sibling containers on the host daemon — for their lifecycle only (create, start, stop, remove, build).
• Each worker carries an agent — the very one a Spunto Cloud sandbox runs, from @spunto/build. The container's main process is its bootstrap; the agent dials back over a WebSocket and carries everything inside the box: commands, terminals, listening ports, the setup's progress. No docker exec, no Node download (Lite lends its own through a read-only volume). Workers created by an older Lite keep docker exec until rebuilt. See docs/agent.md.
• SQLite (via Drizzle) for projects/workers/secrets, in a Docker volume.
• ~/.ssh mounted read-only and injected into each worker — it is both the git identity and the only clone credential. A repository is declared as a clone URL, never as a host plus an owner/repo: there is no forge integration here, no app to install and no token to mint, so any host your key reaches works the same way — a hosted forge, a self-hosted GitLab, a bare repo on a NAS. Authorize the key once, wherever, and every project clones and pushes. A key protected by a passphrase works too, through an SSH agent — see SSH keys with a passphrase.
• @spunto/build for everything the two Spuntos have to agree on: the image recipe and the shell it generates, the build-log protocol, the extension-registry clients, the Docker naming scheme and the portable project format. Same idea as @spunto/design-system, one layer down — that one owns what the products look like, this one what they agree on. A workspace image is your base image plus two devcontainer features, common-utils then , before the features the project declares; images are tagged , so a release that changes what goes into an image rebuilds it instead of leaving your workers on the old one. What the two Spuntos share today and what they still duplicate — project creation, worker listing, the status vocabularies — is written down in .

Agents

Delegate work to a coding agent the way Spunto Cloud does: New task on a project (or Agents in the sidebar), write what you want, and a worker from the project's pool gets its own branch and an agent session — Claude Code or Codex, picked per task. You watch it work live, answer it or interrupt it, read the diff from the machine itself, open a shell on it from the Terminal tab, then Accept or Drop. Every conversation of every project is on the Agents page, grouped by what needs you.

Harnesses are agent apps, as in Spunto Cloud: a project switches on the ones its tasks may use (a new project starts with Claude Code), each puts its official SDK in the project's image, and each task picks one — with that app's models and its own parameters (effort, reasoning…). All it needs is the app's key as a secret (ANTHROPIC_API_KEY, OPENAI_API_KEY). The harnesses, the default models, what Accept and Drop run and whether the worker stays up during review are the project's Delegated work settings. The screens come from @spunto/design-system/tasks and the session parsing from @spunto/build/agent-stream, shared with Spunto Cloud. Details, and what differs from the Cloud version: docs/taches.md.

MCP servers (Notion, Linear…) are declared once in Settings → MCP servers, connected in OAuth from there, and given to each project's tasks through Lite's gateway — the worker never holds the vendor's token: docs/serveurs-mcp.md.

Shared volumes

Each worker gets its own mp-worker-<id>-workspace volume on /workspace. Two workers of the same project therefore re-download their dependencies and regenerate their artifacts separately. A project can declare shared volumes in the Shared volumes section of the project form (inside Advanced options) to stop that: a name and a mount path, e.g. pnpm-store → /home/vscode/.local/share/pnpm/store.

• Backed by a named Docker volume mp-proj-<projectId>-<name>, created on demand by the first worker that needs it and reused by every later one.
• Mounted in every worker of the project, alongside its private /workspace.
• Lifecycle: survives deleting a worker and rebuilding one (unlike mp-worker-* volumes, which a delete wipes). It's destroyed only with the project, behind an explicit confirmation in the delete dialog — your data lives in there.
• Visible on the Resources page with kind: "shared", its owning project, its size and how many workspaces mount it.
• The declaration is versioned like the rest of the project config, so restoring a version and exporting/importing a project carry it. Only the declaration travels in an export — never the data.
• /workspace and its sub-paths are refused as mount points: they'd shadow the worker's own volume and break the setup script's idempotent clone. Same for /var/lib/docker, /var/lib/containerd and the kernel filesystems.

Concurrency is not managed. Several workers write into the same volume at the same time and nothing locks. That's fine for what this is for — package caches, datasets, fixtures, build artifacts, read-mostly data. It is not a place for a shared SQLite database, a lockfile two processes rewrite, or anything needing a single writer.

SSH keys with a passphrase

A key without passphrase is copied into each worker and used as is. A key with a passphrase is copied too — still encrypted — but ssh can't ask for its passphrase in a worker (no terminal behind git clone, nor behind a git push run by an agent), so it signs through an SSH agent instead. Settings marks such a key with a passphrase badge, and a banner says so on every page as long as nothing can use it. Two ways to give it an agent:

1. Unlock it in Settings (works everywhere, nothing to configure). Type the passphrase once: Spunto Lite loads the key into its own ssh-agent and drops the passphrase — it is never written to disk, never stored in the database, never logged. The decrypted key lives only in that agent's memory, so after a restart of Spunto Lite the key is locked again and the banner asks for the passphrase. Lock forgets it at once.

2. Forward your host's agent, if you already ssh-add the key on your machine (keychain, 1Password, gpg-agent…). Mount it into the Spunto Lite container at /run/host-services/ssh-auth.sock — uncomment the matching line of docker-compose.yml, or add to docker run:

   # macOS — Docker Desktop's own forwarded agent (the launchd socket in $SSH_AUTH_SOCK
   # can't be bind-mounted from macOS):
   -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock
   # Linux:
   -v "$SSH_AUTH_SOCK:/run/host-services/ssh-auth.sock"
   

   On Linux the path of $SSH_AUTH_SOCK changes with each login session: recreate the container after logging in again. Settings shows whether the host agent holds the selected key. A key unlocked in Settings takes precedence over the host agent.

How it reaches the workers: every worker mounts the spunto-lite-ssh-agent volume and gets SSH_AUTH_SOCK=/run/spunto-ssh-agent/agent.sock, a socket served by Spunto Lite that forwards to whichever agent holds the key (a named volume because Docker Desktop can't carry a Unix socket through a bind-mounted host directory). The socket is always there, so unlocking a key reaches the workers that are already running — except those created before this volume existed, which need a Rebuild. Without the volume mounted on the Spunto Lite container, Settings says so: keys without a passphrase keep working, keys with one don't.

Like any agent forwarding, whatever runs in a worker can ask the agent to sign while the key is unlocked — it can't read the key itself.

Override the paths with SSH_AGENT_DIR (default /run/spunto-ssh-agent) and HOST_SSH_AUTH_SOCK (default /run/host-services/ssh-auth.sock).

Requirements

• Docker with the socket at /var/run/docker.sock
• Port 80 free on the host (override with PORT, at the cost of :port in URLs)

Development

npm install
npm run db:generate     # regenerate SQL migrations after schema changes
PORT=3900 npm run dev    # run the control plane directly (needs a reachable Docker socket)

Testing

End-to-end tests live in e2e/ — a Playwright suite split into an HTTP-only API project and a browser project (driving browser-remote's Chrome over CDP, or a local Chromium). No auth to set up (the control plane is open); SQLite means no DB service either.

# fast API suite — boot the app, then run the `api` project
PORT=3900 DATA_DIR=./.e2e-data npm run dev
cd e2e && npm install && E2E_BASE_URL=http://localhost:3900 npm run test:api

CI runs the API suite on every PR (.github/workflows/e2e-api.yml). See e2e/README.md for the browser suite, the compose test profile (browser-remote/CDP), and the opt-in worker-lifecycle project.

License

MIT — fork it, run it commercially, vendor pieces of it; just keep the copyright notice.