foldyard

# Working in (and on) a foldyard dev box Foldyard runs this project inside a **rootless VM that mounts only this repo**. You are almost certainly *in the box* — a container in that VM — and the person you're working with is on the **host** (their Mac). That split explains nearly everything below. Check where you are: `fy mode` prints the posture and says which side it's reading from. `fy verify` proves the boundary (it exits non-zero if any of it is false). ## The four facts that will save you the most time 1. **You cannot push.** No credential to the git remote reaches the box, by design. Read and commit locally; the human pushes. Don't try to work around it — there is nothing to find. 2. **You hold no real secrets, and can't grant yourself any.** Posture state lives in the host's home, outside the mount. `fy mode` *shows* posture anywhere; *setting* it is host-only. 3. **Your egress goes through the host's proxy** and may be allow-listed or walled. A blocked host is a decision, not a bug — ask; don't route around it. 4. **The engine socket you have is real** and bounded to this VM. `docker`/`podman` commands work and act on the live dev stack — including anything a test suite's mocks let slip. ## Ask the tool, don't guess Foldyard is introspectable, and its own output is always current — prefer it over any summary (including this one): | question | command | | --- | --- | | what can this environment do right now? | `fy mode` (posture), `fy state` (desired vs observed) | | what's broken / missing? | `fy doctor` — one line per check, each with its fix | | is the isolation intact? | `fy verify` | | what does this verb do? | `fy --help`, `fy <verb> --help` | | the manual, offline, by topic | `fy docs` — then `fy docs <topic>` | | what does the config let the host do? | `fy config widenings` | `fy docs` serves **this install's** documentation, so it can't drift from the code you're running. Start with `fy docs quickstart`, `fy docs modes`, `fy docs networking`, `fy docs security`; the ADRs (`fy docs adr-0001` …) carry the reasoning behind each design decision. ## Daily verbs `fy up | ps | logs [svc] | shell | down` drive the compose stack; `fy box shell | ps` the dev box itself; `fy verify` proves the cage. A consumer repo usually wraps these in its own `just` recipes — check the repo's justfile and CLAUDE.md before reaching for `fy` directly. ## When you need something you don't have **A credential** (a cloud token, an API key): you can't grant it. Name the exact command the human should run on their Mac and why. Postures are per-axis — `fy mode` lists the axes this project declares and their rungs, and high-privilege rungs expire on a timer by design. Detail: [posture-and-credentials.md](references/posture-and-credentials.md). **A host through the network wall**: `fy allow add <host> --level session` — **on the host**. Tell them the hostname and what needs it. Detail: [egress-and-capture.md](references/egress-and-capture.md). **A tool in the box**: it belongs in the project's `foldyard.toml` (`[[box.tools]]`) so it survives a box rebuild, not in an ad-hoc `apt install` that the next `fy box down` throws away. The `bootstrap-devbox` skill covers growing that config from inside the box. ## "I changed it and nothing happened" The most common class of confusion here. Full table: [when-a-change-doesnt-take.md](references/when-a-change-doesnt-take.md). The three big ones: - **`foldyard.toml`** — the host runs the copy it **adopted**, not your working tree. Your edit is inert until the human answers the prompt at the next `fy up`/`fy host` (or runs `fy config adopt`). Check with `fy config status`; see what changed with `fy config diff`. - **Compose files** — read from the **primary checkout**, so an edit inside a worktree changes nothing until it reaches that checkout. - **A running container** — keeps the command and env it was created with. A config change needs a recreate (`fy up`), not a restart. ## Working on foldyard itself Read `fy docs` first — it's the installed version's own manual. The source lives at <https://github.com/twistco/foldyard>. Don't clone it into the box to "check how it works": you'd get a different version than the one running here, which is the exact confusion this design goes out of its way to prevent. The supported way to develop against it is the **co-dev mount** (`fy docs adr-0020`), which mounts the real checkout and installs it editable.