Troubleshooting

Troubleshooting

The first stop is always:

make logs            # tail the orchestrator
bash scripts/smoke.sh # end-to-end check with plain-language verdicts

The stack

make up succeeds but the console shows 502 — the console's nginx resolves the API per-request through Docker's DNS, so this usually means the api container is still starting or crashed: docker compose ps, then make logs.

First run is slow — the sandbox desktop image builds once (~minutes). Subsequent make up reuses it.

Port collisions — the console binds :8081, the orchestrator :8080. Both are compose-level and easy to remap in docker-compose.yml.

Sandboxes

Instance stuck in provisioning — docker logs af-<first-12-of-id>. The usual causes: the sandbox image isn't built (make sandbox), or the machine is out of memory (each sandbox reserves its tier's RAM with swap off, so overcommit fails fast rather than thrashing).

"image unavailable" naming a make target — run exactly the target the error names (make sandbox, make sandbox-vm, make sandbox-dev). The error is derived from the tag, so it's telling the truth.

Agent sees a black screen — the desktop takes a few seconds after running; /observe retries. If it persists, the instance's logs will show which supervisord service failed.

A policied instance can't reach something it should — read Egress-Policies first; the two classic causes are a CDN hostname that rotated out of a resolve-once allow-list, and block_local correctly blocking a private address you forgot was private.

The VM tier

VM instance takes minutes to reach running — no /dev/kvm on the host (Docker Desktop, CI) means TCG software emulation. Same guest, slow boot; the runner's log says which mode it chose. On bare-metal Linux with KVM it's fast.

make sandbox-vm fails — it depends on the base image; run make sandbox first (the target normally chains it).

Models

Agent does nothing / every step errors — fleetctl doctor, then check the provider in Console → Engines. The most common cause is an Ollama base URL that's reachable from your browser but not from inside Docker (use the LAN IP, not localhost — localhost inside a container is the container).

Steps are slow — a big local model on CPU is slow per turn. The loop is patient; pick a smaller vision model or a GPU host for snappier runs.

Phone app

No push notifications — FCM/APNs need your own keys (see docs/PLATFORMS.md). Without them the app still works by polling; alerts just don't wake the phone.

Still stuck?

Open a Discussion with the output of bash scripts/smoke.sh — it prints exactly which layer broke, in order.