Canonical definitions for the runtime, workspace, agent, routing, identity, and configuration concepts used by Ploinky.
This page defines Ploinky-specific vocabulary used by the operational guides and design specifications. Each entry describes the concept's owner, role in a workflow, important relationships, and enforced boundary; implementation identifiers remain in their original form.
The Ploinky Box is the single rootless outer container owned by the host ploinky process for one canonical workspace. It mounts Ploinky source read-only, mounts the selected workspace and validated caches explicitly, and contains ploinky-local, the Router, and nested agent runtimes. Its physical-host network boundary is fixed to the loopback Router TCP publication and one LiveKit UDP publication; agent listeners and private Router port 8081 remain inside the Box.
The Box Supervisor is the host-side lifecycle code that resolves the workspace identity and creates, validates, starts, stops, replaces, or removes its exact Ploinky Box. It verifies ownership, engine state, image identity, mounts, confinement, and publications before mutation and never adopts an ambiguous or foreign container. It owns the outer boundary only; nested agents are controlled by ploinky-local inside the Box.
ploinky-local is the in-Box Ploinky process that owns workspace initialization, repository and dependency preparation, enabled-agent lifecycle, routing generation, and supervision of nested runtimes. The public wrapper enters this process after the Box boundary is ready. It must not create another Box, because the host process is the only owner of the outer runtime.
A nested agent runtime is the isolated process environment created for one enabled agent instance inside the Ploinky Box. Managed Box execution uses rootless Podman and supplies only the generated mounts, declared environment, private network placement, resource limits, and exact identity admitted for that instance. Its writable container layer and inner named volumes do not survive Box destruction, so durable data must use a workspace-backed bind.
A runtime backend is the implementation that creates and controls an agent process. Direct development may select an OCI container, Bubblewrap on Linux, or Seatbelt on macOS according to manifest and workspace policy, while a marked Ploinky Box forces nested rootless Podman for managed agent, helper, probe, and installation work. Backend selection changes process and mount mechanics but does not weaken workspace identity, environment filtering, readiness, or routing admission.
A workspace is the canonical directory from which Ploinky manages one project, its repositories, enabled agents, runtime state, and persistent data. Commands resolve the nearest valid workspace root or an explicitly admitted root before reading or mutating resources, and the absolute canonical path participates in the Box identity. One operation must never discover, adopt, or change another workspace's state.
.ploinky/ is Ploinky-owned workspace state. It contains managed repository checkouts, the enabled-agent registry, routing candidates, encrypted variables, the master key, logs, dependency and image caches, locks, generated topology, and feature-specific service data. Agents do not receive it as an unrestricted home, and cleanup must select exact owned children rather than recursively treating the complete directory as disposable.
.data/ is the workspace-root directory that provides one persistent home for each agent instance. The directory name uses the alias when present and otherwise the agent name, so multiple instances of one source agent keep independent configuration and history. Disabling or replacing a runtime preserves this home unless a separate, explicit data-removal operation is defined.
A managed repository is a Git checkout stored under .ploinky/repos/<repository>/ and recorded with enough source and branch information for later update or repair. Ploinky uses repositories as the distribution and development unit for agents, and one repository may contain several independent agent directories. Installing a repository makes its agents discoverable; it does not enable every discovered agent.
An agent directory is an immediate child of a managed repository that contains a file named exactly manifest.json. Its directory name becomes the manifest agent name, and an optional code/ child becomes the source mount when present; otherwise the agent directory is the source. A directory without the required manifest is ordinary repository content and is not discoverable as an agent.
An agent manifest is the manifest.json contract that declares portable agent intent: image, commands, environment inputs, profiles, dependencies, startup behavior, mounts, readiness, network placement, MCP configuration, and supported policy metadata. Ploinky validates and combines it with workspace policy before runtime creation. The manifest cannot grant itself core credentials, publish an outer Box port, or override Router-owned identity and topology values.
A runtime profile is a named manifest configuration selected for a workspace stage such as development, QA, or production. It may refine the supported lifecycle hooks, environment declarations, mount access, dependencies, provider selection, and private runtime settings according to the manifest merge rules. A profile is not an unrestricted copy of the root manifest: root-only security fields and unsupported runtime arguments remain rejected.
An agent is repository-controlled software that Ploinky discovers through an agent manifest and runs through a selected isolated runtime. It may provide an interactive CLI, a long-running service, MCP tools and resources, static files, or other Router-mediated interfaces. Ploinky owns packaging, lifecycle, isolation, observation, and communication boundaries; the agent owns its application behavior and agent-specific persisted state.
An enabled-agent record is the workspace registry entry that binds one manifest agent to an exact repository, run mode, optional alias, runtime identity, authentication selection, and enable generation. Lifecycle and routing commands use this record instead of selecting a process by a convenient name. Removing the record coordinates route withdrawal and runtime teardown while leaving the instance's persistent home intact.
An agent alias is a workspace-unique name assigned to an additional enabled instance of a manifest agent. It becomes that instance's route key, command selector, runtime identity label, and .data/ home name, allowing two instances of the same source agent to remain independent. An alias does not change the canonical source principal derived from the repository and manifest agent.
The static agent is the enabled agent selected as the workspace's default browser application during start. On a control host, the Router may redirect / or /index.html to this agent's prefixed route. Static selection does not grant the agent administrative authority, does not make it the aggregate MCP server, and does not let it bypass ordinary readiness and route policy.
Manual startup is the manifest policy startup: "manual", which keeps an already stopped enabled agent outside the static dependency graph dormant during an ordinary workspace start. A running manual agent stays running, while a static agent or explicit dependency starts regardless of this policy. An operator activates a stopped manual instance through its explicit restart path, which must recreate or start the exact runtime, verify readiness, and restore its route.
The dependency graph is the complete resolved set and ordering of manifest agents required for a workspace start. Ploinky resolves repository-qualified references, profiles, provider nodes, and direct dependencies before launch, rejects cycles or ambiguity, and starts nodes only after their dependency barriers are satisfied. Graph membership can force a manual agent to start because required dependencies take precedence over the manual-startup preference.
A dependency cache is a prepared, runtime-keyed installation of global and per-agent Node dependencies stored under .ploinky/deps/. Ploinky validates the runtime key and merged package hash, prepares missing or stale content in the appropriate backend, and mounts accepted content read-only into the agent runtime. The cache is regenerated state rather than agent-owned durable data.
Readiness answers whether a newly started agent runtime may receive traffic. Ploinky may use an MCP handshake, TCP connection, declared readiness script, or explicit no-serving-surface decision, then activates a route only after the selected check succeeds. A readiness failure prevents dependent startup and route publication; it is not hidden by the presence of a running process.
Liveness answers whether an already admitted runtime remains healthy enough to keep serving. The Watchdog applies the declared recurring probe and bounded failure threshold to the exact recorded runtime, withdraws a stale route before recovery, and uses bounded restart backoff. Liveness does not replace initial readiness, and an activation-only readiness probe requires separate recurring liveness coverage.
A no-wait dependency is a graph node allowed to continue startup asynchronously after its identity, direct dependencies, and final preparation generation have been fixed. Its detached worker has a run-specific identifier, status, log, deadline, and terminal ready, failed, or superseded state. No-wait shortens the synchronous command boundary but does not permit raw route activation, stale-runtime adoption, or unobservable readiness failure.
The Router is Ploinky's single HTTP, Server-Sent Events, WebSocket, and MCP mediator for browsers, agents, and workspace services. It selects a closed surface from the listener class and exact Host, authenticates the caller, applies route or tool policy, verifies the active generation, and only then serves a file or opens a private upstream connection. Reachability, loopback origin, and container networking are never accepted as authorization.
A route key is the validated workspace-local name used to select one enabled agent through a path such as /<agentName>/.... It is normally the manifest agent name and becomes the alias for an aliased instance. The Router resolves it against the active generation, so an unknown, ambiguous, disabled, or stale key cannot fall through to another agent.
An edge generation is the immutable installed snapshot that binds host selection, routes, targets, and authorization policy for dispatch. Ploinky stages and validates a complete candidate before installation and keeps malformed, partial, or superseded candidates inactive. HTTP, SSE, WebSocket, static-file, and MCP operations revalidate the captured generation at their final execution boundary.
A route lease is the captured proof that a selected target and policy belong to the active generation for the current request. The Router commits or revalidates this lease immediately before reading agent content, dialing an upstream, or executing an operation. A generation change invalidates the lease and stops dispatch instead of allowing a request to reach a predecessor runtime.
AgentServer is Ploinky's default private service for an agent that does not provide its own service command. It loads the runtime-owned mcp-config.json, exposes MCP tools, resources, and prompts, provides health and supported OpenAI-compatible endpoints, and performs traversal-safe static serving below the agent source. The Router remains the public policy boundary; AgentServer is not published directly to the physical host.
Model Context Protocol is the JSON-RPC interface Ploinky uses for tool, resource, prompt, task, and agent-service interactions. The control-host /mcp route aggregates admitted capabilities across active agents, while /<agent>/mcp selects one exact agent's MCP service. Router authentication, active-generation checks, MCP policy, and request-bound target credentials apply before an agent command executes.
WebChat is the authenticated Router-owned browser application that connects one browser tab to a selected agent's manifest CLI. Browser input travels through protected HTTP routes, CLI output returns through a Server-Sent Events stream, and the browser never opens a direct terminal or container connection. The CLI owns conversation persistence and asynchronous task state; WebChat validates and renders bounded runtime snapshots.
A WebChat message envelope is the optional versioned JSON record written to the selected CLI's standard input when webchat.forwardEnvelope is enabled. It carries the user text and validated request context such as attachments and workspace-relative references, followed by one newline. It does not contain reconstructed conversation history or reusable browser and provider credentials.
A WebChat control record is one complete newline-delimited JSON object emitted by a CLI with a recognized versioned marker for session, task, runtime, workspace-file, skills, or interaction state. WebChat strips terminal controls, validates the schema, removes accepted records from visible assistant text, and converts them to named browser events. Malformed or unknown records remain ordinary output and cannot update browser state.
An agent command catalog is the selected agent's structured list of slash commands and completion behavior exposed through its MCP tools. WebChat obtains it during page initialization, caches it in the browser, and performs filtering locally; a reconnect does not resend or reload the catalog. A full page load or an explicit post-skills-change refresh requests it again, and a bounded fallback may be derived from admitted execute_* tools when the catalog tool is absent.
Marketplace is the Router-owned management surface that reports repositories, discoverable agents, enabled instances, and runtime state and accepts a bounded set of lifecycle actions. Human mutations require local administrator authority and browser mutation proof; an asserted agent receives only explicitly admitted operations such as reading inventory or enabling an already available dependency. Marketplace does not grant agents repository removal or general workspace administration.
The Watchdog is the in-Box supervisor for the Router and admitted agent runtimes. It observes exact recorded identities, performs supported health checks, removes stale routes, records bounded diagnostics, and requests controlled recovery with backoff. It does not invent desired state, recreate deliberately disabled agents, or make read-only observation commands mutate the workspace.
A local user is a human identity authenticated by Router-managed password credentials for the selected route policy. The Router stores password material through its encrypted local-auth contract and issues a route- and generation-bound browser session after successful login. A local user's roles determine ordinary and administrative access; the user session is not an agent credential.
A local administrator is a locally authenticated user whose session and control proof satisfy Ploinky's administrator checks on an exact local-control Host. Administrative mutations additionally require the expected Origin and session-bound browser mutation proof. SSO identity, guest identity, agent assertions, loopback source, and component tokens do not substitute for this authority.
An SSO user is a human identity established through the route-selected external identity provider and normalized by the Router into a browser session. The callback, state, return path, and active generation must validate before the session is accepted. An SSO session can satisfy authenticated application access but cannot satisfy local-only administrator controls unless a separate contract explicitly grants that role.
A guest session is a Router-issued, expiring browser identity for a route whose HTTP policy explicitly permits guests. It may be scoped to the route or service that created it and can satisfy only policy classes that admit guests. It is not an anonymous bypass, a local administrator, an agent assertion, or a user-delegation source.
An agent principal is the canonical source identity agent:<repo>/<agent> assigned to a manifest agent. It identifies the repository and agent across enabled instances, while aliases and replacements receive separate runtime tuples. An agent can assert only its own principal and cannot choose a human identity, another agent, or a future generation.
A runtime tuple combines the canonical agent principal, random effective instance identifier, and enable generation for one active instance. Routing, private assertions, credentials, and cleanup compare this tuple to current registry and runtime ownership evidence. Disable, re-enable, replacement, or another identity-changing lifecycle operation rotates the tuple so predecessor authority becomes stale.
An Agent Assertion is a short-lived request-bound token signed by a source agent with its eligible agent request secret for the Router. It identifies the source, target, operation, request-content hash, time window, and replay value needed for one admitted cross-agent MCP or HTTP request. The Router still applies active-tuple checks, caller ACL, and route or MCP policy; a valid signature alone does not authorize execution.
A Private Agent Assertion is the tuple-specific token used by an eligible current agent to call the Router's private listener. It additionally binds effective instance, enable generation, HTTP method, normalized path and query, and body hash. Network access to port 8081 supplies transport only; an absent, replayed, or stale private assertion fails authorization.
A Router Request is the target-specific token minted by the Router after it authenticates the caller and admits the operation. The target agent verifies this token with its own request secret, recomputes the request-content hash, and consumes replay state before exposing normalized invocation metadata to a command. A Router Request cannot be forged by presenting a browser cookie or another agent's assertion directly to the target.
A User Delegation Grant is a separately signed, bounded record of human consent for one declared source agent, target agent, tool, user, and scope set. It accompanies, but never replaces, the source agent's own Agent Assertion and cannot broaden route or MCP policy. Guest users do not receive delegation grants.
The request-content hash, carried as rch, is the canonical digest of the method, path, query, tool arguments, or body hash relevant to a signed request. The source, Router, and target recompute the applicable value so a token cannot be replayed against different content. Canonicalization rules are protocol-specific and remain paired with token type, audience, target, expiry, and nonce checks.
A runtime capability is a core-issued authorization for one exceptional lifecycle, placement, network, or resource operation in an exact workspace generation. It can admit behavior such as constrained host-network placement after the runtime policy verifies it. It is not a human session or application JWT and cannot be presented to an agent route as caller identity.
A relay credential is a fresh, short-lived, generation-bound secret for one verified confined relay channel and private target. Ploinky delivers it only after matching the runtime, container, lease, and destination and removes it with that channel. It is absent from ordinary manifest environment, persistent routing state, logs, and host or unconfined runtimes.
HTTP route access is the closed Router policy domain with the values public, guest, and authenticated. It determines which browser identity is required for an admitted path and keeps anonymous public behavior limited to supported safe operations. Unknown, malformed, absent where required, or inapplicable values deny access, and this policy does not govern MCP tool roles.
MCP tool policy is the separate closed domain with the values authenticated, internal, and admin. It decides whether a normalized user, agent, or local-administrator caller may execute one agent tool after discovery and target resolution. Manifest tags establish defaults, persisted Router policy remains authoritative, and an agent cannot turn its own tool into an administrative operation.
A caller access-control list is the generation-bound declaration of which exact source agents may reach a protected target or private Router operation. The Router evaluates it together with the source's current tuple, request assertion, and the relevant HTTP or MCP policy. Membership alone does not authenticate a request and never grants a source agent human or administrator identity.
A browser mutation proof is the session-bound value required with state-changing Router requests after login. The Router validates it together with the exact Origin, selected Host, route, user session, and active generation to prevent a browser credential from authorizing an unrelated mutation. It does not replace local administrator checks on administrative operations.
A workspace variable is an operator- or provider-owned configuration value stored through Ploinky's encrypted variable contract in .ploinky/.secrets. An agent receives a value only when its selected manifest or profile declares the corresponding environment input and the purpose-specific resolver accepts the source. Variables are not routing authority and must not be copied into manifests, registry entries, status output, or logs when sensitive.
The workspace master key is the root secret for encrypted workspace stores and purpose-separated derived keys. A managed Ploinky Box reads only the private .ploinky/master-key file created for that workspace and removes host environment overrides before core execution; direct development has a separate documented resolution order. The key is never injected into an agent, provider command, route, log, or test artifact.
An agent-generated secret is a deterministic manifest environment value derived for one workspace, repository, agent, and inside variable name. The declaration generatedSecret: true lets cooperating lifecycle code reproduce the value without storing it in the manifest, while keeping different agents and names separated. An operator value overrides it only when the manifest explicitly permits and validates that override.
A shared generated secret is a deterministic value derived from the workspace key and an explicitly declared shared source name. It exists for agents that intentionally need the same secret and therefore has a broader trust boundary than an agent-generated secret. Ploinky still requires each consumer to declare the value and excludes it from provider output, logs, and ordinary routing metadata.
A startup config provider is an agent repository component whose manifest declares a bounded command and an allowlist of configuration outputs needed before dependent runtimes start. Ploinky runs providers in the selected graph order, strips protected environment values, validates one versioned JSON result, persists only accepted changes, reloads affected configuration, and then captures the final launch lease. Provider code proposes ordinary values but cannot write Ploinky state directly or control routing, publication, topology, generated-secret ownership, or core credentials.
An architecture catalog is external, schema-validated JSON data that describes supported local-LLM platforms, accelerator requirements, images, runtime policy, and agent-to-architecture mappings. The hardware detector and selector consume this data to choose a compatible record, but the catalog cannot execute probes, inject raw engine arguments, grant arbitrary devices, or choose host paths. Ploinky converts only an allowlisted validated record into an ordinary constrained runtime plan.
A local LLM runtime is an agent container whose manifest opts into architecture-catalog selection and persistent model storage. Ploinky owns hardware matching, image and policy validation, safe device translation, the /models mount, redacted selection state, and normal lifecycle admission. The agent owns model downloads, cache layout, inference behavior, and its OpenAI-compatible or MCP application interfaces.
Cloudflare publication is the optional core-owned path that connects a configured external hostname to the fixed in-Box Router origin at http://127.0.0.1:8080. Ploinky validates complete configuration, keeps connector credentials out of agent environments, coordinates ingress and DNS with the active generation, and records ownership before any managed teardown. Without valid configuration the workspace remains local-only; agents and startup providers cannot create or mutate publication authority.
The LiveKit media surface is the Box's single wildcard UDP publication targeting the fixed in-Box listener on port 7882. The physical-host UDP port may be selected independently, but it remains one of exactly two outer engine publications. Media reachability does not grant Router identity, agent access, or permission to publish another service.
A TURN credential is a short-lived media-relay credential minted through the Router's private service for an exact allowlisted current agent and available topology. It is rate-limited, generation-bound, and belongs only to the TURN protocol. It cannot serve as a browser session, Agent Assertion, Router Request, runtime capability, or reusable workspace variable.