---
title: "Troubleshooting · intentic docs"
description: "Fix a sandbox that never came up, a workspace that won't open, unattended runs that error, work that won't land, and extensions or capabilities that went quiet."
url: "https://intentic.dev/docs/troubleshooting/"
updated: "2026-09-15"
---

Run a sandbox

# Troubleshooting

What tends to go wrong, what causes it, and what to do: starting with the two checks that settle most of it. Every symptom here is one this product actually produces.

**On this page (28 sections)**

- [The two checks worth making first](#the-two-checks-worth-making-first)
- [Bringing one up](#bringing-one-up)
- [The install command stopped and asked about Docker](#the-install-command-stopped-and-asked-about-docker)
- [On Windows, the install stopped over Docker](#windows-docker)
- [The Windows installer stopped with a code](#installer-exit-codes)
- [The setup code no longer works](#the-setup-code-no-longer-works)
- [docker run says the port is already in use](#docker-run-says-the-port-is-already-in-use)
- [The workspace never opens](#the-workspace-never-opens)
- [A capability the image was supposed to carry isn't there](#a-capability-the-image-was-supposed-to-carry-isnt-there)
- [It was working yesterday](#it-was-working-yesterday)
- [Every browser session stopped verifying at once](#every-browser-session-stopped-verifying-at-once)
- [An update left the sandbox worse](#an-update-left-the-sandbox-worse)
- [A notice says a settings file cannot be read](#a-notice-says-a-settings-file-cannot-be-read)
- [The app offers no update or rebuild button](#the-app-offers-no-update-or-rebuild-button)
- [The agent](#the-agent)
- [Unattended runs error every time and chats are fine](#unattended-runs-error-every-time-and-chats-are-fine)
- [An automation records runs as skipped and never wakes](#an-automation-records-runs-as-skipped-and-never-wakes)
- [Fires are queued and nothing runs](#fires-are-queued-and-nothing-runs)
- [The Front Desk is installed and stays silent](#the-front-desk-is-installed-and-stays-silent)
- [Landing work](#landing-work)
- [Nothing landed and the card says conflict](#nothing-landed-and-the-card-says-conflict)
- [Work is already in main and the card still wants to land](#work-is-already-in-main-and-the-card-still-wants-to-land)
- [Finished agents disappeared](#finished-agents-disappeared)
- [Extensions and capabilities](#extensions-and-capabilities)
- [An extension is installed and one of its surfaces is missing](#an-extension-is-installed-and-one-of-its-surfaces-is-missing)
- [One capability vanished and the rest still work](#one-capability-vanished-and-the-rest-still-work)
- [An extension was switched off on its own](#an-extension-was-switched-off-on-its-own)
- [When none of this is it](#when-none-of-this-is-it)

## The two checks worth making first

If something is not working and you cannot tell which half broke, start here. A sandbox is two containers and one outbound tunnel, and almost everything below is one of those three not being where you think. Ask them directly rather than reading the app.

On the machine hosting the sandbox

```bash
# Both should be "Up". Two per sandbox, always.
docker ps -a --filter name=intentic-sandbox

# The sandbox's own answer, from any machine. No credential needed.
curl https://sandbox-<id>.intentic.dev/health

{ "ok": true, "sandboxId": "…", "boot": { … }, "announce": { … } }
```

Your sandbox's exact address is on **Sandbox → Overview**. If `/health` answers with `"ok": true`, the daemon is alive and the tunnel is up, so the problem is above that line: a session, an account, a permission. If it does not answer, the problem is below it and the logs are next.

When /health says nothing

```bash
# What the daemon said while it came up.
docker logs --tail 200 intentic-sandbox-<SLUG>

# And the connector, if /health never answers from outside the machine.
docker logs --tail 50 intentic-sandbox-tunnel-<SLUG>
```

Your [slug](https://intentic.dev/docs/glossary/) is the first label of that hostname. In the [desktop app](https://intentic.dev/download/) the same logs are a button, next to start, stop and update.

## Bringing one up

### The install command stopped and asked about Docker

You ran it without `sudo` on a machine that has no Docker Engine. Installing Docker is the one step that needs root, and the script will not escalate on its own. So it stops and names your two options instead: re-run it with `sudo`, or install Docker yourself and re-run it without. Everything after that step is a docker or curl call your own user can make.

### On Windows, the install stopped over Docker

Docker on Windows runs Linux containers inside **WSL2**, which in turn needs hardware virtualization and two Windows features. The setup checks all of it before it starts and tells you, in one list, exactly what is missing, so the answer is whatever that list says rather than a guess. Most of it it does for you, once, after asking:

- **WSL2 or its Windows features are off**: turned on for you (Windows asks for permission), then your PC restarts. The desktop app saves the setup and picks it up again after the restart; from a terminal, run the same command once you are back.
- **Docker Desktop isn't installed**: installed for you. If this PC has no Windows package manager, the installer is downloaded straight from docker.com instead, which is the same thing by a different route.
- **Docker is installed but the engine isn't up**: started and waited for. If Docker Desktop is showing you its first-run screens, finish those and run the setup again.
- **Docker is in Windows-container mode**: switched back to Linux containers, which is what a sandbox is.

Two of them are not ours to fix, and the setup says so plainly rather than retrying. **Virtualization switched off in your PC's firmware** is a BIOS/UEFI setting (no software can change it from inside Windows), so the setup prints the steps, including the key to press for your make of PC. And if this Windows is itself a **virtual machine**, nested virtualization has to be enabled on the machine hosting it, with the VM shut down.

You can ask for the diagnosis on its own at any time, without changing anything: `ic docker prepare --dry-run`.

### The Windows installer stopped with a code

The installer is an NSIS package, and it answers with one of three codes. The Microsoft Store shows you the code when it installs the app for you, because it runs the same file silently (`/S`) rather than showing you the installer's own screens.

- **0**: installed. Nothing to do.
- **1**: cancelled. Either you closed the installer, or a Windows permission prompt was declined. Run it again and accept the prompt; the app installs for your user only, so it never asks for an administrator.
- **2**: the install itself failed. Almost always disk space, an antivirus holding the file, or a copy of Intentic already running — quit it from the tray and retry. If it repeats, the installer from the [download page](https://intentic.dev/download/) shows the step it stopped on.

None of these are Docker: the installer only puts the app on disk. Docker is set up later, by the app, on the screen described above.

### The setup code no longer works

Setup codes expire **30 minutes** after the screen mints one. Reopen the setup screen and a fresh code is minted into a fresh command; nothing else is lost, and it is still the same sandbox. Re-running a command whose code is still valid is also safe: see [more about setup codes](https://intentic.dev/docs/quickstart/#setup-codes).

### docker run says the port is already in use

The container publishes a loopback listener at a port derived from your sandbox's id, and something else on the machine holds it. That port is only a shortcut for a browser on this same machine, so it is safe to drop: re-run [step 4](https://intentic.dev/docs/quickstart/#docker-run) with `--no-local-publish` and the sandbox works over its tunnel as usual. The scripted install paths do this for you: they retry without the port rather than failing.

### The workspace never opens

The daemon announces its URL to the platform on boot, and your browser then probes the sandbox directly until it reports healthy. So a workspace that never opens means one of those two halves is missing. Run the checks above: if both containers are up but `/health` answers only on the host, the connector is the piece that has not come up, and its log says why.

### A capability the image was supposed to carry isn't there

An *optional* image fragment this host cannot satisfy, such as a GPU fragment on a machine with no NVIDIA runtime, is skipped rather than failing the launch. The sandbox records the skip, so the container is healthy and the tool absent. Required fragments do the opposite and stop the launch.

## It was working yesterday

### Every browser session stopped verifying at once

That is what **Sign out everywhere** does: it re-keys the sandbox's session signer, so every session stops verifying, including yours. Your own browser re-establishes from the Google credential it holds, so it looks like nothing happened locally while everyone else is signed out. That is intended.

### An update left the sandbox worse

An update that cannot come up healthy puts the previous sandbox back by itself, so a failed update is not yours to recover from. One that came up healthy but works worse is a rollback you ask for: `/work` and your history survive both, because they live in named volumes rather than in the container. See [Updates & rollback](https://intentic.dev/docs/updates/).

### A notice says a settings file cannot be read

Usually that is an older version looking at a file a newer one wrote, and the notice will say so rather than asking you to repair a file that isn't broken. Update again and it reads fine.

### The app offers no update or rebuild button

A sandbox can never recreate its own container, so something on the host has to. Without the desktop app that is a command you paste on the machine, and the platform prints the exact one on your **Sandbox** and **Environment** cards when it applies. [Docker setup](https://intentic.dev/docs/docker/) has them all.

## The agent

### Unattended runs error every time and chats are fine

The commonest failure nobody is present for. A sandbox holds several accounts per provider, and an unattended run takes the first unless something pinned one. When that account runs out of headroom, or belongs to an organisation that turned the plan off, every automation, Front Desk and nightly workflow errors against it until somebody reads the row.

The sandbox keeps the last refusal per provider and shows it beside the account on **Sandbox → Agent**, which is where this becomes obvious. The fix is to **pin the account** on the automation, and it is worth doing on every surface that starts work while nobody is watching. See [Models & accounts](https://intentic.dev/docs/models/).

### An automation records runs as skipped and never wakes

A [guard](https://intentic.dev/docs/glossary/) is doing its job. A guard is a shell one-liner run before the wake: exit 0 and the agent wakes, anything else is recorded as skipped. A guard that can never exit 0, because a path moved or the image lost a command, reads exactly like an automation that stopped firing.

### Fires are queued and nothing runs

**Require approval** is on for that automation, which holds every fire until you approve it. That is different from **Hold for a while**, which runs the fire itself once the hold elapses. An explicit "ask me" always wins over a hold, so an automation carrying both waits for you. [Automations, workflows & loops](https://intentic.dev/docs/automations/) covers the queue.

### The Front Desk is installed and stays silent

Nearly always the allowed origin. `https://example.com` and `https://www.example.com` are different origins, the site redirects one to the other, and the browser ends up on the one you did not list. List both. The install panel names the origin it turned away and offers to add it: [Front Desk](https://intentic.dev/docs/front-desk/) has the detail.

## Landing work

### Nothing landed and the card says conflict

One of the agent's repository patches could not apply: you edited the same lines, or an overlapping file is dirty. Landing checks the whole composition first, so nothing reaches any repository. The card names what stopped it and every worktree keeps everything; resolve your side and land again. [Parallel agents](https://intentic.dev/docs/parallel-agents/) covers the whole flow.

### Work is already in main and the card still wants to land

Work that reached the main tree by another road is not a conflict. An agent that committed onto the main line, or a branch you merged by hand, resolves as "already there", so landing is a no-op rather than a refusal. Landing twice is safe by design.

### Finished agents disappeared

Finished agents are archived after three days by default, on **Sandbox → Agent**. That sweep is on where almost everything else is off, because a finished card holds a full checkout of every repo: a lane that grew forever would be disk that grew forever.

## Extensions and capabilities

### An extension is installed and one of its surfaces is missing

A view, command, viewer, setting or process the approved manifest never declared is refused at runtime rather than warned about, and an undeclared route throws. A missing surface usually means the manifest and the code disagree. When a manifest grows, the update **re-asks** and shows the added powers as plain sentences. Approval never transfers to powers you did not approve. [Extensions](https://intentic.dev/docs/extensions/) covers what you approved; the [manifest reference](https://intentic.dev/developers/manifest/) is what its author had to declare.

### One capability vanished and the rest still work

An unreadable stored connection is skipped and reported *by name*. It may come from a hand edit or an old format, but it is never rewritten and every other capability keeps working. Reconnect that one card. [Capabilities](https://intentic.dev/docs/capabilities/) covers where the credential lives.

### An extension was switched off on its own

Its registry listing is marked `blocked`: known-malicious or known-broken. The advisory on the installed row carries the registry's recorded reason. Disabling is the one automatic action the trust model permits, because it runs no new code and reverses with a click. [Extensions](https://intentic.dev/docs/extensions/) states the whole model.

## When none of this is it

The daemon keeps terminal captures, CLI run logs and `daemon.log`. They are reachable over the API and in the desktop app. Your files are never the thing at risk while you dig: `/work` and your history are named Docker volumes, and removing, updating or rebuilding a container does not touch them.

And if none of it says anything either: bring the symptom to the [Discord community](https://discord.gg/3veuzYp32T): most of what reaches this page is something somebody has already hit, or [open an issue](https://github.com/intentic/intentic/issues) if you can make it happen twice. Either way, the logs above are what makes it answerable.

## Related pages

- [Docker setup](https://intentic.dev/docs/docker/): what every install path created, and the update, rebuild and cleanup commands.
- [Glossary](https://intentic.dev/docs/glossary/): the words above, if any of them were doing unexplained work.
- [When a call fails](https://intentic.dev/api/errors/): every status the API returns and what it actually means.

More in Run a sandbox

[Previous ← Access & sharing](https://intentic.dev/docs/access/)