Agent control plane Structured SSH · Git receipts · Human inspection
Agent-first deploys · SSH in, HTTPS out

Start with ssh mechanics.run

One structured SSH command at a time: create an app, push code, build, deploy, and expose a route. No kubeconfig required.

Get started See workflow
Audience · Agents first Control · Human inspectable State · GitOps receipts
1
intentional platform command per SSH connection
0
kubeconfig files needed by coding agents
6
core resource commands: app, addon, secret, route, domain, quota
∞
human auditability through Git, images, events, and routes
Start here

Getting started with mechanics.run

First command: ssh -T mechanics.run -- -h. Mechanics is not a shell; it is a small SSH command surface for app delivery.

Front door: ssh mechanics.run. Everything else is a receipt: Git commits, image tags, manifests, route state.
  1. Open SSH Read help, sign up, inspect identity.
  2. Create an app Get a Forgejo repo and GitOps declaration.
  3. Push code Add CI and agent instructions.
  4. Ship Build, deploy by SHA, expose HTTPS.
Loop: inspect, change, push, build, deploy, route.
agent getting started 

ssh -T mechanics.run -- -h
ssh -T mechanics.run -- user signup
ssh -T mechanics.run -- whoami

ssh -T mechanics.run -- app 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 -- app -a myapp scaffold ci
ssh -T mechanics.run -- app -a myapp scaffold agents
git pull --ff-only origin main

sha=$(git rev-parse HEAD)
ssh -T mechanics.run -- app -a myapp build wait --commit "$sha" --logs-on-failure
ssh -T mechanics.run -- app -a myapp deploy --tag "$sha"
ssh -T mechanics.run -- app -a myapp wait --tag "$sha" --json
ssh -T mechanics.run -- route -a myapp create
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 typed platform commands instead of raw infrastructure access.

01

Structured, not shell

Mechanics does not interpret arbitrary shell pipelines over SSH. It accepts typed platform commands.

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

Thin control plane, visible systems

Mechanics gives agents a safe command surface, then records the work in systems humans already know how to inspect: Git, CI logs, image tags, GitOps manifests, Argo CD health, Kubernetes resources, Gateway routes, and addon secrets.

Forgejo

Source and review

Repositories, SSH remotes, commits, workflow files, and package metadata show exactly what changed.

Actions

Build evidence

CI status, logs, image metadata, and full-SHA tags connect every deployment to the commit that produced it.

Argo CD

GitOps reconciliation

Apps, overlays, addons, and routes are committed as files and reconciled into the tenant namespace.

Kubernetes

Runtime state

Deployments, pods, events, services, and addon resources remain ordinary cluster objects with summarized health.

Gateway API

Public routing

HTTPRoute resources expose apps with TLS, backend readiness, route acceptance, and certificate diagnostics.

Addons

Managed services

CloudNativePG, SeaweedFS, Valkey, and NATS provide typed backing services through Kubernetes-native resources.

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.

agent deploys myapp 

ssh -T mechanics.run -- app 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 -- app -a myapp scaffold ci
ssh -T mechanics.run -- app -a myapp build wait --commit <sha>

ssh -T mechanics.run -- app -a myapp deploy --tag <sha>
ssh -T mechanics.run -- app -a myapp wait --tag <sha>
ssh -T mechanics.run -- route -a myapp create
04 · Command surface

A small set of platform commands

app

Source, builds, and deploys

Create a source repository, scaffold CI, wait for builds, deploy image tags, and inspect runtime state.

addon

Managed backing services

Provision databases, buckets, caches, and messaging through typed parameters and Kubernetes secrets.

secret

Application configuration

Expose OpenBao-backed values to apps through ExternalSecret manifests without handing agents cluster credentials.

route

Public HTTPS endpoint

Expose an app through Gateway API and inspect backend readiness, TLS, and route acceptance.

domain

Verified custom hostnames

Claim hostnames with a DNS CNAME challenge while leaving DNS changes in the domain owner's hands.

quota

Operational limits

Inspect CPU, memory, storage, object counts, defaults, and usage before changing the workspace.

05 · 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.

inspect before and after 

ssh -T mechanics.run -- whoami
ssh -T mechanics.run -- app list
ssh -T mechanics.run -- app -a myapp info
ssh -T mechanics.run -- route -a myapp info
ssh -T mechanics.run -- domain status 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.