Home

squarepeg

squarepeg runs a docker run-style command as a Kubernetes Pod or Job. It creates the resource, streams its output to your terminal like a normal local command, waits for it to finish, and exits with the same exit code the container exited with.

squarepeg run alpine echo "hello from a pod"

That one command: builds a Pod manifest, applies any resource requests/limits and passthrough config you've set up, creates it in your current kubeconfig context, streams stdout/stderr back to you as it runs, waits for it to terminate, deletes it, and exits with its exit code — 0 on success, non-zero otherwise.

Why

Running a one-off container as a Kubernetes workload normally means writing a Pod or Job manifest by hand, kubectl apply-ing it, then separately watching, kubectl logs -f-ing, and kubectl delete-ing it afterwards. squarepeg collapses that whole loop into a single command with docker run ergonomics, while still giving you full access to arbitrary Kubernetes fields (node selectors, tolerations, service accounts, PVCs, GPU resources, ...) through a layered config file.

Pages

Page	What's in it
Getting Started	Install, first run, the two things every new user needs
CLI Reference	Every flag on squarepeg run and squarepeg config, tables
Configuration	The layered config file system: locations, precedence, schema, profiles
Environment Variable Interpolation	${VAR} / ${VAR:-default} references inside config YAML
Docker Compatibility	What subset of docker run is supported, what's rejected and why
Execution Lifecycle	What actually happens between squarepeg run and your prompt coming back: manifest building, naming, waiting, log streaming, exit codes, cleanup, signals
Troubleshooting	Every error condition squarepeg detects and what it tells you to do about it
Development	Running the test suite, linting, integration tests, CI

At a glance

Modes	Pod (default) or Job (--mode job)
Config	Layered YAML, Nextflow-style: defaults → ~/.config/squarepeg/config.yaml → $SQUAREPEG_CONFIG → --config (repeatable) → CLI flags
Cluster access	Standard kubeconfig resolution ($KUBECONFIG, ~/.kube/config, current context), falling back to in-cluster service account config if squarepeg is itself running as a pod
Cleanup	Deletes the Pod/Job after it finishes, by default (--keep to retain)
Output	Container stdout/stderr streamed live to your terminal; squarepeg's own messages go to stderr only
Exit code	Mirrors the container's exit code (or 125 if squarepeg itself couldn't determine it, matching docker run's own convention)
Interrupt	Ctrl+C deletes the resource by default; press twice to abandon it running