Multi-repo projects: design #3

New issue

Open

opened 2026-10-01 09:20:27 +00:00 by jan · 0 comments

jan commented

2026-10-01 09:20:27 +00:00

Owner

Motivation

Agentbox maps one Git repository to one VM. A real work project I want to use
it for is a folder with five sibling repositories that import each other, plus
a large non-Git data folder:

project-root/            not a Git repository
├── repo-a/              imports repo-b
├── repo-b/
├── repo-c/
├── repo-d/
├── repo-e/
└── test_data/           ~70 GB, not Git, read-only for the agent

Launch scripts in the repos find their siblings relative to themselves
(../repo-b), so the layout has to stay identical inside the VM.

sbx create --clone handles exactly one repository: one private clone, one
sandbox-<name> git-daemon remote on the host. Sibling repos need another
way in and another way back.

Proposed design (to validate)

Manifest at the project root, parsed like the config (KEY=VALUE or a
simple line format, never sourced). Sketch:

name = myproject-agent
repo = repo-a
repo = repo-b
...
data = test_data            → see the data-mount issue
template = myproject:v1     → see the project-templates issue

Inside the VM: one directory per project, same sibling layout. Each repo is
a private clone whose only remote is host, pointing at a read-only source.

Way in: either read-only workspace mounts (sbx create ... path:ro, documented
for additional workspaces), or host-made git bundles copied in with
sbx cp. To find out: can the primary workspace be mounted :ro, or can a
sandbox be created with no primary workspace and only :ro extras? Without
clone mode the primary path is bind-mounted read-write, which is exactly
what agentbox avoids today.

Way back: git bundle create inside the VM, sbx cp to a quarantine
directory on the host, git fetch from the bundle. That is the same direction
and trust level as fetching from the git daemon today, it works for any number
of repos, and it does not depend on sbx's clone mode at all. Side effect: the
"sbx restores origin on every start" problem does not exist without
--clone.

Open questions

Does the bundle path replace clone mode for single-repo projects too
(one code path), or do both stay?
How are diff, merge, sync, status addressed per repo?
(agentbox diff repo-b? all repos by default?)
remove must refuse while any repo has unfetched commits.
Ownership registry: the record points at the project root, not a repo.
Secret-file preflight has to cover every repo (and data folders).
Is sbx env / sbxenv.yaml a usable base for the manifest, or too
experimental to build on?

Done when

A design section in docs/ARCHITECTURE.md (or docs/MULTI_REPO.md) answers
the questions above and is backed by a manual prototype against real sbx.
Implementation: #4 (Multi-repo projects: implementation and tests).

## Motivation Agentbox maps one Git repository to one VM. A real work project I want to use it for is a folder with five sibling repositories that import each other, plus a large non-Git data folder: ```text project-root/ not a Git repository ├── repo-a/ imports repo-b ├── repo-b/ ├── repo-c/ ├── repo-d/ ├── repo-e/ └── test_data/ ~70 GB, not Git, read-only for the agent ``` Launch scripts in the repos find their siblings relative to themselves (`../repo-b`), so the layout has to stay identical inside the VM. `sbx create --clone` handles exactly one repository: one private clone, one `sandbox-<name>` git-daemon remote on the host. Sibling repos need another way in and another way back. ## Proposed design (to validate) **Manifest** at the project root, parsed like the config (KEY=VALUE or a simple line format, never sourced). Sketch: ```text name = myproject-agent repo = repo-a repo = repo-b ... data = test_data → see the data-mount issue template = myproject:v1 → see the project-templates issue ``` **Inside the VM:** one directory per project, same sibling layout. Each repo is a private clone whose only remote is `host`, pointing at a read-only source. **Way in:** either read-only workspace mounts (`sbx create ... path:ro`, documented for *additional* workspaces), or host-made `git bundle`s copied in with `sbx cp`. To find out: can the *primary* workspace be mounted `:ro`, or can a sandbox be created with no primary workspace and only `:ro` extras? Without clone mode the primary path is bind-mounted **read-write**, which is exactly what agentbox avoids today. **Way back:** `git bundle create` inside the VM, `sbx cp` to a quarantine directory on the host, `git fetch` from the bundle. That is the same direction and trust level as fetching from the git daemon today, it works for any number of repos, and it does not depend on sbx's clone mode at all. Side effect: the "sbx restores `origin` on every start" problem does not exist without `--clone`. ## Open questions - [ ] Does the bundle path replace clone mode for single-repo projects too (one code path), or do both stay? - [ ] How are `diff`, `merge`, `sync`, `status` addressed per repo? (`agentbox diff repo-b`? all repos by default?) - [ ] `remove` must refuse while *any* repo has unfetched commits. - [ ] Ownership registry: the record points at the project root, not a repo. - [ ] Secret-file preflight has to cover every repo (and data folders). - [ ] Is `sbx env` / `sbxenv.yaml` a usable base for the manifest, or too experimental to build on? ## Done when A design section in `docs/ARCHITECTURE.md` (or `docs/MULTI_REPO.md`) answers the questions above and is backed by a manual prototype against real sbx. Implementation: #4 (Multi-repo projects: implementation and tests).

jan referenced this issue

2026-10-01 09:20:29 +00:00

sbx 0.46 compatibility: --no-share-skills is gone #2

jan referenced this issue

2026-10-01 09:20:30 +00:00

Multi-repo projects: implementation and tests #4

jan referenced this issue

2026-10-01 09:20:31 +00:00

Project templates on top of the agent template #5

jan referenced this issue

2026-10-01 09:20:31 +00:00

Read-only data mounts with a disposable writable layer #6