Troubleshooting

The daemon won't start

Check what it says first:

openacme status
openacme logs

The common causes:

• Port already in use. Something else is on 3456. Change server.port in ~/.openacme/config.yaml and openacme restart.
• Stale process. openacme stop then openacme start. If a process survived, openacme status shows its pid.

Agents won't respond / auth errors

Your provider credentials expired or were never set:

openacme login --provider anthropic   # or openai

API-key users: confirm the key is in config.yaml or exported in the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, …). Subscription sign-ins refresh automatically; if refresh fails permanently you'll be prompted to log in again.

A task is stuck

• blocked never clears itself — an agent (or you) set it, and an agent (or you) must set it back. Open the task and read the comments; the blocker is usually stated there.
• A task that errored gets parked with a retry delay and a comment from the scheduler. It re-runs on its own; cancel it if it shouldn't.
• Check the task's events log (on the task page) to see exactly what happened and when.

Where everything lives

When in doubt, look at the data directly — it's files:

Tools run unconfined ("SANDBOX UNAVAILABLE")

On Linux the sandbox needs a few system packages. openacme start offers to install them; or do it yourself:

sudo apt install -y bubblewrap socat ripgrep   # Debian/Ubuntu
openacme restart

Without them the daemon still runs, but agent tools execute unconfined. macOS sandboxes natively — no extra packages.

Notifications don't arrive

Web push needs a few things lined up:

• Secure context — push works on localhost, but a remote instance needs HTTPS. Over plain http://<ip> the browser disables push entirely; reach it through a tunnel (see Remote access).
• OS permission — on macOS, System Settings → Notifications → your browser must be allowed, with Focus / Do Not Disturb off.
• Per-site permission — the browser's site settings must allow notifications for the OpenAcme URL.

Notifications fire when an agent calls ping_user; enabling them under Settings → Notifications only subscribes the device.

Verbose logging

OPENACME_DEBUG=1 openacme restart

drops the logger to debug level. Attach the output when reporting an issue.

Starting fresh

Stop the daemon, move ~/.openacme aside (don't delete it — your data is in there), and run openacme setup again.