Ploinky Runtime

How Ploinky prepares, starts, and supervises one agent runtime without exposing its private services.

Workspace state

Each workspace owns its enabled-agent registry, managed repositories, generated dependency caches, and persistent agent homes. These records let lifecycle commands identify one exact runtime instead of guessing from a name or a live container.

Runtime selection

Enabling an agent resolves its manifest, validates an optional alias, selects an authentication mode, and records the resulting instance before the route can become active. An alias is both the route key and runtime identity, allowing more than one instance of the same agent in a workspace.

flowchart TD
    M[Agent manifest] --> E[Enable record]
    E --> R{Placement policy}
    R -->|Default| C[OCI runtime]
    R -->|lite-sandbox on Linux| B[Bubblewrap]
    R -->|lite-sandbox on macOS| S[Seatbelt]
    C --> H[Persistent agent home]
    B --> H
    S --> H

Outside a Ploinky Box, the container path detects Podman before Docker. On Linux, lite-sandbox: true selects Bubblewrap; on macOS it selects Seatbelt. Inside a marked Box, all managed agent, helper, probe, and install-container work uses nested rootless Podman.

Startup and readiness

Ploinky resolves the recursive manifest dependency graph before it starts agent processes. It prepares the matching dependency cache, starts each agent in dependency order, and admits its route only after the declared readiness checks succeed.

flowchart TD
    A[Resolve manifests] --> B[Prepare dependencies]
    B --> C[Start selected runtime]
    C --> D[Run readiness probe]
    D -->|Healthy| E[Activate route]
    D -->|Unhealthy| F[Keep route inactive]

The Watchdog observes the same recorded runtime identity after startup. A failed health check removes the stale route and schedules recovery against a fresh exact-generation runtime; a deliberately disabled agent is removed from the registry before its runtime is torn down, so it is not recreated by supervision.

Startup config providers

A startup config provider is an agent component that discovers or generates workspace configuration before dependent agents launch. It runs a declared host-side command and returns a small versioned JSON document. Ploinky validates every returned name, stores accepted values in the encrypted workspace variable store, reloads the graph configuration, and only then starts consumers. The provider never edits the store directly and its output is not injected automatically into every agent.

flowchart TD
    A[Static manifest selects provider] --> B[Ploinky resolves provider in dependency graph]
    B --> C[Provider command returns versioned JSON]
    C --> D[Ploinky validates declared output names]
    D --> E[Encrypted workspace store]
    E --> F[Consumer resolves its declared env values]
    F --> G[Final runtime preparation and launch]

Provider manifest

{
  "providesConfig": {
    "command": "node scripts/discover-config.mjs",
    "outputs": [
      { "name": "SERVICE_BASE_URL", "sensitive": false, "required": true },
      { "name": "SERVICE_ACCESS_TOKEN", "sensitive": true, "required": true }
    ]
  }
}

Provider selection and consumption

{
  "configProviders": ["infrastructure/config-discovery"],
  "env": [
    { "name": "SERVICE_BASE_URL", "required": true },
    { "name": "SERVICE_ACCESS_TOKEN", "required": true }
  ]
}

Command output

{
  "version": 1,
  "values": [
    {
      "name": "SERVICE_BASE_URL",
      "value": "http://service.internal",
      "sensitive": false,
      "source": "service-discovery"
    }
  ],
  "warnings": []
}

The command runs from the provider directory with a bounded environment containing workspace and provider locators plus the provider's declared configuration. Ploinky removes master keys, agent request secrets, Router authority values, publication credentials, TURN credentials, and reserved PLOINKY_* names. Output names must match the provider allowlist and cannot collide with core-owned topology values or generated secrets. Provider metadata records only names, sources, warnings, and redaction markers; returned values never appear in that metadata.

Isolation and mounts

Runtime preparation mounts only the agent code, selected project path, declared volumes, dependency cache, and persistent home required by the manifest and profile. Profiles choose mount modes; development defaults code and skills mounts to read-write, while QA and production default them to read-only.

An agent container that must launch its own Podman runtime can declare containerSecurity.nestedPodman: true. Ploinky admits this root-only manifest setting only for a container running inside a marked Box, rejects it together with privileged, and renders a fixed capability, device, label, and seccomp contract. Other runtime backends and containers outside the Box cannot request it.

Ploinky resolves agent environment entries from the selected manifest, profile, workspace variables, and approved startup providers. Reusable secrets remain outside the registry and logs. Fresh credentials used for a private interaction are generation-bound and delivered only through the confined channel.

The outer Box exposes only the Router loopback TCP surface and LiveKit UDP. Agent ports, including the default MCP port 7000, remain private to the Box. Reachability to the private Router does not grant request authority: the Router still verifies the caller, active generation, route policy, and request binding.