README
¶
Ploy — Migs Orchestrator and Control Plane
Ploy is a workstation‑first orchestration stack for code‑mig (Migs) workflows. It consists of:
ploy— a CLI for submitting migs runs, following logs, and administering clusters.ployd— the control-plane daemon with scheduler, HTTP/SSE API, PKI, and PostgreSQL-backed storage.ployd-node— lightweight worker nodes that execute jobs in ephemeral workspaces.
Ploy uses a server/node split with PostgreSQL for state and mTLS for all control‑plane traffic. Nodes clone repositories shallow on-demand and upload diffs/logs/artifacts back to PostgreSQL.
Install
Homebrew (macOS/Linux):
brew install --cask iw2rmb/ploy/ploy
Direct download: latest release
Build from source:
make build
Quick Start
export PLOY_DB_DSN='postgres://ploy:ploy@localhost:5432/ploy?sslmode=disable'
export PLOY_OBJECTSTORE_ENDPOINT='http://localhost:3900'
export PLOY_OBJECTSTORE_ACCESS_KEY='...'
export PLOY_OBJECTSTORE_SECRET_KEY='...'
docker compose -f /Users/v.v.kovalev/@scale/ploy-lib/images/docker-compose.yml up -d
Submit and follow a run:
ploy run ./mig.yaml example/repo:main --pull
Documentation
- API schema:
docs/api/OpenAPI.yaml - Environment variables:
docs/envs/README.md - Runs:
docs/runs.md - Migs lifecycle:
docs/migs-lifecycle.md - TUI usage:
docs/how-to/tui-navigation.md - Java dependency usage extractor:
docs/how-to/java-dependency-usage-extractor.md
License: MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
assets/ployd-node
Package ploydnodeassets reserves the node asset package path.
|
Package ploydnodeassets reserves the node asset package path. |
|
ploy
command
|
|
|
ployd
command
|
|
|
ployd-node
command
|
|
|
internal
|
|
|
blobstore
Package blobstore provides an interface for object storage operations.
|
Package blobstore provides an interface for object storage operations. |
|
blobstore/mock
Package mock provides an in-memory implementation of blobstore.Store for testing.
|
Package mock provides an in-memory implementation of blobstore.Store for testing. |
|
blobstore/s3
Package s3 provides an S3-compatible implementation of blobstore.Store.
|
Package s3 provides an S3-compatible implementation of blobstore.Store. |
|
cli/config
overlay.go implements local config.yaml overlay loading and deterministic merge for the Hydra envs/in/out/home contract.
|
overlay.go implements local config.yaml overlay loading and deterministic merge for the Hydra envs/in/out/home contract. |
|
cli/logs
Package logs provides a shared log printer for CLI commands that consume enriched log events from the job-scoped SSE stream.
|
Package logs provides a shared log printer for CLI commands that consume enriched log events from the job-scoped SSE stream. |
|
cli/migs
Package migs provides CLI client implementations for Migs operations.
|
Package migs provides CLI client implementations for Migs operations. |
|
cli/pull
mig_pull.go implements the `ploy mig pull` subcommand for pulling Migs diffs into the current git worktree based on mig project context.
|
mig_pull.go implements the `ploy mig pull` subcommand for pulling Migs diffs into the current git worktree based on mig project context. |
|
cli/run
run_artifact.go isolates artifact download and fetching logic.
|
run_artifact.go isolates artifact download and fetching logic. |
|
cli/specpayload
mig_run_spec.go separates spec file handling from mig run execution.
|
mig_run_spec.go separates spec file handling from mig run execution. |
|
domain/api
Package api defines canonical domain-level DTO types for shared API payloads.
|
Package api defines canonical domain-level DTO types for shared API payloads. |
|
domain/types
Package types provides domain value-type helpers and interfaces.
|
Package types provides domain value-type helpers and interfaces. |
|
nodeagent
claimer_loop.go contains the claim loop orchestration and backoff logic.
|
claimer_loop.go contains the claim loop orchestration and backoff logic. |
|
pki
Package pki provides certificate authority and certificate management utilities for the simplified Ploy server/node mTLS architecture.
|
Package pki provides certificate authority and certificate management utilities for the simplified Ploy server/node mTLS architecture. |
|
server/auth
Package auth provides role-based request authorization for the server.
|
Package auth provides role-based request authorization for the server. |
|
server/blobpersist
Package blobpersist provides a service for persisting blob data with coordinated database metadata and object storage writes.
|
Package blobpersist provides a service for persisting blob data with coordinated database metadata and object storage writes. |
|
server/handlers
Package handlers implements HTTP handlers for the ploy server API.
|
Package handlers implements HTTP handlers for the ploy server API. |
|
store
Package store provides PostgreSQL-backed data persistence using pgx and sqlc.
|
Package store provides PostgreSQL-backed data persistence using pgx and sqlc. |
|
store/ttlworker
Package ttlworker provides a background worker for purging expired data from the database.
|
Package ttlworker provides a background worker for purging expired data from the database. |
|
store/wavescheduler
Package wavescheduler provides a background worker for scheduling queued runs within waves.
|
Package wavescheduler provides a background worker for scheduling queued runs within waves. |
|
testutil/workflowkit/ids
Package ids provides cycle-safe domain key types for cross-module orchestration scenario assembly.
|
Package ids provides cycle-safe domain key types for cross-module orchestration scenario assembly. |
|
tui/joblist
Package joblist implements the JobList TUI domain component.
|
Package joblist implements the JobList TUI domain component. |
|
workflow/backoff
Package backoff provides centralized retry and backoff utilities using github.com/cenkalti/backoff/v5.
|
Package backoff provides centralized retry and backoff utilities using github.com/cenkalti/backoff/v5. |
|
workflow/contracts
build_gate_config.go defines Build Gate validation configuration types.
|
build_gate_config.go defines Build Gate validation configuration types. |
|
workflow/stackdetect
Package stackdetect provides filesystem-only, deterministic detection of technology stacks from build files.
|
Package stackdetect provides filesystem-only, deterministic detection of technology stacks from build files. |
|
workflow/step
build_gate_image_resolver.go implements the Build Gate image catalog resolver.
|
build_gate_image_resolver.go implements the Build Gate image catalog resolver. |
|
tools
|
|
|
autocomplete
command
|
|
|
gen_ac
command
|
|
|
gencomp
command
|
|
|
gentoken
command
|
Click to show internal directories.
Click to hide internal directories.