Vibex

Vibex brings Agent sessions, source code, Git, terminals, previews, and provider configuration into one focused workbench. The desktop runtime stays in control of Agent processes, session history, workspace files, Git, PTYs, providers, and permissions. A native mobile client lets you monitor and steer those same sessions remotely, while an optional self-hosted Relay carries only encrypted frames.

No Vibex-hosted workspace is required to run the local desktop. Your repository, credentials, and durable session state remain on the machines you choose.

Why Vibex

Principle	What it means in practice
Local-first authority	The PC owns the runtime and durable state. Mobile is a typed remote client, not a second backend.
Native by default	Rust and GPUI power the desktop and mobile clients without a browser shell or a separate WebUI product.
One Agent contract	Every online Agent session uses ACP and managed adapters, giving integrations a shared session, capability, permission, and terminal surface.
Remote without lock-in	Pair over Direct, Tailnet, or your own Relay. The Relay forwards encrypted frames and never becomes a second database.
Inspectable workflows	Plans, tool calls, process details, diffs, approvals, elicitation forms, errors, and reconnect states stay visible and explicit.
Provider choice	Configure Agents, model providers, credentials, MCP servers, Skills, Prompts, and Hooks inside Vibex-scoped configuration.

Features

Vibex is designed for the complete loop: ask an Agent to change code, inspect what it did, run the project, review the diff, and keep the session available wherever you are.

Workflow	Included
Agent sessions	Stream user and Agent messages as a structured timeline with Markdown, reasoning, plans, tool and process details, attachments, approvals, and typed elicitation forms. Stop, continue, fork, rename, and resume sessions, or import supported local histories.
Workspace and editor	Browse workspace-scoped file trees, search by name or content, read and write files with revision checks, and keep encoding, line endings, and large-file limits explicit.
Git-native review	Inspect status, history, diffs, and blame; create and switch branches; stage, unstage, revert, commit, fetch, and push; and manage isolated Git worktrees with guarded merge and rebase recovery.
Terminal and content	Use native PTYs with ANSI emulation, tabs, resize, scrollback, search, and raw-byte handling. Preview Markdown, images, PDFs, and supported Office documents in the workbench.
Agent and provider center	Discover and manage Agent runtimes, select models and reasoning options, authenticate providers, run health and capability probes, and keep provider profiles separate from online route identity. Providers are shared: one set of keys can serve several Agents without being configured per Agent.
Local model gateway	Point Agents at a loopback endpoint that routes each call to a shared Provider. It translates between the OpenAI Chat, OpenAI Responses, Anthropic Messages, and Gemini APIs, keeps a conversation on the key that holds its prompt cache, cools down a key that fails instead of retrying it forever, and records a token-only request ledger. Routing state never enters an Agent's process fingerprint, so replacing a key does not restart a session.
MCP and workflow resources	Import, validate, and scope MCP servers, Skills, Prompts, and Hooks. Give Agents reusable context without scattering configuration across unrelated home directories.
Automation	Schedule one-shot, interval, or daily Agent runs and compose automation graphs with explicit run state, recovery, and audit history.
Attention and continuity	Receive desktop notifications for completed, failed, or input-blocked sessions, track unread completions, and recover authoritative timeline state after reconnects or restarts.
Mobile companion	Pair an iOS or Android client with the desktop runtime, read the same GUI Agent timeline, approve or decline requests, send follow-ups, inspect files and Git state, and use remote terminal surfaces when available.

Supported Agents

Vibex uses the Agent Client Protocol (ACP) as the only online Agent transport. The runtime is provider-neutral: an Agent's identity and capabilities are kept separate from the protocol used to connect it. Works with any ACP-compatible agent — if it speaks ACP, it runs in Vibex.

Built-in presets include Claude Code, Codex, ZCode, and OpenCode. The ACP catalog also includes integrations such as Antigravity, Cline, Codebuddy, Cursor, Gemini CLI, GitHub Copilot, Devin, Grok Build, Hermes, Kimi Code, Pi, DeepSeek Harness, and more. Availability is checked against the installed runtime, provider configuration, and live capability probes.

You can also register any ACP-compatible executable with its command, arguments, environment, and display metadata. Adding an Agent does not require a new UI or a second vendor-specific session protocol.

Native Surfaces

Surface	Role	Entry point
Desktop	Full native GPUI workbench and the authoritative DesktopRuntime for Agents, workspaces, files, Git, PTYs, providers, permissions, and durable state.	Linux, macOS, and Windows targets; start with pnpm dev:desktop.
Mobile	Native GPUI iOS and Android companion. It renders the desktop session model as a GUI timeline and sends typed remote mutations.	apps/mobile; build with pnpm build:mobile:android or pnpm build:mobile:ios.
Self-hosted Relay	Optional Rust/Axum transport for encrypted WebSocket frames. It stores no workspace, provider, Agent, or application data.	apps/relay-server and deploy/relay; validate with pnpm smoke:relay:local.

Mobile never starts a local Agent, owns a workspace filesystem, mutates local Git, or becomes a second PTY authority. Its compact native UI preserves the desktop Agent timeline semantics, including loading, streaming, approval, error, and reconnect states.

Quick Start

Prerequisites

• Git with submodule support
• Node.js 22
• pnpm 11.3.0
• Rust 1.97.0, pinned by rust-toolchain.toml
• A graphical session and working Vulkan driver for desktop development

Native mobile builds additionally require the Android SDK/NDK and cargo-ndk, or macOS with Xcode, XcodeGen, and the Apple Rust targets. See the platform sections below for the exact commands.

Run the desktop workbench

git clone https://github.com/vibex-ai/vibex.git
cd vibex
git submodule update --init --recursive
pnpm install --frozen-lockfile
pnpm dev:desktop

The desktop app starts with a local runtime. Configure an Agent and provider in the Config Center, open a project directory, then create an Agent session from the workbench.

Repository checks

pnpm check
pnpm release:build-smoke
pnpm check:mobile-native

pnpm check runs the normal Rust, frontend, license, and deterministic behavior gates. pnpm release:build-smoke checks the native desktop, mobile, and Relay build graph. pnpm check:mobile-native validates the mobile crate and checked-in native project contract without claiming that an Android or iOS SDK is installed on the host.

Tagged releases use the free GitHub-hosted native matrix in .github/workflows/release.yml: Linux .deb/AppImage, macOS .dmg, Windows NSIS, signed Android APK/AAB, and unsigned iOS simulator/XCFramework artifacts are collected by one aggregation job. macOS/Windows signing and mobile store upload are optional credentialed follow-up steps; RC and preview Android packages can use an ephemeral CI key, while stable Android releases require a configured release keystore.

Development

Desktop packaging

Targeted desktop checks are useful while iterating:

cargo check -p vibex-desktop --locked
cargo test -p vibex-desktop --locked
pnpm smoke:first-frame

Linux preview packages use cargo-packager and the reviewed PDFium runtime:

cargo install cargo-packager --version 0.11.8 --locked
pnpm prepare:pdfium
pnpm package:preview

Use the release runbook before building RC or Stable packages. Generated packages and runtime binaries are build outputs and are not tracked in the repository.

Android

Install the Android SDK/NDK, cargo-ndk, and the Rust targets for the ABIs you will build. Debug defaults to arm64-v8a and x86_64; release defaults to arm64-v8a.

pnpm build:mobile:android
pnpm package:mobile:android

Set VIBEX_MOBILE_ANDROID_TARGETS to a space-separated ABI list to override the debug defaults. The local release APK is unsigned and must be aligned and signed with the intended release key before distribution; tagged release APKs are signed by the publish workflow.

iOS

On macOS, install Xcode, XcodeGen, and the aarch64-apple-ios plus aarch64-apple-ios-sim Rust targets:

pnpm build:mobile:ios

This builds VibexFFI.xcframework and generates the Xcode project. Signing, simulator or device selection, and distribution credentials remain local to the developer or release pipeline.

Self-hosted Relay

The Relay is optional. Pull the published image, or build it from source:

export VIBEX_RELAY_IMAGE=ghcr.io/vibex-ai/vibex-relay:v0.1.0-rc.8
docker compose -f deploy/relay/docker-compose.yml pull relay-server
docker compose -f deploy/relay/docker-compose.yml up -d --no-build relay-server
curl -fsS http://127.0.0.1:9700/health
docker compose -f deploy/relay/docker-compose.yml down

The headless runtime publishes ghcr.io/vibex-ai/vibex-server the same way; both images cover linux/amd64 and linux/arm64. Use the Relay deployment guide for HTTPS through Caddy, private Tailnet publication, runtime limits, and the optional operator-owned push adapter, and the headless runtime guide for the image tag rules. Keep the default loopback binding for local development.

Architecture

The desktop runtime is the single authority. Shared contracts and projections keep native desktop and mobile behavior aligned without duplicating business state.

DesktopRuntime
|-- ACP Agent sessions and authoritative timelines
|-- Workspace files, editor, Git, and managed worktrees
|-- Native PTYs, content previews, providers, and permissions
`-- Typed RemoteGateway v2
    |-- Direct or Tailnet transport
    `-- Encrypted self-hosted Relay
            -> AutoRemoteTransport
            -> Native mobile GPUI client

The main ownership boundaries are:

• crates/core defines serialized ids, DTOs, errors, capabilities, and remote protocol contracts.
• crates/desktop-model owns framework-neutral session and timeline projections and reducers.
• crates/vibex-backend exposes provider-neutral capability facades shared by native and remote adapters.
• crates/vibex-ui owns semantic tokens, portable component models, workflow controllers, and shell composition.
• crates/vibex-remote-client owns pairing, reconnect, synchronization, and Direct, Tailnet, and Relay route selection.
• apps/desktop owns the native workbench and DesktopRuntime; apps/mobile only composes the shared remote projections into a compact native surface.

Read the UI architecture boundary, platform support matrix, and Remote Protocol v2 for the detailed contracts.

Tech Stack

Layer	Technologies
Application	Rust 2024, Cargo workspace, Rust 1.97.0
Native UI	GPUI, gpui-component, shared Rust UI contracts, generated design tokens
Agent runtime	Agent Client Protocol schema 1.6, managed ACP adapters, Tokio
Workspace runtime	SQLite via rusqlite, filesystem and Git services, xpty, alacritty_terminal
Content	markdown (CommonMark/GFM through gpui-component), pulldown-cmark, HTML5ever, PDFium, ZIP/XML parsers
Remote transport	Axum, HTTP/WebSocket v2, Rustls, tokio-tungstenite, X25519, HKDF, HMAC, ChaCha20-Poly1305
Platforms	Linux, macOS, and Windows desktop; native Android and iOS through gpui-pre-mobile
Tooling	Node.js 22, pnpm 11.3.0, deterministic smoke tests and release quality gates

Privacy and Control

• Local-first storage: session timelines, workspace metadata, provider profiles, and runtime state are owned by the desktop runtime and stored locally.
• Explicit permissions: Agent tools, terminal actions, device access, and remote mutations are capability-gated and auditable.
• Encrypted remote access: Direct, Tailnet, and Relay routes use typed handshakes and encrypted transport. Relay forwards frames but cannot decrypt business payloads.
• Scoped provider configuration: Vibex does not rewrite real Agent home configuration by default. Export is an explicit user action with preview and rollback boundaries.
• Redacted diagnostics: tokens, private keys, prompts, file contents, and terminal bytes are excluded from logs and diagnostic artifacts.

Contributing

Issues and pull requests are welcome. Before opening a change:

• Keep DesktopRuntime as the only authority and route mobile behavior through typed backend and remote contracts.
• Run the smallest relevant gate while iterating, then run pnpm check for cross-layer changes.

License

Vibex is free software licensed under the GNU Affero General Public License v3.0 or later. Third-party package, font, icon, and PDFium notices are recorded in docs/licenses.