Troubleshooting

Common issues and how to resolve them.

agents-sandbox doctor fails

If the doctor command reports missing prerequisites:

Docker not running

Start the Docker daemon. How to start it depends on your environment. When using Docker Desktop, start it. With Docker installed as system wide package on Linux, the normal startup procedure is to execute sudo systemctl start docker

You can verify afterwards by running docker info. It should show a healthy daemon.

Microsandbox runtime version mismatch

Before using microsandbox, agents-sandbox compares the selected msb version with the microsandbox SDK version linked into the launcher. A mismatch is reported before the runtime database is opened. The interactive recovery menu can:

  • upgrade agents-sandbox and restart when a newer launcher release is available;
  • upgrade or downgrade msb to the required version;
  • use the installed runtime unchanged in unsupported brave mode;
  • print a sanitized diagnostic report and the bug-report URL; or
  • quit without changing anything.

The default choice is always quit. --yes does not select a runtime recovery action; in a noninteractive invocation the command prints diagnostics and exits without modifying the runtime.

Do not replace only ~/.microsandbox/bin/msb manually. The runtime database, libkrunfw, FFI library, VM records, volumes, and caches are versioned state and must remain compatible with one another. If a newer msb has already migrated the database, use the official rollback offered by the prompt rather than copying an older binary over the newer one.

If no newer agents-sandbox release supports the installed msb, submit the compatibility report at:

https://github.com/inoio/agents-sandbox/issues/new?template=bug_report.yml

KVM unavailable 

# Check if /dev/kvm exists
ls -la /dev/kvm

If missing, enable virtualization in your system BIOS/UEFI (INTEL-VT, AMD-V or similar) and ensure your user is in the kvm group:

sudo usermod -aG kvm "$USER"

Log out and back in for the group change to take effect.

macOS-specific issues

Not Apple Silicon

The doctor command will exit with an error if you are running the x86_64 binary under Rosetta 2. Download the darwin-arm64 binary instead. To check your current architecture:

uname -m

Expected output on supported hardware: arm64.

Docker socket not found

On macOS, the Docker socket is managed by Docker Desktop or colima. Verify it is running:

docker info

If Docker Desktop is installed but not running, launch it from Applications. If using colima:

colima start

agents-sandbox finds the socket the same way the docker CLI does: DOCKER_HOST wins, then the active docker context, then the default /var/run/docker.sock. If docker info works but agents-sandbox reports the socket as unreachable, check which context is active and where it points:

docker context ls

A context marked * that points at a stopped provider explains the failure — switch it with docker context use <name>, or point agents-sandbox at the socket directly:

export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock

Note that DOCKER_HOST takes precedence over the active context, so an outdated value in your shell profile overrides a correct context.

VM won’t start

When a VM won’t start, check the general troubleshooting steps first.

“create sandbox: …” errors

Try --log-level verbose to see the full error:

agents-sandbox run --log-level verbose

Common causes:

  • Not enough system memory — reduce with -m 2G

Stale sandboxes consume resources

List and prune 

# See what's running
agents-sandbox list

# Remove old resources
agents-sandbox prune --dry-run    # preview
agents-sandbox prune --force      # remove

Stop a specific VM 

agents-sandbox stop               # graceful stop
agents-sandbox kill               # force kill

Branch session issues

“failed to create worktree”

If the managed worktree creation fails:

# Clean up stale worktrees in your repo
git worktree prune

Then retry the command. If the problem persists, check for uncommitted changes or locked worktrees:

git worktree list

Branch prompt hangs

If the branch creation prompt doesn’t respond, check that the repository has a remote configured:

git remote -v

Without a remote, some git operations may hang. Add one or use an absolute branch name:

git remote add origin https://example.com/repo.git

Missing tools inside the sandbox

If you need a tool that isn’t in the base image (e.g., go, rustc, python3), add it to your project’s custom Dockerfile, see Runner Image documentation.

Secrets not available

Verify the secret is set with the correct format. For legacy env.secret, the format is KEY=value@host where the part after the last @ is the host policy tag — values may contain @. If no @host part is present the secret is dropped with a warning.

For env.secret.yaml, values may contain @ without issues. Ensure the entry defines either host, hosts, or allow_any_host_dangerous: true — entries with no hosts definition are silently skipped. An empty value is valid and passed through unchanged.

Memory or CPU limits too low

If the agent runs slowly or VMs fail to start with resource errors, increase allocation:

agents-sandbox run -c 4 -m 8G

Or set defaults in config:

# ~/.config/agents-sandbox/config.yaml
cpus: 4
memory: 8G

Config not applying

If your config files aren’t being picked up:

  1. Verify the file exists in the right location:

    ls ~/.config/agents-sandbox/config.yaml
ls .agents-sandbox/config.yaml

  2. Check valid syntax:

    # For YAML files
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
   
# For JSON/JSONC files
python3 -c "import json; json.load(open('config.json'))"

  3. Check that CLI flags aren’t overriding your config (flags always win).

  4. Use --log-level verbose to see which config files were loaded:

    agents-sandbox run --log-level verbose

Image build fails

Docker build failures are usually due to:

  1. Network issues — The base image downloads packages from the internet. Ensure outbound access:

     curl -fsSL https://debian.org | head -c 100

  2. Docker daemon memory — Large builds may need more memory:

     docker info | grep "Total Memory"

  3. Custom Dockerfile errors — If using a project Dockerfile, build it manually to isolate the issue:

     docker build -f .agents-sandbox/Dockerfile -t test-image .

If an older image or updater state reports Release vuser-provided not found, update agents-sandbox and rebuild the runner image. user-provided identifies an agent that was previously found in a custom base; it is not a valid release version. A rebuilt image will keep an agent supplied by the base, or install a real resolved release if that binary is no longer present.

Docs built from release main