| subsystem | plane | |
|---|---|---|
| owned_paths |
|
The first slice of the management server for self-hosted FlyBot (#3113, parent #3110): accounts, workspaces and instance metadata, the two separated credentials, the create/start/stop/restart lifecycle, and an abstract lifecycle backend with one compose materializer. It is a skeleton on purpose: no container is started in this slice.
plane/: the@flybot/planepackage — store, credentials, lifecycle contract, HTTP router, CLI, tests and its README. The three replaceable working defaults (granularity, storage, backend) are at the top of plane/README.md.
- The FlyBot runtime inside the instance (Agent, sessions, memory, scheduling) — that stays
core/and the plugins. - The shipped image,
Dockerfile,compose.yaml,docker/and the pack whitelist — this package is not in the image and not indocker/profile.mjs's bundles. - Cross-instance social traffic — Bot Social and
plugins/social; the plane will configure an instance's connection later, not carry messages. - Upgrade, recycle, backup and recovery implementation — present only as
NotImplementedErroron the lifecycle contract.
- The plane never runs an Agent. It records an instance, and a
LifecycleBackenddecides where it runs; the first backend writes a compose project and starts nothing. - Two credentials never interchange:
op_is accepted on/api/*only,ctl_is what the plane hands an instance. Only sha256 is persisted, and comparison is timing-safe. - Every instance route checks the operator token first, then
instance.ownerId === token.accountId; a mismatch is403, an unknown id is404, no token is401. (workspaceId, name)is unique inside an owner's workspace, never globally; a clash isDuplicateInstanceError/ HTTP 409.workspace.membersis the only source of membership:owner / admin / member, and the creating account becomes the onlyowner. An olderplane.jsonis read with its owner seeded as the only member, never rejected.GET/POST /api/workspaces/:id/membersverify the token, then pick the workspace by the caller's role: two owners' same-namedws-1never mix. Non-member403, unknown id404, duplicate member409, unknown role400. A role does not reach the instance routes yet — those still answer toinstance.ownerIdalone, so anadminadds members and nothing more. A workspace id is still owner-scoped, so one account invited into two owners'ws-1resolves to the first one stored; scoping the workspace key is the next slice.plane.jsonis written atomically (temporary file + rename), mode 0600, directory 0700, and carriesversion: 1for migration.upgradeandrecyclefail loudly (NotImplementedError) instead of pretending to succeed.
npm --prefix plane test (25 cases) runs in the L1 plane suite registered in
docs/testing-layers.json and in the Plane tests step of
.github/actions/flybot-tests/action.yml. Root
npm run verify includes it. The suite needs no Docker, network, socket or model.