Workspace fails to spawn

The spawn modal returned an error, or the workspace transitioned straight to failed after spawning.

Read the error code

Qorin returns structured error codes. Common ones:

Code	What it means	Fix
agent_not_connected	Host went offline between you opening the modal and clicking Spawn.	Check Agent offline.
no_agent_user	You have no OS-user mapping on this host (multi-user setup).	Ask the host owner to add you in Manage users.
spawn_ack_timeout	Agent received the spawn request but didn't ack within 7s.	The host is busy or the CLI is slow to start. Retry.
spawn_failed + code=cli_not_found	The CLI binary (claude/codex/cursor/gemini/opencode) isn't in the agent's PATH.	CLI not found.
spawn_failed + code=worktree_collision	A worktree already exists for that branch.	Either pick a different branch or terminate the conflicting workspace.
plan_limit_exceeded + code=max_workspaces	You hit the Free 3-concurrent cap.	Terminate an idle workspace or upgrade to Pro.
repo_already_registered	The path is registered as a repo on this host. Modal auto-resolves to spawn under that repo.	Should be transparent — if you see this in an alert, refresh and retry.

Check the agent journal

The agent logs the spawn attempt — often the error is more readable there than in the dashboard alert.

Linux:

sudo journalctl -u qorin-agent -n 100 --no-pager | grep -i workspace

macOS:

sudo log show --predicate 'subsystem == "dev.qorin.agent"' --last 10m | grep -i workspace

Common root causes

• CLI not authenticated under the OS user that owns the workspace. claude login (or the codex/cursor/gemini/opencode equivalent) needs to have been run as that user, not as root.
• tmux not installed on the host. The agent uses tmux for every workspace; install it:
  • macOS: brew install tmux
  • Debian/Ubuntu: apt install tmux
  • Fedora: dnf install tmux
• git ownership / safe.directory on Linux when the agent root isn't the folder owner. Already handled in agent ≥ 0.42 (we set safe.directory=* per-invocation), but if you're on an older version, upgrade.

When all else fails

Try the stub CLI agent at spawn time. It's a noop that just tail -f /dev/nulls — if even the stub fails, the issue is in the agent itself (tmux missing, setuid failing, etc.) and not in your CLI auth.