Run lifecycle & registry
One environment, two verbs
Section titled “One environment, two verbs”A workspace has exactly one environment: one docker network, one sidecar, one set of containers. There is nothing to create or name — the first start creates it. Two verbs act on it:
- Start a node — bring up whatever that node requires that isn’t
running, then (re)create the node itself from the current config, then
restart its running dependents in place (
docker restart, not a rebuild) so they reconnect to the new container. On a workspace with no environment yet, this is what creates it, with just that node and its requirements in it. - Switch to a flow — make the environment that flow: top up the flow’s nodes (start what’s missing, recreate what drifted, leave alone what’s already correct), then stop — never remove — every running container outside it, dependents before their requirements. Stopped containers keep their volumes; switching back starts them again.
There is no “stop the environment” action: stopping single nodes, or
switching flows, covers day-to-day use. The environment’s containers,
network and sidecar are only torn down when the workspace itself is
removed (POST /workspaces/remove, the Config tab’s “Remove workspace”).
Removing discards it: its volumes, and the data in them, go too, so wiring
it again starts from empty stores.
Liveness is checked directly against Docker on every call, never trusted from persisted state alone — a container can be stopped or removed out-of-band between calls, so only a fresh check is trustworthy.
Branch overrides: removed
Section titled “Branch overrides: removed”Every node always builds straight from the live workspace checkout, so local edits are picked up on every run without needing a commit first.
This used to have a second mode — a run could override which branch a specific node built from, via a throwaway mirror + checkout kept separately from the live checkout. It was removed: see Branch ownership model for why (a real permission bug in the mirror clone, plus no designed answer for an override branch whose own config doesn’t match the live graph’s shape).
The reconciler: drift correction
Section titled “The reconciler: drift correction”A background loop checks every live run’s containers each second, with one
Docker listing per workspace rather than a call per container, against real
Docker state and writes back any status that changed —
including flagging a container that’s vanished entirely (removed by hand,
outside fghj) as removed. This is explicitly analogous to a Kubernetes
controller’s reconcile loop.
What it does with the reading depends on what happened. A service you
asked to run that is down without you stopping it through fghj (a crash,
a Docker or OrbStack restart, a reboot, a hand-typed docker stop) is
restarted by fghj, through the same path as the Start button: what it
depends on comes up first, and the node’s events show each attempt. Tries
back off from 5 seconds to 5 minutes, one node at a time. A Stop through
fghj is the one thing it respects. Tasks never restart.
A container deleted outside fghj (docker rm, a prune) is not something
Docker can bring back, and nothing can tell whether it was meant. The node
reads missing, and its drawer asks: Recreate it, or Forget it.
The same kind of check runs once at daemon startup, against whatever was
persisted from a previous fghjd lifetime. Every container is kept:
containers Docker still knows about get a freshly inspected status, ones
that have vanished come back as missing, and if Docker can’t be reached at
all the record is left as it was rather than read as “everything’s gone”.
Only the observed half is refreshed. What fghj recorded that it wanted
the container to be doing survives the restart untouched, which is what
lets a container that died while fghjd was down come back reading as
drifted rather than as freshly correct.
Which commit a container is running
Section titled “Which commit a container is running”Config drift covers more than .fghj.yaml. For a node fghj builds, the
checkout itself is an input: the same build: stanza at a different commit
produces a different container. So the hash that decides synced vs
drifted folds in the checkout’s HEAD and whether its tree was dirty,
and a git commit, git pull or rebase moves a built node to drifted
without .fghj.yaml changing at all.
That matters because the image tag doesn’t move. fghj tags what it builds
fghj/<node>:<branch> — stable across commits by design, so there’s no tag
to notice. Before the checkout was part of the hash, you could pull and the
node stayed lit as synced while serving the old code.
Alongside the hash, each container records the branch and commit it was actually built from. The hash is a digest, so on its own it can only report that something moved; the recorded commit is what lets the UI say
a3f9c1 → 4f4cd9d— built from one commit, checkout now on another. It’s a snapshot taken when
the container was created and never refreshed: a field that followed the
checkout would always agree with it and could never show drift. The same two
facts are also stamped on the container as fghj.source_branch and
fghj.source_head labels, so docker inspect answers “what commit is this
running” without fghj in the loop.
Two caveats worth knowing:
dirtyis one bit. It catches the clean → dirty transition and nothing after it; a second edit to an already-dirty tree moves no field.HEADis the input that moves on every commit, and it’s exact.- Nothing acts on this. Drift is reported, never healed — see above. A
git switchchanges the graph under a live environment constantly, and a background loop recreating containers in response would fight whoever is working in it. Reset the node when you want the new code.
A container started by an fghjd from before this was recorded reads back
with no source rather than a guessed one, and the UI says nothing instead of
claiming a commit fghj never saw.
How the proxy finds a container
Section titled “How the proxy finds a container”Each running container carries a list of routes — domain/host-port pairs
built from every port that’s either primary or named (see
Node identity & domains). This is
what lets the TLS proxy turn an incoming HTTPS request into a
127.0.0.1:<port> to relay to — fghjd runs on the host, outside the
Docker network, so it can’t rely on Docker’s own embedded per-network DNS
the way sibling containers can. See
Local CA & TLS proxy. These routes are
persisted alongside the rest of a run’s state, so routing survives a
fghjd restart along with everything else the startup reconciler
restores.
Limitations
Section titled “Limitations”Route lookup only considers containers with a "running" status, which
excludes stopped containers correctly but can briefly still return a
route to a container that’s been fully removed between reconcile ticks.