Workspaces

A workspace is the unit Qorin operates on. One CLI agent process, one folder, one host, one Qorin user. Lifecycle is short to long running — most live a few hours, some live for days.

Lifecycle

spawning  →  running  ↔  idle  ↔  awaiting_input
                                     ↓
                                terminate
                                     ↓
                  completed | failed | discarded

Transitions you should know:

• spawning → running: the agent acknowledged the spawn within ~7 seconds. If it doesn't, you get a 504 in the spawn modal — the agent might be busy or the CLI may not be installed.
• running ↔ idle: idle is "no output for >30s". Not actionable — the CLI might just be thinking.
• awaiting_input: the CLI is asking for permission, or its turn ended and it's your move. With hook notifications enabled (Pro+), this opens the workspace's one attention request — and opening the workspace, or the CLI going back to work, closes it and withdraws the notification. See notifications.
• failed: the agent reported a workspace error (CLI not found, bad branch, …) or the host went offline while the workspace was alive (the sweeper flips zombies to failed).

Direct vs worktree mode

Every workspace runs in one of two modes. The New workspace modal calls the choice Isolation, and it only appears for git folders.

Direct is the default on every tier, including Pro. The CLI runs in your project folder, in place — the same files you'd see in your editor. Setup is instant, and nothing about your checkout changes. Two workspaces pointed at the same folder do share those files, so parallel agents can step on each other.

Worktree (Pro+) gives the workspace its own checkout:

• The original repo checkout stays untouched.
• The workspace gets a worktree directory like <repo>/.qorin/worktrees/<branch>.
• Two workspaces on two branches of the same repo don't fight.

We don't turn worktree on for you when you upgrade. Isolation changes where your files live, so it stays an explicit choice you make in the spawn modal.

For non-git folders the choice doesn't appear: worktrees need git, so those workspaces are always Direct. We enforce one live workspace per non-git folder at a time, because parallel agents on the same files would clobber each other.

Attach a file

The 📎 in the terminal toolbar puts a file where the CLI can read it. It's a Pro+ feature, and it has two halves:

• Upload from this device — sends the file to the host. It lands in .qorin/uploads/ inside the workspace, and Qorin drops a .gitignore next to it so your uploads never show up as changes to commit.
• Browse host files — picks a file that's already on the host and hands its path to the CLI. Open to every tier: nothing is transferred, so there's nothing to meter.

What we cap, and why:

Limit	Value	Reason
File size	20 MiB	The agent assembles the file in memory before writing it.
At a time	one per user	Each byte crosses the control plane twice (you → us → host). One sequential stream also keeps chunk order intact on zero-knowledge workspaces.
Speed	2 MB/s per user	A 20 MiB file in about ten seconds, without one upload starving everyone else's.

Pick a second file while one is going and it waits its turn — the terminal says so rather than failing. On a Zero-knowledge workspace the file is sealed before it leaves your device; we relay bytes we can't read.

Terminate vs delete

• Terminate stops the CLI cleanly (sends SIGTERM via tmux, gives it 5s, then SIGKILL). The workspace row stays around in "discarded" state so you can read scrollback.
• Delete removes the row entirely (only allowed on terminal states). Best-effort: asks the agent to remove the worktree dir too, so disk doesn't fill up. Idempotent — works even if the agent is offline.

Branch picker

For git workspaces, the branch picker is editable. We do git fetch on the host before spawn, so freshly-pushed branches show up. If you type a branch that doesn't exist locally, the agent creates it from the repo's default branch (main / master).

Idle pruning

Workspaces that have been in a terminal state for >30 days get auto-deleted by the sweeper. The dashboard shows a warning on the row 7 days before that happens.

See also

• Repositories — folder vs git clone vs new
• Notifications — get pinged on awaiting_input
• Troubleshooting › workspace fails to spawn