Skip to content

Run lifecycle & registry

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.

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).

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.

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:

  • dirty is one bit. It catches the clean → dirty transition and nothing after it; a second edit to an already-dirty tree moves no field. HEAD is the input that moves on every commit, and it’s exact.
  • Nothing acts on this. Drift is reported, never healed — see above. A git switch changes 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.

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.

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.