First command: ask for help
Mechanics is not a shell. It is a small SSH command surface for app delivery.
Every command answers -h without side effects, so an agent can
map the entire surface before touching anything.
ssh mechanics.run. Everything else is a receipt:
Git commits, image digests, manifests, route state.
Agent skill: mechanics.run/SKILL.md.
- Open SSH Trust the host key once, read help, sign up with GitHub, finish visible onboarding.
- Create a repo Get a Forgejo source repository with an SSH remote.
- Push code Scaffold CI and agent instructions, push to main.
- Ship Release the latest successful build, expose HTTPS, check reachability.
# clean machine: accept the mechanics.run host key on first connect
ssh -o StrictHostKeyChecking=accept-new -T mechanics.run -- -h
ssh -T mechanics.run -- user signup
# approve GitHub code
ssh -T mechanics.run -- setup | sh
ssh -T mechanics.run -- whoami
ssh -T mechanics.run -- repo create myapp
git remote add origin ssh://git@forgejo.mechanics.run/<user>/myapp.git
git branch -M main
git push -u origin main
ssh -T mechanics.run -- repo -r myapp scaffold ci
ssh -T mechanics.run -- repo -r myapp scaffold agents
git pull --ff-only origin main
ssh -T mechanics.run -- app create myapp --from-repo myapp
ssh -T mechanics.run -- app -a myapp release --latest-success --json
ssh -T mechanics.run -- route create web --app myapp
ssh -T mechanics.run -- route check webPreview environments that clean themselves up
Mechanics v0.4.1 adds expiring app instances. Add --ttl and
--route to a deploy or clone, get a short-lived HTTPS URL,
and let the scheduler remove the instance and its routes after the stamp
expires.
ssh -T mechanics.run -- app -a myapp -i pr-42 deploy \
--tag abc1234 --ttl --route --json
ssh -T mechanics.run -- app -a myapp -i pr-42 wait --tag abc1234 --json
ssh -T mechanics.run -- app -a myapp -i pr-42 info
ssh -T mechanics.run -- route info myapp-pr-42Expiry is GitOps state. The TTL becomes a label and annotation on the instance overlay. The cleanup worker re-reads that overlay before deleting anything, then uses the same teardown path as a manual instance removal.
The route created by --route is ordinary route state too.
Humans can inspect the preview with app info,
route info, Git history, and the redacted audit trail.
From push to public, with receipts
One command drives the whole pipeline: app release observes the
commit build, pins the image to an immutable digest, deploys through GitOps,
and waits for runtime convergence. Every stage leaves an artifact a human can
audit later.
tag@digest target. route check proves public reachability. | exit | state | what the agent does |
|---|---|---|
| 0 | live | Done. The runtime digest matches the pinned image. |
| 2 | progressing | Retry the identical command after retry_after. |
| 3 | blocked · app | App state blocks the release. Fix the app, then release again. |
| 4 | blocked · platform | Platform state blocks the release. Hand off to an operator. |
Every wait is bounded. Release, build, route, secret, and
registry waits share one budget: cap at 60 seconds, re-observe every 5,
and exit 2 with a retry_after and the exact next
command when state is still moving.
No agent on Mechanics ever has to invent a polling strategy. The contract is to retry the same command until it says live.
Focused nouns, fully discoverable
The platform is a focused SSH command surface. Each command documents
itself with -h, takes --json for machine output,
and accepts --comment to annotate intent in the audit trail.
Source and builds
Create Forgejo repositories, scaffold CI and agent files, probe build status by commit, and observe collaborated owner/repo targets.
Release and runtime
Release or deploy images, clone instances, stamp disposable previews with --ttl and --route, read logs and events, diagnose convergence, and print tunnel commands with connect.
Managed backing services
Provision PostgreSQL, S3 buckets, Valkey, and NATS with typed parameters, print generated credentials in text, env, or JSON form, and manage anonymous bucket read prefixes with public-read.
Application configuration
Expose OpenBao-backed values to apps through ExternalSecret manifests. Values are never printed back.
Public HTTPS endpoint
Give a host to an app, bucket asset path, or bucket website, attach more paths under the same host, and verify reachability with route check.
Verified custom hostnames
Claim hostnames with a DNS CNAME challenge while DNS changes stay in the domain owner's hands.
Private image pulls
Store pull credentials for private external registries in OpenBao. Deploys resolve them to imagePullSecrets before any GitOps mutation.
Deployable boundaries
Create named secondary workspaces such as prod, each with its own namespace, quota, GitOps tree, Calico isolation policy, and Istio mesh enrollment.
Identity and repair
Show who the SSH key is, repair account setup with user doctor, and print an opt-in read/debug kubeconfig for workspace inspection and kubectl port-forward.
Limits and consumption
Inspect quota ceilings and per-object limits. Read observed CPU, memory, storage, and network usage per workspace.
Tools you already know
Mechanics is a thin control plane over systems humans already know how to inspect. The transports live in an open provider SDK. Mechanics keeps the product semantics.
Forgejo source of record
Repositories, SSH remotes, commits, and workflow files show exactly what changed.
Forgejo Actions build evidence
CI status, logs, and full-SHA image tags connect every deployment to its commit.
Argo CD reconciliation
Apps, addons, and routes are committed as files and reconciled into the workspace.
Kubernetes runtime
Deployments, pods, events, and services stay ordinary cluster objects with summarized health.
Gateway API + Istio routing and mesh
HTTPRoutes expose apps with TLS, while workspace sidecars add L7 telemetry, mTLS, and scoped xDS config.
Calico workspace isolation
Per-workspace policies deny cross-workspace traffic by default, with public isolation as an explicit live switch.
CNPG · SeaweedFS · Valkey · NATS addons
Typed backing services through Kubernetes-native resources, with per-workspace bucket isolation.
OpenBao + ESO secrets custody
Canonical secret and pull-credential values live in OpenBao and materialize into workspaces, never printed back.
PostgreSQL control-plane memory
Users, SSH keys, signup state, domain claims, and redacted command and tunnel audit events.
Capable agents, narrow authority
The point is not to make agents all-powerful. The point is to give them enough platform agency to finish useful software work while authority stays narrow, inspectable, and recoverable.
ssh -T mechanics.run -- whoami
ssh -T mechanics.run -- repo list
ssh -T mechanics.run -- app -a myapp info
ssh -T mechanics.run -- app -a myapp connect
ssh -T mechanics.run -- route check web --json
ssh -T mechanics.run -- usage --window 24h
ssh -T mechanics.run -- user kubeconfig > kubeconfig.yaml
KUBECONFIG=./kubeconfig.yaml kubectl port-forward svc/myapp-main 8080:80Typed platform operations, not raw infrastructure. Mechanics never interprets shell pipelines. Identity is the SSH public key, and each connection carries one intentional command.
Every authenticated command and workspace tunnel lands in a redacted
audit trail, and agents annotate intent with --comment.
Kubeconfig access is workspace-scoped and debug-oriented: read APIs
plus port-forward, not exec, attach, secrets, or writes.