Troubleshoot with dynocap doctor

dynocap doctor checks everything a sandbox needs and tells you, for each problem, what is wrong and what to run. dynocap doctor --fix repairs the problems it can.

dynocap doctor                  # report only; changes nothing
dynocap doctor --fix            # repair, then report again
dynocap doctor --fix ./project  # check and prepare the runtime ./project uses

The runtime doctor checks is the one your project uses: package.json means node:24; pyproject.toml, uv.lock, requirements.txt, setup.py, or Pipfile means python:3.14; go.mod means go:1.27. clone picks the same way. Pass --runtime NAME:VERSION to choose another. With no project (for example, in the dynocap checkout), doctor requires no runtime and lists the prepared ones.

--fix builds from the dynocap checkout, which it finds from the dynocap binary, so you can run it in any directory.

Reading the Report

Home: /Users/you/.dynocap

OK      platform           macOS 13+; guest architecture aarch64
OK      signing            CLI signature validates and includes the virtualization entitlement.
ERROR   images             The guest image for aarch64 does not match its manifest.
                           Next: Run dynocap doctor --fix to build the guest image (downloads pinned Alpine files; needs Go).
ERROR   daemon             The running daemon started before this dynocap binary was rebuilt, so it runs the old build.
                           Next: Run dynocap doctor --fix to restart the daemon with this dynocap build.

2 required checks failed. Run dynocap doctor --fix to repair them.

• OK passed; a stopped daemon or a home that does not exist yet is normal. WARNING is worth knowing but does not block sandboxes, such as having no runtime prepared outside a project. ERROR blocks sandboxes, and the command exits 1.
• Next: is the one thing to do. When it names dynocap doctor --fix, the command already includes any --home or --runtime you passed, so you can paste it as printed.
• The last line says whether --fix can repair everything, some of it, or nothing.

For scripts, dynocap doctor --json prints the same report. Each check has a fix field naming its automatic repair. See JSON Schemas.

What --fix Repairs

Repairs run in that order, and progress goes to stderr. Each repair prints a build log path, so a failure shows what to read. --fix then runs every check again and reports the result.

--fix never:

• restarts a daemon that has running sandboxes. Instead it names them, so you can finish or rm them first;
• deletes image files. It moves them aside;
• re-signs the CLI or rebuilds companions. Reinstall with brew reinstall baires/tap/dynocap or scripts/install.sh. From a source checkout, run ./scripts/build-macos.sh.

Checks That Need You

Common Situations

I rebuilt dynocap and now commands fail

The daemon keeps running the old build until it is restarted. doctor reports this as an ERROR daemon. Run:

dynocap doctor --fix

--fix says Go is missing

The guest agent is compiled during image and runtime builds. Install Go 1.22 or newer (brew install go), then run dynocap doctor --fix again.

--fix cannot find the source checkout

--fix looks beside the dynocap binary and above the current directory. A Homebrew or curl install keeps Package.swift and guest/ next to bin/, and the CLI resolves its own symlink to that prefix. If you copied the binary by itself, run doctor from a source checkout with the project path: dynocap doctor --fix ~/code/my-app.

clone picked the wrong runtime

clone prints the runtime it chose and the file it chose by, such as Using runtime node:24 (detected from package.json). Pass --runtime to clone and to doctor --fix to choose another.

A repair failed

The repair line shows the error, a Log: path, and a Next: step. The build log has the full download or compile output.

This page is also plain Markdown, for agents and for you.