Daemon troubleshooting

Every paired computer runs a small idapt-computer daemon that keeps an outbound connection to idapt open. When that connection breaks, the AI can no longer reach the machine. Here is how to get it back 🛠️

Start here: one command that shows everything

Before anything else, run this on the machine itself:

idapt-computer status

It answers the four questions this article is about in one screen: whether the machine is linked and to which account, whether the daemon is running and connected, which capabilities are enabled, and which ports are currently exposed. Anything disabled comes with the exact command to enable it.

This command needs no sign-in. The idapt-computer daemon authenticates as the machine, so it works even on a box you have never signed into.

Computer shows offline

The computer's page shows an Offline badge when no heartbeat has arrived for about 90 seconds (the daemon beats every 30 seconds). Commands the AI tries to run fail until it is back.

Ask the machine why.
On the host, run the status command. When the cause is known it says so on the first line, before any detail: the computer is not registered on the server, it was deleted from your account, or the daemon is holding an old credential. Each names the command that fixes it.
```
idapt-computer status
```
Check the daemon.
If the status gives no verdict, check the daemon's own service state and self-test:
```
idapt-computer service status
idapt-computer service doctor
```
Doctor checks connectivity, credentials, and configuration, and tells you what is wrong.
Restart it.
If the service is not running, restart it:
```
idapt-computer service restart
```
Within a few seconds the badge returns to Online.
Check the OS service.
A standard Linux install uses a user systemd unit:
```
systemctl --user status idapt-computer
```
A daemon elevated for root or cross-user access uses a system unit instead:
```
sudo systemctl status idapt-computer
```
On macOS it is a LaunchAgent, and on Windows a scheduled task, both set to start when you log in.
If you just re-paired this computer, restart the daemon.
Pairing issues a fresh credential, and a daemon that was already running is still holding the previous one. Recent versions restart it for you; if yours did not, or the restart reported a warning, do it by hand:
```
idapt-computer service restart
```
The tell-tale sign is that on-box commands such as idapt-computer tunnel list are refused by your own daemon while the computer stays offline in the app.
Read the logs.
If it still will not connect, look at the daemon logs for clues:
```
idapt-computer service logs
```

A capability is blocked

A computer you paired yourself starts with its most sensitive capabilities turned off, so capabilities like shell, file access, computer use, the interactive terminal, and local inference are refused until you turn them on the machine itself. This is by design, not a fault. The computer's Permissions list on its Dashboard shows each capability as Allowed or Blocked.

There are two ways to enable one, and both act on the machine:

In the idapt desktop app, on the computer itself: open the computer, and in the Permissions section click Manage to open the native permissions window. Turn on the capability you need. The Manage button appears only for the machine the app is running on.
On the host, in a terminal: enable the capability. The command prints Applied. and a running daemon adopts the change without a restart.
```
idapt-computer service policy enable computer-use
```

The capability names you can enable are remote-shell, remote-files, admin-ops, computer-use, remote-terminal, computer-apps, tunnels, and local-inference. Use full-control to enable every full-control capability at once.

To enable every local capability, including full control, port tunnels, containers, and local inference, run:

idapt-computer service policy enable all

all gives idapt every local capability on this computer. Enable one named capability instead when you want narrower access.

Swap enable for disable to turn a capability back off. If a change does not seem to take effect, restart the service with idapt-computer service restart.

The terminal is reconnecting

The computer's heartbeat and its secure terminal connection recover separately. After a daemon restart or brief network change, the computer can appear online for a few seconds before the terminal is ready.

Wait a few seconds and retry.
Click Try again in the Terminal tab. A temporary reconnect needs no configuration change.
Check the daemon status.
```
idapt-computer service status
```
Read the logs if it continues.
```
idapt-computer service logs
```
Look for a tunnel connection error, then confirm that your network allows outbound HTTPS connections.

Run commands or terminals as root

Installing the user-mode daemon while signed in as root does not grant deliberate root command access. On Linux, move the existing pairing to a root system service:

sudo idapt-computer service elevate

The command preserves the paired computer and switches autostart to a system unit. Root access is used only when a command or terminal explicitly requests root.

If this computer has only a root account and commands fail with runas-forbidden: uid 0 (root) requires explicit policy opt-in, run idapt-computer service elevate directly on the host. The system service sets the daemon's root opt-in, preserves the existing pairing, and restarts it. Then retry the command from idapt. Do not search for or hand-edit an undocumented daemon config file.

Private AI fails in chat

When a chat on a local model cannot run, the error in the chat names the cause and the fix, rather than a generic provider message. The common cases:

Model not installed: install it again from the model directory on the computer's Private AI tab, then retry.
Out of memory or context too large: the model did not fit. Try a smaller model, or lower its context window on the installed-model card.
Computer offline: the request fails fast instead of hanging. Bring the computer back online, then retry.

An interrupted download recovers on its own. idapt resumes it from where it stopped, and a stalled download retries automatically. You can also retry it yourself from the model card.

If the Private AI Engine shows as not installed but you already run Ollama, idapt detects the system install on its own. You can also install it from ollama.com.

An update rolled back

idapt ships daemon updates to your computer over its heartbeat, not on a fixed timer. If an update fails its self-test, the daemon reverts to the previous working version and shows a notice on the computer's page. Nothing breaks, because the machine keeps running the older daemon, and the next update picks up the fix on its own.

Re-pair after deleting a computer

When you delete a computer, its daemon notices its credentials are revoked, wipes its config, and shuts down cleanly. It does not keep retrying. To bring the host back:

Install idapt on the host.
Open Add computer and copy the install command for that operating system. It downloads the daemon. It carries no credential, so the same command is safe to share.
Connect it to your account.
Run the connect command below. It prints a link. Open it in your browser, check the name, and choose which workspaces may use the machine.
```
idapt-computer up
```
Wait for the online badge.
Once the daemon sends its first heartbeat, the computer shows as Online.

A cloud computer will not come online

A cloud computer installs its daemon at first boot. While it comes up, the computer's status page walks through bootstrap checkpoints, the stage it has reached and the current attempt, so you can see how far it got.

If the daemon never reports a first heartbeat, provisioning is marked failed after about five minutes. The last bootstrap checkpoint on the status page tells you where it stopped. Terminate the computer and create a new one to try again.

Computers

Pair your own machine or launch a cloud one, then let your AI run commands and work with files on it.

Cloud computers

Launch an on-demand cloud machine, understand what it costs per second, and suspend it when you're done.

The computer daemon

What idapt-computer runs on a paired machine, how to manage the service, and where its config lives.

Up next

Start coding with idapt Code

Point a normal idapt Chat at a paired or cloud computer and have it read the project, change code, run the tests, and report what it did.

Was this helpful?