WIP: docs: design for an agent workspace pod #741

Draft

tobru wants to merge 3 commits from docs/agent-workspace into main

tobru commented

2026-10-31 18:56:05 +00:00

Owner

Design for a personal agent workspace that runs in a Kubernetes pod.

What it is

One pod holds the repo, one git worktree per feature branch, one Django dev server
and one database per worktree, and pi-web as the browser UI. You reach it over
NetBird with a password. An agent works in two modes: you steer it in the browser,
or a Forgejo issue starts an unattended run that pushes a branch and opens an MR.

Decisions

One pod with many worktrees, not one pod per branch.
Single user. A teammate deploys their own copy.
Synthetic data only. No staging or production rows reach a pod.
The agent stops at the MR. Forgejo permissions enforce it.
8 hour run budget, no cost cap, parallel runs allowed.
PostgreSQL runs in the pod on emptyDir, rebuilt on pod start.
NetBird client in netstack mode with NB_ENABLE_NETSTACK_LOCAL_FORWARDING, so the
pod needs no TUN device and no privileges.

Open at build time

The minimum NetBird client version with that flag, and the exact content of the
synthetic seed. Both are listed in the document under "Left to the builder".

Not in this iteration

A fake Kubernetes API, so the instance pages stop rendering degraded.

Design for a personal agent workspace that runs in a Kubernetes pod. ## What it is One pod holds the repo, one git worktree per feature branch, one Django dev server and one database per worktree, and pi-web as the browser UI. You reach it over NetBird with a password. An agent works in two modes: you steer it in the browser, or a Forgejo issue starts an unattended run that pushes a branch and opens an MR. ## Decisions - One pod with many worktrees, not one pod per branch. - Single user. A teammate deploys their own copy. - Synthetic data only. No staging or production rows reach a pod. - The agent stops at the MR. Forgejo permissions enforce it. - 8 hour run budget, no cost cap, parallel runs allowed. - PostgreSQL runs in the pod on `emptyDir`, rebuilt on pod start. - NetBird client in netstack mode with `NB_ENABLE_NETSTACK_LOCAL_FORWARDING`, so the pod needs no TUN device and no privileges. ## Open at build time The minimum NetBird client version with that flag, and the exact content of the synthetic seed. Both are listed in the document under "Left to the builder". ## Not in this iteration A fake Kubernetes API, so the instance pages stop rendering degraded.

tobru added 1 commit

2026-10-31 18:56:05 +00:00

docs: design for an agent workspace pod 2eae123ef8

Run pi in a Kubernetes pod as a personal agent workspace: one pod, one
worktree per branch, a dev server and database per worktree, pi-web in
the browser, reachable over NetBird without any container privileges.

Records the decisions from the design session: single user, synthetic
data only, the agent stops at the MR, 8 hour run budget, parallel runs,
Postgres in the pod on emptyDir, and NetBird netstack with local
forwarding for inbound access.

🤖 Generated with Pi (https://github.com/earendil-works/pi) using deepseek-v4.1-flash

tobru added 1 commit

2026-10-31 20:08:56 +00:00

docs: plan a mock Odoo sidecar next to the mock Kubernetes API 6e95a05939

OdooClient speaks XML-RPC, so a stub is a small xmlrpc.server answering
authenticate and execute_kw with canned rows. Adds a loopback guard for
the Odoo URL and the database host as well: the fence becomes a check
instead of a promise.

🤖 Generated with Pi (https://github.com/earendil-works/pi) using deepseek-v4.1-flash

tobru added 1 commit

2026-10-31 20:29:22 +00:00

docs: implementation plan for the agent workspace 26bd3745f3

Nine tasks, each with a failing test first. Pod tooling lives in the
Django project as two management commands, so the workspace logic is
tested with pytest instead of bash.

🤖 Generated with Pi (https://github.com/earendil-works/pi) using deepseek-v4.1-flash

tobru changed title from ~~docs: design for an agent workspace pod~~ to WIP: docs: design for an agent workspace pod

2026-11-03 11:54:25 +00:00

This pull request is marked as a work in progress.

This branch is out-of-date with the base branch

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/agent-workspace:docs/agent-workspace

git switch docs/agent-workspace

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff docs/agent-workspace

git switch docs/agent-workspace

git rebase main

git switch main

git merge --ff-only docs/agent-workspace

git switch docs/agent-workspace

git rebase main

git switch main

git merge --no-ff docs/agent-workspace

git switch main

git merge --squash docs/agent-workspace