Agent sessions and sandboxes
The pattern
Section titled “The pattern”A coding agent works freely in a separate place, and the one step that changes production goes through an approval. For that to hold, the separate place must really be separate: its own credentials, no production secrets, no network path to production, and disposable.
Sessions
Section titled “Sessions”A trigger (a webhook, a node signal, a schedule) or a human starts an agent session. The core decides when, whether and with which rights; the driver only starts, polls and stops it.
| Where the session runs | Driver | How the session proves itself |
|---|---|---|
| a pod in kubernetes-sigs/agent-sandbox on k3s | agent_sandbox | a projected ServiceAccount token, checked by TokenReview; bound to namespace, ServiceAccount and pod |
| a Forgejo Actions job | forgejo_actions | the job’s OIDC ID token (ES256), bound to repository and run |
| your machine, next to you | vaicoa-run pair | a comparison code you confirm on your phone |
- The session gets no token, but a run ticket: usable once, valid for at most ten minutes. Redeeming it gives a run certificate that ends with the run’s budget.
- The sandbox may reach only the core’s door and the model (a NetworkPolicy). On Forgejo runners the driver cannot restrict egress (limitations).
- Every run has a budget: tokens, runs per day, proposals per run, a timeout.
- A run carries at most the rights of the user it acts for, capped at level
device, and only the actions in its trigger’smayProposelist.
vaicoa-run
Section titled “vaicoa-run”The agent never talks to the core directly. vaicoa-run sits in the session with two faces: a CLI and a local MCP
server over stdio, for Claude Code, OpenCode or any MCP client. Its tools are the allowed actions from the verified
signed catalog, plus:
| Tool | What it does |
|---|---|
actions | what this run may propose, and for each action whether it runs at once or needs approval, and from whom |
explain | a dry run: what the core would decide for exactly these parameters, without creating an op |
propose | answers done, queued, pending_approval (with what is missing) or refused (with the reason) |
status, wait | follow an op, within the run’s budget |
report | send results or questions back to the human |
A skill file tells the agent how to behave: explain first, propose once, keep working while an approval is pending, do
not repeat a proposal. Reviewer sessions get review-next and review-decide instead and never see the proposer’s
claims. A run never has both roles.
Twins: an idea, not built
Section titled “Twins: an idea, not built”The idea behind the name: an agent gets a copy of an environment (with seed data or a masked copy), tries a change there and presents the result for review. This is not built in Vaicoa Core. What exists is the session in a sandbox or CI job, changes delivered as a pull request (GitOps flow), and plans that show before and after.