| name | foldyard |
| description | Orient yourself in a foldyard dev box and drive it — the host/box split, what the box structurally cannot do, posture modes for credentials, egress and the proxy, worktrees, and why a config or compose change might not have taken effect. Use whenever `fy`/`foldyard` commands appear, when something needs a credential or network access it doesn't have, when a change "doesn't take", or when asked to work on the dev environment itself. |
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
- 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.
- 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.
- 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.
- 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.
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.
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. 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.
