Troubleshooting

The app cannot connect

Confirm the app and daemon use the same HTTPS gateway origin and GitHub account.
Confirm that the app and the machine are trusted devices: open Devices in the app and run dieter device status on the host. See a device is not trusted .
Run dieter daemon status on the host, then dieter machine list.
Check the gateway’s minimum client/daemon releases and each installed release.
Check dieter machine route MACHINE_ID and dieter --machine MACHINE_ID status.

A healthy local API can coexist with a reconnecting gateway tunnel. A recent gatewayLastAcknowledgedAt is bidirectional tunnel liveness evidence. A sync heartbeat alone does not mean all workspace data has arrived.

The gateway root returning 404 is expected. /healthz is its health route; the public marketing and documentation site is a different service.

Setup fails or the service does not start

Run dieter setup for the standard gateway, https://gateway.getdieter.com. Access requires an allowed GitHub account. For a self-hosted gateway, pass its actual HTTPS origin with --gateway. dieter.example.com is a documentation placeholder and must not be copied as a real address.

If enrollment failed before authorization, correct the origin and rerun setup. Incomplete enrollment retries update the origin and machine name while keeping the original private key. Completed enrollments retain their existing identity; see gateway migration . Do not delete or manually edit identity.json or identity-key.pem. If a machine was accidentally enrolled a second time, recover its original identity .

On macOS, setup uses Homebrew’s background service. If an earlier dieter daemon start is still running in a terminal, stop that foreground process with Ctrl-C and rerun dieter setup. Two daemons cannot share the local API port. Setup reports the foreground process instead of accepting its local API as proof that the new service started.

Check dieter daemon status: expect homebrew (started), a healthy local API, and a connected gateway. If the service still fails, inspect brew services list and dieter daemon logs. Agent work can run without screen sharing; remote desktop also requires the daemon’s Screen Recording and Accessibility permissions. Run dieter daemon permissions --check to verify them.

A device is not trusted

Machines answer only the devices in your account’s device roster. Open Devices in an app (More › Devices on Android, iPhone and iPad, Settings › Devices on Mac), or run dieter device status on a machine, and act on its state:

State	Meaning (app title)	What to do
`NO_ROSTER`	Your account has no trusted devices yet (“Set up Dieter on a machine first”)	On your first machine, run `dieter device init` (or `dieter setup`) and store the recovery key
`PENDING`	The device waits for approval and shows a one-time code (“Waiting for approval”)	Type the code on a trusted device: Devices → Add a device, or `dieter device approve CODE`
`TRUSTED`	The device is trusted (“This device is trusted”)	If a machine still refuses it, run `dieter device sync` on that machine: it may not have seen the newest entries yet
`REVOKED`	Another device removed this one (“This device was removed”)	In an app, choose Reset this device and pair again. On a machine, run `dieter daemon unenroll`, then `dieter setup`, and approve its code
`CONFLICT`	The device saw a history of your devices that contradicts the one it trusts (“Your trusted devices conflict”)	See below; remote calls stay closed until you act

A waiting device keeps its code until it is approved, also across restarts, but other devices see its request only while it runs: keep the app open, or the daemon running. “No device is waiting with this code” means the code was mistyped, the new device is not running, or it has already joined. A remote command that fails with “not a trusted device” says which machine still needs approval.

Conflicts. A conflict appears after someone started a new roster with dieter device init --replace, or when a gateway presents a forged or rewritten list. dieter device status shows where the histories differ. Do not reset anything until you know which it was.

If you started a new roster yourself, reset each app (Reset this device), re-enroll each other machine (dieter daemon unenroll, then dieter setup), and approve their codes on the machine with the new roster.
If nobody did, treat your gateway as compromised. Stop using it, tell its operator, and keep the device in its conflict state as evidence.

If every trusted device is lost, add a machine back with the recovery key; see trusted devices .

A project is missing or duplicated

dieter setup does not register projects. Use dieter project open PATH for an existing Git working tree on the host. For another checkout of an existing shared project, use dieter project attach PROJECT_ID PATH.

Inspect dieter project checkouts PROJECT_ID and dieter peer status. A replica can show shared project metadata while a conversation’s execution owner is offline; that does not make its local files or agent executable on another machine.

A model is unavailable

Run dieter harness list --format jsonl on the execution host, or use global --machine MACHINE_ID. Verify that provider’s normal configuration and login on that host. The catalog is machine-specific. Updating a global CLI does not update Dieter’s pinned runtime. See Agents & models .

A task seems stuck

Use dieter card context CARD_ID, dieter card transcript --last 20 CARD_ID, and dieter daemon logs --follow. Check whether it is running, awaiting input, queued, or failed before acting. A lost client connection does not stop its turn.

After a start/send command times out, inspect the conversation before sending it again. The original turn may already have been admitted.

dieter daemon permissions --check
dieter screen capabilities

The result distinguishes ready, permission required, and unsupported. Grant permissions on the target machine, to the executable identified by setup. Mac app permissions and daemon permissions are separate. Linux needs an active graphical session and the screen host requirements . Wayland may require local portal consent when connecting.

For network failures, check the configured STUN/TURN service. H.264 is the default; strict HEVC may fail when either endpoint lacks support. Use screen status SESSION to inspect actual codec and stream state. Do not treat emulator timings as physical device latency measurements.

Phone updates stop in the background

The Android and iOS apps observe your workspace only while they are open. They have no background sync service, notifications, or widgets; reopening the app reconnects and catches up. The host’s agent continues regardless.

A terminal disappeared after a host restart

Client reconnect persistence is built in. Persistence through a daemon restart requires tmux on the host. Remote executions are separate and end when the daemon shuts down. Terminals & automation explains the difference.

Report a useful bug

Include the Dieter release and contract versions, OS/device, selected route, steps to reproduce, expected and actual behavior, and a small redacted log excerpt or screenshot. Avoid complete transcript dumps and remove credentials and personal data. See Contributing .