01
Structured, not shell
Mechanics does not interpret arbitrary shell pipelines over SSH. It accepts typed platform commands.
01 · Why agents
Deploy agents need boundaries
Modern coding agents can build applications, fix bugs, write tests, and iterate quickly. But production-like deployment requires constrained authority, repeatable workflows, and observable state. Mechanics gives agents explicit platform verbs instead of raw infrastructure access.
02
One command, one intent
Each SSH connection carries a clear operation: create a repo, wait for a build, update an app, inspect a route.
03
Artifacts over mystery
Mutations leave behind durable artifacts: Git commits, image tags, manifests, Kubernetes state, or DNS checks.
04
Same surface for humans
Human operators can run the same commands, inspect the same state, and recover using familiar GitOps tools.
02 · Open source substrate
Not another custom platform stack
Mechanics is intentionally thin. It gives agents a safe command surface, then relies on well-maintained, widely adopted open-source systems for source control, CI, images, deployment, networking, and data services.
Git and collaboration
Repositories, SSH remotes, web review, package registry, and the visible history of agent work.
Container builds
Forgejo Actions builds Docker images and publishes immutable tags to the registry.
Runtime substrate
Apps run as ordinary workloads in namespace-scoped tenant environments.
GitOps reconciliation
Deployment state is committed to Git and continuously reconciled into the cluster.
HTTP routing
Public routes are standard HTTPRoute resources with backend and TLS diagnostics.
PostgreSQL addons
Databases are managed as Kubernetes-native PostgreSQL clusters with typed connection secrets.
03 · Agent workflow
A safe agent workflow
Code to public service
An agent does not need cloud console access, cluster credentials, registry passwords, or Argo CD tokens. Mechanics translates bounded commands into source, image, deployment, and route state.
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 build wait --commit <sha>
ssh -T mechanics.run -- app create myapp --repo myapp --tag <sha>
ssh -T mechanics.run -- app -a myapp wait --tag <sha>
ssh -T mechanics.run -- route -a myapp create04 · Human transparency
Agent work, human visibility
Mechanics is built so a human can understand what happened after every agent action. The agent uses a constrained command surface; the platform records the work in systems operators already know how to inspect.
Source is visible
Review the exact repository, commit history, and workflow files an agent created or changed.
Builds are replayable
Inspect CI status, logs, image metadata, and the commit that produced each deployable artifact.
Desired state is committed
Apps, overlays, addons, and routes are represented as files with normal Git history.
Cluster state is summarized
App and route inspection reports sync, health, pods, events, endpoints, TLS, and diagnostics.
05 · Platform verbs
Small verbs agents understand
Where agents create source
Create private repositories, scaffold CI, inspect builds, and list image tags.
The build artifact to deploy
Agents can wait for immutable image tags before asking the runtime to roll forward.
The declarative runtime unit
An app is a Kustomize base plus one overlay per instance, reconciled by Argo CD.
Managed dependencies
Provision PostgreSQL without handing agents database administrator or infrastructure credentials.
Public HTTPS exposure
Expose a service through Gateway API and inspect backend readiness, TLS, and route acceptance.
Human-owned DNS proof
Custom domains require a DNS CNAME challenge; agents delegate DNS ownership instead of guessing credentials.
06 · Safety boundaries
Constrain capable agents
The point is not to make agents all-powerful. The point is to give them enough platform agency to complete useful software work while keeping authority 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 -- route -a myapp info
ssh -T mechanics.run -- domain check www.example.com Operational rule: agents get typed platform operations, not raw infrastructure.
Humans keep the ability to inspect Git, builds, manifests, runtime health, and public exposure.
07 · Bottom line
Agent speed, human audit
Mechanics is fast enough for autonomous coding loops and explicit enough for operators: a narrow SSH API for agents, backed by GitOps artifacts humans can review, reproduce, and override.