Mechanics 0.4.1: disposable previews expire themselves
App instances can now carry a TTL and a generated route, so agents can create short-lived preview URLs while GitOps remains the authority and cleanup removes the instance and its routes.
Release notes and design decisions
Engineering log
What shipped, why it is shaped that way, and what an agent should do differently. One entry per meaningful change to the platform.
Mechanics 0.3.37: workspace tunnels over plain ssh -L
Private workspace Services and Pods are now reachable through stock OpenSSH local forwarding, with destination authorization, resolution, and audit kept under the SSH key identity boundary.
Routes compose: app paths and public bucket assets
A route now owns one host and composes app and bucket-backed paths as named attachments, while bucket public reads stay an explicit, read-only addon policy.
Mechanics sheds its transports
Ten releases moved every external-system transport (Forgejo, OpenBao, GitHub, S3, VictoriaMetrics, OCI registries, Kubernetes) into operation-based mechanics-sdk providers, and the kubectl binary is gone.
app release: commit to live in one bounded loop
One idempotent command observes the build, pins the image by digest, deploys, waits for convergence, and optionally verifies the public route, with stable exit codes agents can loop on.
An audit trail agents can annotate
Every authenticated SSH command now lands in PostgreSQL as a redacted audit event, and agents can attach a --comment explaining why they ran it.
Workspaces are product names, namespaces are internal
Secondary workspaces are selected as -w prod, Kubernetes namespace names moved behind the API, and machine-readable output gained a structured workspace shape.
Private images and collaborated repos
Registry credentials became workspace state, image pulls became deploy preflight, and Forgejo collaboration now reaches the deploy path: inspect a shared repo and release its image into your own workspace.
kubectl for debugging, not deploying
user kubeconfig prints an opt-in, read-only kubeconfig whose short-lived credentials refresh over Mechanics SSH. Inspection without handing out cluster secrets.
Mechanics 0.3.2: agent-friendly signup
Unknown-key signup no longer blocks the first SSH session: Mechanics watches GitHub approval in the background and keeps onboarding visible in the foreground.
Mechanics 0.3.1: repo owns source, app owns runtime
The public workflow now matches ADR-017: repo commands own source, CI, builds, images, and cleanup while app commands own image declarations and runtime state.
Mechanics 0.1.57: addons become a service catalog
A focused look at the expanded addon catalog: PostgreSQL, S3-compatible buckets, Valkey caches, and NATS JetStream.
Deleting safely in an agent-run platform
How dry runs, structured plans, user-commit protection, and repo deletion cascade make destructive operations inspectable.
Debugging deployments from the control plane
How app info, logs, events, route diagnostics, image drift, and smoke-test headers made operations inspectable over SSH.
Custom domains: from claim to CDN-safe TLS
How Mechanics custom domains evolved before 0.1.57: CNAME proof, CDN-safe TLS, domain attach, diagnostics, and safe detach.
Routes belong in GitOps too
The route layer moved from basic exposure to GitOps-managed network state with Gateway API, TLS, redirects, sync, and wait.
GitOps is the receipt layer for agents
How the per-user gitops repo became the audit trail for apps, routes, addons, and user-visible platform writes.
Self-service without shared cluster credentials
Mechanics gives users isolated namespaces, Argo CD projects, deploy keys, rollback access, and addon quotas without handing out kubeconfig.
One app, many instances
How Mechanics introduced app instances with base and overlay layouts for main, prod, preview, and pull-request style deployments.
Agents need commands, not shells
Why Mechanics shaped its SSH surface around explicit verbs, safe help, named flags, and shell-syntax rejection.
One SSH key from signup to git push
How signup, provisioning, and SSH client configuration became self-service and agent-friendly.
Putting git SSH behind the same control plane
Mechanics started relaying git SSH traffic to Forgejo, making clone, fetch, and push part of the same authenticated platform front door.
The Mechanics deployment loop: commit to HTTPS
How Mechanics connected CI, image publishing, build waits, app deploys, and public routes into one scriptable path.
Mechanics updates start here
A short note on what this update stream will track as Mechanics evolves.