Mechanics 0.3.1: repo owns source, app owns runtime

Mechanics 0.3.1 makes the deployment model match the way the system actually behaves: source repositories and builds are one concern, deployed runtime state is another. The repo command owns Forgejo repositories, CI scaffolding, builds, image tags, build restarts, and source cleanup. The app command owns image declarations, deployments, instances, sync, logs, events, and readiness.

This is the ADR-017 split in user-facing form. It removes the old ambiguity where app sometimes meant source repository and sometimes meant running application.

The normal loop now starts with repo

A new code-backed app starts by creating a source repository, pushing code, and waiting for CI to publish an image. Those steps now live under repo:

source and build


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
sha=$(git rev-parse HEAD)
ssh -T mechanics.run -- repo -r myapp build wait --commit "$sha" --logs-on-failure

Once the image exists, runtime state begins. Create the app declaration, deploy the image tag, wait for readiness, and expose it through a route:

runtime and route


ssh -T mechanics.run -- app create myapp
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 create web --app myapp

Apps can also be image-only

Apps no longer need to imply a Mechanics-managed source repository. If an image already exists, app create myapp --image <image-base> declares that deployable image base directly, and app deploy --tag <tag> selects the tag. That covers external images and manually-built images without inventing a source repository just to satisfy the app model.

Delete means the narrow thing

app delete removes app GitOps and runtime state. It no longer removes source repositories or image packages. Source cleanup is explicit: repo -r myapp delete --dry-run to inspect, then repo -r myapp delete --packages --force when the repository and its matching package artifacts should go away.

Why this matters for agents

The command surface now gives agents a clearer plan. Use repo while changing code and producing images. Use app while changing deployed runtime state. Use route, addon, secret, domain, quota, and usage to inspect or attach the surrounding platform resources.

Repo owns source and images. App owns runtime. The split makes agent actions easier to audit and easier to undo.