Workspace Lifecycle

The operator workflows that prepare a workspace, run its agents, inspect its state, and remove only the resources selected by a lifecycle command.

Start a workspace

ploinky start resolves one workspace identity, acquires the workspace lock, prepares required repositories and dependencies, starts the Router and selected agents, and waits for the declared readiness graph. The command reports readiness only after the required external health checks pass.

flowchart TD
    A[Select workspace] --> B[Lock and validate identity]
    B --> C[Prepare repositories and dependencies]
    C --> D[Start Router and agents]
    D --> E[Verify readiness graph]
    E --> F[Expose active routes]

Workspace startup flow

Example: run ploinky start from the workspace directory. A static target supplied to the command is enabled through the normal agent path before the workspace starts.

Manage agents and repositories

Repository commands install, update, inspect, or unregister source selected from the workspace or managed storage. Agent commands enable, disable, start, restart, reinstall, stop, and open a selected agent's shell or CLI. Each action resolves the intended enabled record before it changes the runtime.

Operator action	Result
`enable` / `disable`	Adds or removes an enabled-agent record and coordinates the matching runtime lifecycle.
`restart` / `reinstall`	Replaces or refreshes the selected runtime through its recorded manifest and backend.
`shell` / `cli`	Opens an interactive session in the selected agent runtime without exposing it as a host service.
`update`	Refreshes repositories at their selected source paths and invalidates prepared dependency caches when their resolved inputs change.

Disabling an agent removes its registry record before runtime teardown. This preserves the precise selected identity for cleanup and prevents the Watchdog from treating the intentional stop as a failed runtime to recreate.

Use agent repositories from the workspace

Keep an agent repository directly inside the workspace to run and develop its agents from that checkout. All operations that select repository source use the same priority: a matching local checkout first, then the managed repository under .ploinky/repos/<repository>. Source files from the two copies are not merged.

Look for a direct workspace child named after the repository alias, containing at least one agent directory with manifest.json.
Otherwise, match the registered Git URL, or the explicit installation URL, against Git origins of direct workspace children containing agents. Hidden directories and node_modules are excluded. Multiple origin matches produce an error requiring the duplicate checkouts to be resolved.
If neither local lookup finds a source, use .ploinky/repos/<repository>; installation or startup preparation clones it there when needed.

For example, work/AssistOSExplorer with origin https://github.com/AssistOS-AI/AssistOSExplorer.git supplies the registered repository AchillesIDE when Ploinky runs in work, even if work/.ploinky/repos/AchillesIDE also exists. The agent principal remains agent:AchillesIDE/explorer. Folder names select source locations; registered aliases continue to identify agents, dependency caches, and runtime ownership.

Operation	Workspace checkout behavior
Discovery and inventory	Installed and active repository lists and Marketplace include local repositories even without a managed copy. Missing and explicitly unregistered sources are excluded. An empty enabled-repository list means all installed repositories are active; otherwise only installed entries in that list are active.
Install and automatic preparation	Reuse the matching checkout and record its repository association without cloning another copy or switching its branch. Manifest-declared repository dependencies are read from the selected source.
Prepare and launch a new runtime	Read manifests, configuration, hooks, code, skills, and dependency inputs from the selected repository. Managed source links are refreshed during lifecycle preparation.
Explicit repository update	Update the selected checkout, including a workspace Git checkout. A local directory without Git metadata is not replaced by a clone.
Uninstall repository	Disable and unregister the local repository while preserving its files. Explicit installation registers it again. Uninstalling a managed-only repository removes its managed directory.

An existing runtime retains the source paths admitted for its generation. Adding or removing a local checkout does not redirect an already running instance. Use a lifecycle action such as restart or reinstall to select the source for a new runtime; teardown and routing still refer to the exact existing runtime identity.

Recover WebTTY terminals

Explorer's folder menu offers the Ploinky Box first, followed only by live agents whose effective mounts prove access to that exact folder. A read-only badge describes the selected folder mapping. Closing a tab normally reclaims the exact terminal and its foreground descendants.

At Router startup, WebTTY v2 recovery records distinguish a worker-only allocation, a PTY that was starting, and a PTY with complete Box or agent evidence. Recovery verifies immutable process and container identities before signaling anything and retains ambiguous evidence instead of guessing. An ambiguity confined to one immutable agent container and enable generation quarantines only that target; a systemic agent-provider evidence failure removes all agent choices but preserves the Box choice. Unsafe unclassifiable or Box evidence keeps the entire WebTTY surface unavailable.

Operator recovery: target quarantines do not expire. If normal exact-identity recovery cannot prove cleanup, run ploinky destroy for the affected workspace and then recreate it through the normal ploinky start workflow. Box recreation clears the transient /run/ploinky/webtty records and nested containers; it preserves host workspace data and the retained dependency/image caches. Do not edit recovery records or kill numeric PIDs by hand.

Observe runtime state

ploinky status and ploinky logs are observational paths. They inspect the existing workspace and its recorded agents without initializing a new workspace or repairing a failed one.

The Watchdog supervises the Router and admitted runtimes. It performs health checks, applies bounded restart behavior, and removes a route when its corresponding runtime is no longer healthy. The authenticated status interface exposes read-only state and metrics; it does not become a command-execution surface.

Stop and destroy

stop stops the Router and active agent runtimes while retaining reusable workspace state. destroy removes the exact managed outer Box and discards its nested runtime layers and inner volumes. It preserves the workspace, .data/ agent homes, dependency cache, and image cache unless an explicit cache-deletion option selects those regenerated caches.

flowchart TD
    S[Stop] --> R[Router and agents stopped]
    R --> K[Workspace state retained]
    D[Destroy] --> X[Selected runtimes removed]
    X --> C[Nested runtime state discarded]
    C --> V[Workspace and persistent data retained]

Workspace stop and destroy flow

Lifecycle actions validate immutable workspace identity immediately before mutation. A command that cannot identify its exact target fails rather than adopting a similarly named Box, container, process, or repository.