Skip to content

Deploy by hand (CLI)

The Claude skill is convenient, but it's only a wrapper around the allocus CLI. If you'd rather drive the deploy yourself — or you're deploying from a machine without Claude — here's the whole thing.

Prerequisites

  • Docker with buildx (bundled with modern Docker Desktop / Engine).
  • A launched box and your API key (from your dashboard).
  • The CLI installed and logged in: 
    curl -fsSL https://allocus.dev/install | sh
allocus login

1. Describe the app

From your app's repo, scaffold the two files a deploy needs:

allocus init --name my-app --port 8080

This writes:

  • allocus.yaml — the app manifest. It's intentionally tiny: 
    name: my-app
port: 8080
  • Dockerfile — a starter, only if you don't already have one. Replace it with your app's real Dockerfile.

--name defaults to the current directory name; --port defaults to 8080.

2. Make sure your Dockerfile fits

There's essentially one rule: your app must listen on the port from allocus.yaml, and the Dockerfile must EXPOSE it. A minimal example:

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8080
CMD ["python", "app.py"]  # must bind 0.0.0.0:8080

Bind to 0.0.0.0, not localhost

Inside the container your app must listen on 0.0.0.0:<port>, not 127.0.0.1, or Traefik can't reach it.

3. Deploy

allocus deploy

That single command:

  1. builds your Dockerfile for linux/amd64 and tags it with your git SHA,
  2. pushes it to your private registry namespace,
  3. calls the deploy broker, which instructs your box to pull and run it.

A moment later it's live:

✓ deploy queued (pending). Live shortly at https://my-app.<you>.allocus.dev

Note the word queued — that's all a bare allocus deploy promises. Add --wait and it blocks until your box reports the app healthy, or names the service that failed:

allocus deploy --wait

Use it whenever you care about the answer, and always in CI.

Deploy more apps by repeating this in each repo — they share the box, each at its own subdomain.

Rolling back

Every deploy is tagged with an immutable git SHA, so a rollback is just redeploying an earlier one (no rebuild):

allocus rollback <sha>

Checking on things

allocus status      # your box + apps at a glance, plus CPU/memory/disk
allocus logs        # this repo's app, straight from the container
allocus apps        # just the app list

There's no SSH and no exec — the box is firewalled to web traffic, and logs works by asking its agent to fetch the output for you. That covers most of what you'd have opened a shell for; troubleshooting covers the rest.

For the full command list, see the CLI reference. To understand what each step is doing under the hood, see How it works.