Fix Docker And Runtime Issues

Most agent startup failures begin with Docker or runtime readiness.

Apprentice requires Docker for agent execution, browser automation, CLI providers, MCP runtime, and mounted folder isolation.

Quick Checks

Start here:

1. Open Docker Desktop or your Docker service.
2. Confirm Docker is running.
3. Restart Apprentice after Docker is healthy.
4. Try one simple manual agent message.
5. Open Activity if the run fails.

Common Symptoms

Docker is not running:

• Agents do not start.
• Runtime health shows unavailable.
• Browser or MCP runtime fails.

Container setup is stale:

• A previously working agent stops starting.
• MCP tools are missing after a runtime change.
• Browser automation fails before navigation.

Folder mount is wrong:

• The agent cannot see expected files.
• Writes fail.
• A mounted path appears under a different name than expected.

Check Folder Mounts

Open the agent, then Config > Directories.

Confirm:

• Primary directory is correct.
• Volumes are present.
• Mount names are unique.
• RO or RW mode matches the intended task.

Remember that a volume named project appears inside the container as:

~/project

Check Runtime Health

Use runtime health panels in agent configuration, especially:

• MCP Servers tab for MCP runtime state.
• Capabilities tab runtime diagnostics.
• Activity and Run Detail for failed run context.

Restart Safely

If Docker was just started or repaired:

1. Restart Apprentice.
2. Open the agent.
3. Refresh the relevant tab.
4. Run a short manual test.

When To Rebuild Or Repair

Repair runtime-related setup when:

• MCP install state is failed.
• Tool discovery does not complete.
• Browser dependencies appear missing.
• Runtime health stays unavailable after Docker is running.

Use in-app lifecycle or repair actions when available instead of manually changing runtime files.

Still Failing

Collect:

• The agent name.
• The failed run time.
• Activity error.
• Runtime health state.
• Docker status.
• Whether the failure affects one agent or all agents.

That information usually separates Docker-wide failures from one agent's configuration issue.