Common Issues

Startup

ZeroSphere does not start:

Open the three-dot menu (⋯) in the title bar and select Install Diagnostic to collect logs automatically.

Or check the log file directly:

Windows:

%APPDATA%\zerosphere-nightly\logs\zerosphere-runtime.log

"Failed to load configuration":

Delete or rename settings.toml and restart. ZeroSphere recreates defaults on next launch.

Windows:

%APPDATA%\zerosphere-nightly\settings.toml

API and Models

"API key not found":

Native provider keys (Anthropic, OpenAI, Gemini, Tavily) are set in Settings > AI > API Keys.

Custom model profiles are managed in Settings > AI > Custom Models. Paste the key directly into the profile card and click Save Changes.

"Model not found": Verify the profile is enabled (checkbox on the card in Settings > AI > Custom Models). The model name must match exactly what your provider expects.

Slow responses: Switch to a faster model. Start a new conversation if the current one has grown very long — large context slows every response.

Permissions

File operation blocked: Check Settings > AI. If the file is outside your workspace, outside_workspace_access_enabled must be true in config.toml.

Terminal command blocked: Approve when prompted, or set run_command_mode = "let_model_decide" in config.toml for routine commands.

Agent freezes or hangs mid-stream with no response:

The most common cause is the agent waiting on a permission it cannot get because the approval dialog never appeared. This happens when a tool hits a denied permission silently — the agent is paused internally but nothing shows on screen.

Fix: go to Settings > AI > Permissions and temporarily allow whatever the agent was trying to do (virtual session creation, terminal commands, file access, etc.). Once access is granted, the agent will resume. After the task completes, tighten the permission back if needed.

Virtual Display

Windows: "Virtual Display Driver installation failed"

The VDD driver requires Administrator for the initial install. Re-launch ZeroSphere as Administrator once. Subsequent sessions do not need elevated privileges.

Windows: App launched but nothing in the viewer / black screen:

The app may have opened on a different display. Use osListWindows to find it, then osBindWindow to move it into the session.

Windows: Resolution not what I requested:

The VDD snaps to the nearest configured resolution. The pre-configured list lives at:

C:\VirtualDisplayDriver\vdd_settings.xml

Session not found:

Sessions expire after 20 minutes of inactivity. Create a new one — the agent handles this automatically.

Known Windows bug — app appears stuck on the virtual display and won't show on your desktop:

This is a Windows regression where a window can get pinned to a display that is no longer active. Nothing is wrong with ZeroSphere. There are three ways to get it back:

Fastest — ask the agent: Just launch the app and tell ZeroSphere in the chat: "Move [app name] back to my display." The agent will locate the window and move it straight to your primary display. No restart needed.

Keyboard shortcut: Click the app icon in the taskbar to bring its focus bubble to the foreground, then press Win + Shift + → or ← two or three times. The window will snap back to your active display instantly.

Taskbar bubble click: If the window is not visible, click the app's taskbar icon — a small focus square will appear in the background behind the icon. Click it once to select the window, then use Win + Shift + → or ← to move it over.

None of these require a restart. The window is just off-screen, not lost.

MCP

Server not loading:

Test the server directly:

uvx mcp-server-time

Check the ZeroSphere output panel for connection errors.

Config location:

%USERPROFILE%\.zerosphere\mcp/mcp.json

Tool requires approval every time: Add safe read-only tools to autoApprove in mcp.json.

Performance

High CPU or memory: Restart ZeroSphere. Start a new conversation. Add large generated directories (node_modules, target, dist) to .gitignore to reduce indexing.

Configuration

Settings not persisting: Check that the config directory exists and ZeroSphere has write access to it.

Config changes not taking effect: config.toml permission changes take effect on the next agent run without requiring a restart. settings.toml changes require a restart.

Logs

Windows:

%APPDATA%\Roaming\zerosphere-nightly\logs\

For a full diagnostic bundle, use three-dot menu (⋯) > Install Diagnostic.

Still stuck? support@zerosphere.dev