Architecture and boundaries
Components and responsibilities
| Component | Responsibility |
|---|---|
Operator CLI (pyplines) | Calls the API to deploy, execute, inspect, and administer |
| Server | Owns execution state, revisions, authorization, policies, and retained evidence |
| Runner | Enrolls with the server and executes inspected Action images using Docker |
| OCI registry | Stores versioned Action images that deployments resolve to digests |
| Action CLI and SDK | Create and publish new operations when existing Actions are insufficient |
The server stores execution state in SQLite. Embedded NATS JetStream transports invocation IDs to runners, not secrets. Logs live in bounded filesystem storage. The server does not need a Docker socket; runners do.
Execution and concurrency
Steps execute in declaration order. Conditions can skip steps; there is no parallel branch or loop construct. One Environment executes one Run's attempt at a time. Separate Environments can execute concurrently when their pools have available runners and capacity.
The Environment's platform must match its runner pool and Action images. Use separate pools for different architectures. Actions with network access need the configured network on the runner.
Isolation and trust
Runners use pinned, inspected images with the fixed SDK entrypoint, a non-root user, a read-only root filesystem, dropped capabilities, and resource limits. Action containers do not receive the Docker socket.
Actions are still trusted code: an Action receiving credentials can use them against external systems. Review its behavior and permissions before adopting it. Sensitive steps suppress logs and protect results; see context and secrets.
Recovery guarantees
A retry retains prior attempts and does not replay successful steps. It cannot undo effects already performed by a failed Action. Cancellation requests execution to stop; it is not rollback.
A runner losing connectivity does not make its work eligible for reassignment. Execution becomes uncertain until the owning runner establishes that its container stopped. Permanent host loss has no automatic recovery path; external fencing and a separately designed administrative recovery process are required. See recovery.
Current boundaries
Pyplines currently exposes a CLI and API, with no web console, built-in schedules, webhooks, lifecycle hooks, Change Requests, loops, or arbitrary script steps. It does not provide an infrastructure provisioning/state engine. Actions may interact with external services, but their capabilities must be supplied and documented separately.
There is no built-in backup scheduler or installer utility. Administrators operate the services and back up the complete data directory while the server is stopped.