SuCoder Documentation
SuCoder
Unix-user sandboxing for AI coding agents. One account per agent, filesystem-enforced boundaries, plain git.
Getting Started
- Full Documentation — project overview, quick start, configuration, and command reference.
- Host Environment Setup — checklist for provisioning a new machine.
- Remote & Connection FAQ — tunnels, reattaching to sessions, TRAMP, and managing compute cost on SLURM-backed targets.
Architecture
- Skills Architecture — agent-agnostic discovery, write control, and compliance auditing.
- Standing Shadow Values for LLM Use — approximate hourly resource prices for human task timing and SuCoder delegation.
- LLM Usage Collection — practical design for quota, model-tagged usage, price/supply histories and coverage for rate estimation.
- LLM Usage Collection: Model Identification Review — red-team findings and design response on Fable/Opus attribution and the minimum model-aware pilot.
- LLM Usage Implementation Charter — Claude/Codex scope and acceptance criteria for extending the existing llm-accounting project.
- Always-on Control Plane — an EC2 instance, vantage, as launcher and canonical host and the laptop as a mosh client: the decision, the build record, the minimal-secrets posture, and the procedure that moves live sessions.
- Attention — design and step-1 prototype: Claude hooks write per-session status records, and
sucoder attentionlists the sessions waiting on the human first, feeds a tmux status line, and notifies a phone; a coordinator agent comes later. - tunnel keep — design: a supervisor that re-warms the gateway mux, asks for an OTP only when the certificate cannot, and logs every mux lifetime.
- Persistent Presence — a standing condo slice on a shared HTC partition: renew, turnover, and handoff.
- Local-disk Tiering — design note: disposable working tree on node-local disk, git as the sync, WIP snapshots (spike-verified).
- Codex Remote Control — isolated server identities, owned pairing, and simultaneous-node validation.
- Codex Local State — proposed SQLite placement, durable recovery, lifecycle handoff, and Savio validation gates.
- Codex Local State: Pilot Runbook — the Slice 4 pilot from a laptop: config, the step-by-step turnover, what to bring back, what refusals mean.
- Codex Local State: Slice 0 Spike — measured on Savio with Codex 0.162.1: what follows
sqlite_home, what stays inCODEX_HOME, the rollout dependency on restore, abrupt-stop captures, queue and goal replay, two writers, and local-versus-Lustre latency. - Happier as a Common Harness — research note: what Happier's one-CLI-over-every-agent surface would buy SuCoder, the shared-home machine-identity and daemon mechanics read from its source, and a Claude-first trial plan (issue 58).
- Happier: Disposable Claude Pilot — pinned CLI, allocation-scoped adapter, browser/message acceptance checks, and release evidence.
Examples
- Org Authoring Playground — demonstrates Org skills for humans and agents (view source on GitHub; requires
citeprocfor local HTML export).