Authoritative runtime
The authoritative runtime is the only thing that holds real state: Agent processes, session timelines, workspace files, Git repositories, terminals, the browser, computer use, provider credentials, and the local database. Every client is a projection of it. Vibex has three runtime forms with the same core:
The desktop workbench, mobile apps, and TUI are clients. The desktop uses its embedded runtime by default; you can switch it to a remote runtime, after which it is a client like the phone and the TUI. The entry point is the Runtime button in the title bar.
Project
A project is a folder registered in Vibex: it has a name, an icon, and a long-lived row in the sidebar. Right-click it to rename, customize the icon, create folders, import sessions, or delete it. A project can contain several workspaces.Workspace
A workspace is “one way of using this project”. There are three locations:
A project can have one
Local workspace and several Worktree workspaces at the same time. That is how you can keep working on the main branch while an Agent tries another approach in an isolated directory.
A session always belongs to one workspace (or to temporary space). Switching workspaces does not carry uncommitted changes across.
See Projects and workspaces.
Session
A session is the complete record of one development task: your input, Agent output, tool calls, approvals, and errors, stored in order as a timeline. A session belongs to the workspace where it was created. New session in the sidebar creates one. Sessions can be renamed, pinned, forked, archived, bulk-deleted, and imported from other Agents’ history. Several sessions can form a session group under one worktree and be viewed in split panes. Delegation creates child sessions, which hang under the parent’s ownership tree and have their own timeline. See Agent sessions.Agents and Providers
These terms are often mixed up:
An Agent can use only its own model Provider profile, or bind a shared Provider or route group. A switch only affects later runs; the existing timeline keeps its original identity.
See Agents and provider profiles and Providers, route groups, and the local gateway.
Scope
Some resources have a scope: global, user, project, or workspace. The smaller the scope, the less likely it is to affect unrelated projects. MCP servers currently offer user and workspace.Channel
The release channel determines product identity and data directory: Preview, RC, and Stable. They can be installed side by side, each with its own database. The channel is compiled into the package and cannot be changed at runtime.Pairing
Pairing grants a device access to an authoritative runtime. There are two common paths:- Desktop → phone / TUI: the desktop shows a QR code or link; the phone scans it and the TUI claims it with
vibex connect. - Server → desktop / phone / TUI:
vibex-serverprints a one-time code and connection string; the client enters them.
read_only, approve_only, or full_control. The initiator decides; a client cannot elevate itself.
See Remote access and mobile.