EasyRunner | Apus Ami

EasyRunner hosts the Apus Gateway as a small containerized app behind its Caddy proxy. This guide assumes an EasyRunner host that runs Podman-compatible Compose apps and terminates HTTPS through Caddy.

Before you begin

An EasyRunner server with a domain routed to it.
The official Apus image (ghcr.io/apus/apus) or your own build.
A persistent config volume for /home/node/.apus.
A persistent workspace volume for /home/node/.apus/workspace.
A strong Gateway token or password.

Keep device auth enabled when possible. If your reverse proxy cannot carry device identity correctly, fix trusted-proxy settings first (see Trusted proxy auth); use dangerous auth bypasses only on a fully private, operator-controlled network.

Compose app

Create an EasyRunner app with a Compose file shaped like this:

services:
  apus:
    image: ghcr.io/apus/apus:latest
    restart: unless-stopped
    environment:
      APUS_GATEWAY_TOKEN: ${APUS_GATEWAY_TOKEN}
      APUS_HOME: /home/node
      APUS_STATE_DIR: /home/node/.apus
      APUS_CONFIG_PATH: /home/node/.apus/apus.json
      APUS_WORKSPACE_DIR: /home/node/.apus/workspace
    volumes:
      - apus-config:/home/node/.apus
      - apus-workspace:/home/node/.apus/workspace
    labels:
      caddy: apus.example.com
      caddy.reverse_proxy: "{{upstreams 1455}}"
    command: ["node", "apus.mjs", "gateway", "--bind", "lan", "--port", "1455"]

volumes:
  apus-config:
  apus-workspace:

Replace apus.example.com with your Gateway hostname. Store APUS_GATEWAY_TOKEN in EasyRunner's secret/environment manager instead of committing it to the app definition. The image binds to loopback by default, so the explicit --bind lan --port 1455 in command is required for Caddy to reach the container.

Configure Apus

Inside the persistent config volume, keep the Gateway reachable only through the proxy and require auth:

{
  gateway: {
    bind: "lan",
    port: 1455,
    auth: {
      token: "${APUS_GATEWAY_TOKEN}",
    },
  },
}

If Caddy terminates TLS for the Gateway, configure trusted-proxy settings for the exact proxy path rather than disabling auth checks globally. See Trusted proxy auth.

Verify

From your workstation:

apus gateway probe --url https://apus.example.com --token <token>
apus gateway status --url https://apus.example.com --token <token>

From the EasyRunner host, GET /healthz (liveness) and GET /readyz (readiness) need no auth and back the image's built-in container health check. Also check the app logs for a listening Gateway and no startup SecretRef, plugin, or channel auth failures.

Updates and backups

Pull or build the new Apus image, then redeploy the EasyRunner app.
Back up the apus-config volume before updates. It holds apus.json, shared auth in state/apus.sqlite, agent-local profiles in agents/<agentId>/agent/apus-agent.sqlite, and installed plugin package state.
Back up apus-workspace if agents write durable project data there.
Run apus doctor after major updates to catch config migrations and service warnings.

Troubleshooting

gateway probe cannot connect: confirm the Caddy hostname points at the app and that the container listens on 0.0.0.0:1455.
Auth fails: rotate the token in EasyRunner secrets and the local client command together.
Files are root-owned after restore: the image runs as node (uid 1000); repair the mounted volumes so that user can write /home/node/.apus and /home/node/.apus/workspace.
Browser or channel plugins fail: check whether the required external binaries, network egress, and mounted credentials are available inside the container.