How it works

You don't need this page to use Allocus. It's here because "just say deploy this to allocus" is the kind of promise that ought to come with a look under the lid — and because a handful of things that seem arbitrary (why you build locally, why there's no SSH key, why a deploy takes a moment to land) make immediate sense once you see the shape.

When you say "deploy this to allocus", Claude isn't doing anything magic. It runs the same allocus CLI you can run yourself, which drives a small and fairly boring pipeline.

flowchart LR
    subgraph laptop["Your laptop"]
      cli["allocus CLI<br/>(or Claude skill)"]
    end
    subgraph cp["Allocus control plane"]
      api["deploy broker"]
      reg["container registry<br/>(your private namespace)"]
    end
    subgraph box["Your box (a VM)"]
      agent["allocus-agent"]
      traefik["Traefik<br/>(HTTPS edge)"]
      app["your app<br/>container"]
    end

    cli -- "1. build + push image" --> reg
    cli -- "2. deploy request (API key)" --> api
    api -- "3. queue instruction" --> agent
    agent -- "4. pull image" --> reg
    agent -- "5. run container" --> app
    traefik -- "6. route + TLS" --> app

Three properties of that picture are the whole design:

• You never touch the box directly. No SSH key, no VM address to look after. Deploys are brokered — the control plane is the only thing that talks to your box.
• The box pulls; nothing is pushed at it. Your box reaches out and asks whether there's work. That's why its management surface can stay completely closed, and it's a network fact rather than a promise — see can anyone log into my box.
• HTTPS is already working. Your box holds a wildcard certificate for *.<you>.allocus.dev, issued while the box is being provisioned rather than on first request. Every app you deploy is TLS-valid immediately, with no per-app certificate wait.

A deploy, step by step

sequenceDiagram
    autonumber
    participant You as You / Claude
    participant CLI as allocus CLI
    participant Reg as Registry
    participant CP as Control plane
    participant Agent as Box agent
    participant Traefik

    You->>CLI: allocus deploy
    CLI->>CLI: docker buildx build --platform linux/amd64
    CLI->>Reg: push image (immutable git-SHA tag)
    CLI->>CP: deploy request (API key + app + SHA)
    CP->>CP: resolve your box, queue instruction
    Note over Agent: agent polls for work
    Agent->>CP: any instructions?
    CP-->>Agent: deploy <app> @ <SHA>
    Agent->>Reg: pull image
    Agent->>Agent: run container (compose up)
    Agent->>Traefik: register route <app>.<you>.allocus.dev
    Traefik-->>You: https://<app>.<you>.allocus.dev is live
    Agent->>CP: report result

1. Build, on your machine

allocus deploy reads your allocus.yaml — for a simple app, just a name and a port — and builds the Dockerfile in your repo.

Boxes run linux/amd64, so the CLI always cross-builds for that target even on an Apple-Silicon laptop. The image is tagged with your current git SHA, which is what makes every deploy immutable and every rollback exact.

Why your machine and not ours? Two reasons that both benefit you. Your box spends its memory running your apps instead of competing with a build, which matters a lot on a 2 GB machine. And your Docker build context — your source, your .env files, whatever else is in the directory — never leaves your control except as a finished image.

The cost is that you need Docker with Buildx locally, and the CLI checks for it up front rather than failing halfway through.

2. Push, to your own registry namespace

The image goes to your own private namespace in the Allocus container registry. The CLI fetches short-lived registry credentials for this, so there is no registry login for you to create, store, or rotate.

3. Broker

The CLI hands the control plane an app name and an image SHA, authenticated with your API key. The control plane looks up your box and queues an instruction for it.

This indirection is the reason you never need your box's address or a credential to it. It's also why your API key is worth protecting: it's the one thing that identifies you to the broker, and anyone holding it can deploy to your box.

4–5. Pull and run, on your box

Your box's agent polls every five seconds, so it picks the instruction up almost immediately, and then:

• fetches that app's secrets on a separate request, so secret values never ride inside a deploy instruction and never appear in the stored deploy record,
• writes them and the pinned image tag to the app's .env, readable only by root,
• pulls the image using the box's own auto-rotated registry credential,
• brings the containers up, and waits for the healthcheck to pass before calling the deploy a success.

If it's the app's first deploy, the agent creates it from scratch. There's no separate "add an app" step, and nothing to click.

That health gate is why allocus deploy --wait can tell you what went wrong instead of just "queued" — see when something's wrong.

6. Route and TLS

Traefik, the edge proxy on your box, picks up the new container and starts routing <app>.<you>.allocus.dev to it over HTTPS. The subdomain is claimed the first time you deploy that app; you never touch DNS and never wait for a certificate.

What Claude adds on top

Almost nothing, deliberately. Before running allocus deploy, the skill:

1. writes a Dockerfile if your repo doesn't have one,
2. writes an allocus.yaml — the app's name and port, or a whole services: stack if you have a database,
3. runs the deploy and tells you the URL.

Everything after that is the pipeline above. You can watch it happen, and you can do it by hand at any point without losing anything.

Why it's built this way

Choice	What it buys you
One VM per developer	"One price = one box" is exact. Overloading your box is your own problem, so there are no shared-cluster quotas to argue with and no noisy neighbour.
Brokered deploys, no SSH, no IPs	You never hold a credential to a machine, and there's no attack surface on the box for you to keep patched.
Immutable git-SHA tags	Deterministic deploys, and a rollback that reruns the identical image rather than rebuilding and hoping.
Build on your machine	Your box's memory goes to running apps; your build context stays local.
Secrets fetched separately	A stored deploy record can be kept for history without ever containing a secret value.
Wildcard HTTPS, pre-issued	Every app is TLS from its first request, with zero certificate work and no first-deploy wait.

What happens when something is down

Worth knowing, because the answer is better than you'd expect from a one-person platform:

If the control plane is down — Traefik and your running containers are entirely self-contained on your box. Your apps keep serving traffic. You can't deploy, roll back, or fetch logs until it's back, but nothing that's already live is affected.

If your box goes quiet — the dashboard shows it as stale or offline, and the apps on it stop answering, because that's where they run. Deploys queue rather than failing, and run when it returns.

If your box's disk is lost — you redeploy from your git SHAs, which is quick, and you lose anything that only existed in a volume, which is not. That asymmetry is the reason backups are your job and the reason the docs keep saying so.