# Claude Code
Source: https://docs.avibe.bot/agents/claude-code
Run Claude Code through Avibe — from the browser Workbench or any chat app.
# Claude Code
Claude Code is a strong default for deep reasoning, complex refactors, and codebase-wide tasks.
## Install
```bash theme={null}
npm install -g @anthropic-ai/claude-code
```
Verify:
```bash theme={null}
claude --version
```
## Models & auth
Claude Code runs on your own Anthropic access — a Claude subscription or an API key. Avibe drives the *official* CLI, so your authentication and model choice are exactly what you'd use in a terminal. Pick the model per agent in the [Workbench](/concepts/workbench), and keep credentials local.
## Configure in Avibe
In the setup wizard:
1. Enable Claude Code.
2. Confirm the `claude` CLI path.
3. Choose a default working directory.
4. Route one or more chat channels to Claude Code.
## Best for
Deep reasoning, multi-file refactors, and tasks that span a whole codebase. A common setup routes your `#backend` or complex-logic channels here — see [Thread sessions](/concepts/thread-sessions) for per-channel routing and mid-thread switching.
## Usage notes
* Keep your Claude Code authentication local.
* Use chat threads to separate independent work.
* Ask for a small first task to verify permissions and project path before a large refactor.
## Smoke test
```text theme={null}
Read the current project root and summarize the repository in three bullets.
```
# Codex
Source: https://docs.avibe.bot/agents/codex
Run Codex through Avibe — from the browser Workbench or any chat app.
# Codex
Codex is the OpenAI coding-agent path for Avibe users.
## Install
```bash theme={null}
npm install -g @openai/codex
```
Verify:
```bash theme={null}
codex --version
```
## Models & reasoning effort
Codex runs on your own OpenAI access. In the [Workbench](/concepts/workbench) you pick the model and the **reasoning effort** per agent — lower for quick edits, higher for hard problems — the same knobs you'd set on the CLI, surfaced where you route work. Keep credentials local.
## Configure in Avibe
In the setup wizard:
1. Enable Codex.
2. Confirm the `codex` CLI path.
3. Choose a default working directory.
4. Route one or more chat channels to Codex.
## Best for
Quick experiments and prototypes, and tasks where you want to dial reasoning effort up or down. Route your `#prototypes` or experiment channels here — see [Thread sessions](/concepts/thread-sessions) for routing.
## Usage notes
* Keep OpenAI credentials local.
* Use one chat thread per task.
* Keep large tasks scoped with clear acceptance criteria.
# OpenCode
Source: https://docs.avibe.bot/agents/opencode
Run OpenCode through Avibe — from the browser Workbench or any chat app.
# OpenCode
OpenCode is a low-friction backend for users who want fast setup and an extensible local coding agent.
## Install
```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```
Verify:
```bash theme={null}
opencode --version
```
## Models & providers
OpenCode is provider-flexible: point it at a hosted model, an OpenAI-compatible endpoint, or a local model if you want inference on your own hardware too. That makes it the most "local all the way down" option of the three. Configure the model per agent in the [Workbench](/concepts/workbench).
## Optional permission behavior
If you understand the tradeoff and want less interruption during agent work, configure OpenCode permissions according to your local policy.
Example:
```json theme={null}
{
"permission": "allow"
}
```
Only use broad permissions in repositories and machines where you're comfortable with that level of autonomy.
## Configure in Avibe
In the setup wizard:
1. Enable OpenCode.
2. Confirm the `opencode` CLI path.
3. Choose a default working directory.
4. Route one or more chat channels to OpenCode.
## Best for
Fast iteration, lightweight tasks, and setups where you want inference local too. A common pattern routes your `#frontend` or quick-turnaround channels here — see [Thread sessions](/concepts/thread-sessions) for routing.
# Install for AI agents
Source: https://docs.avibe.bot/ai/install-for-ai
A setup runbook designed for Claude Code, Codex, OpenCode, and other AI coding agents helping a user install Avibe.
# Install for AI agents
This page is written for an AI coding agent helping a human install Avibe.
## Rules
* Ask before choosing a chat platform, agent backend, workspace, or credential value.
* Do not guess secrets, bot tokens, app tokens, API keys, workspace IDs, or chat IDs.
* Prefer the browser setup wizard launched by `vibe` over hand-editing config files.
* Do not restart an already-running local `vibe` service unless the user confirms it is safe.
* Keep setup local-first. Do not expose public webhooks unless the selected platform requires it.
## 1. Check the machine
```bash theme={null}
uname -a
command -v vibe || true
command -v uv || true
command -v claude || true
command -v opencode || true
command -v codex || true
```
On Windows, prefer WSL unless the user explicitly wants native PowerShell.
## 2. Install Avibe
macOS / Linux:
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash
```
Open source — view the [script on GitHub](https://github.com/avibe-bot/avibe/blob/master/install.sh). The short URL is a 307 redirect to that file.
Windows PowerShell:
```powershell theme={null}
irm https://raw.githubusercontent.com/avibe-bot/avibe/master/install.ps1 | iex
```
Verify:
```bash theme={null}
vibe version
vibe doctor
```
## 3. Install one coding agent
Ask the user which backend they want first.
Recommended default:
* OpenCode for low-friction setup.
* Claude Code for deeper codebase work.
* Codex for OpenAI workflows.
OpenCode:
```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```
Claude Code:
```bash theme={null}
npm install -g @anthropic-ai/claude-code
```
Codex:
```bash theme={null}
npm install -g @openai/codex
```
Verify:
```bash theme={null}
opencode --version || true
claude --version || true
codex --version || true
```
## 4. Start the setup wizard
```bash theme={null}
vibe
```
Help the user choose:
1. Chat platform.
2. Agent backend.
3. Project working directory.
4. Channel or chat scopes that should be enabled.
## 5. Optional remote Web UI
If the user wants to open the local Web UI from another device:
```bash theme={null}
vibe remote
```
Use this for Web UI access, not for exposing the agent runtime directly.
## 6. Smoke test
Ask the user to send:
```text theme={null}
Say hello and tell me which project directory you are running in.
```
Then verify:
```bash theme={null}
vibe status
```
If messages do not arrive:
```bash theme={null}
vibe doctor
```
# Avibe vs OpenClaw and Hermes
Source: https://docs.avibe.bot/compare/openclaw
OpenClaw and Hermes are agents. Avibe is the Agent OS the agents you trust run in.
# Avibe vs OpenClaw and Hermes
These tools get compared a lot, but they sit at different layers.
**OpenClaw** and **Hermes** are *agents*. OpenClaw is a gateway-first personal assistant — a messaging gateway wrapped around an assistant. Hermes (from Nous Research) is a self-improving agent with its own learning loop and persistent memory. Both *are* the intelligence you talk to.
**Avibe** is a different layer: the **Agent OS**. It doesn't try to be the agent. It gives agents a place to live — a unified world model of agents, sessions, [Show Pages](/concepts/show-pages), and the [Harness](/concepts/harness) — and runs the *official* Claude Code, Codex, and OpenCode you already trust. (An Avibe-native agent is [on the roadmap](/concepts/vision), alongside the ones you bring.)
## Comparison
| Area | Avibe | OpenClaw | Hermes |
| - | - | - | - |
| What it is | The Agent OS the agents run in | A gateway-style personal assistant | A self-improving agent with a learning loop |
| The agent | The official Claude Code / Codex / OpenCode you bring | Its own assistant loop | Its own agent, with memory |
| Lock-in | Bring your own keys; switch agents per task | Tied to its assistant loop | Tied to its agent |
| Token overhead | None in between — tokens go straight to your chosen agent | Carries assistant / orchestration context | Runs its own agent's reasoning |
| Human interaction | Browser Workbench, Show Pages, voice, and chat | Chat-first | Chat / CLI |
| Setup | One command plus a web wizard | Gateway + channels + config | Setup wizard (can import from OpenClaw) |
Descriptions of OpenClaw and Hermes reflect their own published positioning. Both are capable tools — they just aim to be *the* agent rather than the layer an agent runs in.
## The key distinction
Avibe does not try to become the agent.
It lets Claude Code, OpenCode, and Codex run as themselves on a substrate you own, in the same communication flow as you — and gives them OS-level primitives to schedule, watch, show, and act on their own timeline.
```text theme={null}
chat app / Workbench -> Avibe (the OS) -> the agent you chose
```
No hidden intelligence layer relays your work. Pick a tool that *is* a great agent and you get that agent; pick Avibe and you get the home any agent runs and thrives in — the ones you trust today, and an Avibe-native one tomorrow. → [Design Philosophy](/concepts/philosophy)
# What is Avibe
Source: https://docs.avibe.bot/concepts/agent-os
Avibe is the local-first Agent OS — the operating layer an AI agent lives in, on your own machine.
Avibe is the **local-first Agent OS**. One install command turns your own machine into the runtime an AI agent lives in, and you operate that agent from a browser Workbench or any chat app.
Coding is the first strong workload — not the product boundary.
## The model
Think of Avibe as the layer between your machine and the way you already work:
* **Substrate** — your own machine becomes the place the agent runs and lives.
* **Inhabitant** — an official first-party agent (Claude Code, Codex, or OpenCode) is the partner living there.
* **Interface** — you talk to it from a browser Workbench, or from Slack, Discord, Telegram, WeChat, and Lark.
* **Access** — `vibe remote` gives that machine a public address through the avibe.bot tunnel, so you can reach it from anywhere.
## What makes it different
### Local-first, and yours
Your AI partner, its execution, and its local state stay on your own machine. Remote Web UI returns to that machine through a secure tunnel. Model-backed features use the providers you choose or the models supplied for Avibe features. The [Local-first boundary inventory](/concepts/local-first#what-leaves-your-machine) shows exactly what crosses the network in each mode. This is an architectural stance, not a setting.
### One substrate, every first-party agent
Avibe drives the *official* Claude Code, Codex, and OpenCode directly — not a cut-down embedded copy. Bring your own subscription or API keys, switch agents per task, and never get locked into one vendor's silo. → [Claude Code](/agents/claude-code) · [OpenCode](/agents/opencode) · [Codex](/agents/codex)
### It keeps its own timeline
The Agent Harness gives your partner durable primitives — run a job, schedule a time trigger, watch a condition, inspect history — so it can act without you pressing a button. → [Commands](/reference/commands)
The **Runs** graph makes Agent-to-Agent delegation inspectable: see which Session started each background Agent, where its result reports back, and the execution history behind every node.
### It can show, not just tell
Show Pages let the agent hand you a live web page — a dashboard, a diagram, a diff, a report — reachable from your phone through the same tunnel.
## Where to go next
* Install and run: [Quickstart](/quickstart)
* What stays on your machine: [Local-first](/concepts/local-first)
* One thread, one session: [Thread sessions](/concepts/thread-sessions)
* Reach it from anywhere: [Remote UI](/concepts/remote-ui)
* Control secret delivery: [Vaults](/concepts/vaults)
* Why we built it this way: [Design Philosophy](/concepts/philosophy)
* The bigger picture: [Vision](/concepts/vision)
# Annotating Show Pages
Source: https://docs.avibe.bot/concepts/annotating-show-pages
Point at anything on a Show Page — an element, a region, a screenshot — and tell your agent what you mean. Answers come back on the page.
A [Show Page](/concepts/show-pages) isn't a read-only handout. Annotation turns it into a two-way surface: you point at exactly what you mean — a chart, a paragraph, an empty gap that looks wrong — say a word about it, and your agent picks it up like any other message. When the answer is easier to *show* than to describe, it comes back **on the page**, pinned next to the thing you pointed at.
It's the same instinct as Show Pages themselves, run in reverse: instead of the agent handing you a page, you hand the agent a spot on it.
Annotation and on-page replies arrive with a recent Avibe release. If your chat has no annotation control on a Show Page, or `vibe show` doesn't list the `annotate` / `reply` / `marks` commands yet, run `vibe upgrade` and reload.
## Turn on annotation
When you open a Show Page inside the [Workbench](/concepts/workbench) chat, an **Annotate** control appears in the page header, next to the button that takes you back to the conversation. It's **off by default** — the page behaves like a normal page until you turn it on.
* **On desktop**, the control starts as a single icon. Activate it and it expands into a small segmented group: the **Annotate** toggle plus the two modes, **Smart** and **Screenshot**.
* **On a phone**, it's one button that opens a compact popup — pick **Smart** or **Screenshot**, or **Turn off annotation**. Tapping the button turns annotation on in whichever mode you used last.
Annotation opens in **Smart** mode the first time, and after that it remembers the mode you used. On desktop, press **Option+X** on macOS or **Alt+X** on Windows and Linux to turn annotation on, and hover over the annotation button to see the current shortcut. Change it for the current browser under **Settings > Shortcuts**. Press **Esc** any time to leave. While annotation is off, clicks, links, and controls on the page work exactly as before.
## Smart mode — point and say
Smart mode is for pointing at what's already on the page.
1. **Click an element**, **select some text**, or **drag a box** around a region. A comment card opens, anchored to what you picked.
2. Give it an **intent** so the agent knows what kind of response you want:
* **Comment** — a note or observation.
* **Change** — you want this reworked.
* **Question** — you're asking about it; the agent is nudged to answer right here on the page.
* **Approve** — a one-tap sign-off. No typing needed.
3. Send. Your annotation lands in the chat as a message and your agent responds — reworking the page, replying on it, or answering in chat, whichever fits.
Because **Approve** needs no text, signing off on something is a single tap.
## Screenshot mode — mark up a capture
Sometimes the point isn't one element — it's how a few things look together. Screenshot mode captures a region and lets you mark it up.
1. **Drag a box** around the area you care about. Avibe captures it locally, in your browser — there's no screen-sharing prompt, and it works on iPhone-class devices where screen capture normally isn't available.
2. Drop **numbered comments** onto the capture — "1" here, "2" there — as many as you need.
3. **Send them together** as one batch, so the agent gets the whole picture and your notes in order.
On touch, page scrolling locks while you're marking a region so your drag stays precise. Press **Esc**, or toggle annotation off, to scroll normally again.
## On a standalone page
Open a Show Page on its own — a direct `/show/…` tab, or a page you've [pinned to the Dock](/concepts/apps-dock) — and there's no chat header to hang the control on. Instead a small **floating button** sits in the bottom-right corner. It opens the same modes and produces the same result: your annotation still flows back to the session's conversation, and the agent still answers.
## What happens after you send
Your annotation shows up in the chat as a normal message (tagged so you can tell it came from the page) and kicks off a reply, just like anything else you send.
The agent can also answer **on the page**. When it does, a **violet dot** appears next to the element you pointed at — a short reply, anchored to your question. Open it to read the answer; once you've read it, the mark **retires**: it fades to a quiet gray and won't come back on the next load. Think of these as conversation bubbles, not sticky notes that pile up forever.
A few things keep the page calm:
* At most **five** unread marks show inline at once. Any beyond that collect into a **badge in the bottom-right corner** whose list holds every active mark.
* If the agent reworked the page and a mark's original spot is gone, that mark moves into the badge list labeled **"original location updated"** — its text is still there to read, and it's never pinned to the wrong place.
## Public pages: who can annotate
When you [publish a Show Page](/concepts/show-pages) as a public `/p/…` link, the read and write sides are treated differently:
* **Anyone with the link can view** the page and read the marks on it.
* **Annotating requires being signed in** to the workbench in the same browser. An anonymous visitor sees the page read-only, with no annotation control. Sign in and the control appears.
Every annotation records **who made it** — your workbench identity — so you and the agent can tell contributions apart. Nothing you annotate is anonymous, and public links never let a stranger write to your page.
## Answering on the page: reverse marks
The second half of the loop belongs to the agent. You don't run these commands yourself — you ask for the behavior ("answer my page questions on the page", "flag anything you changed") and the agent uses the `vibe show` commands below. They're worth knowing when you're writing agent instructions, and they're the reference an agent follows.
| Command | What it does |
| - | - |
| `vibe show reply --message "…"` | Answer a specific annotation, anchored where you pointed. Replying again to the same annotation replaces the earlier reply. |
| `vibe show mark --message "…"` | Leave a proactive callout on an element — a named page anchor or a CSS selector. Marking the same target again replaces the previous note. |
| `vibe show marks` | List the marks currently active on the page. |
| `vibe show unmark …` | Retire one or more marks (space-separated). |
| `vibe show annotate --on \| --off [--mode smart\|screenshot]` | Turn your annotation overlay on or off, or switch its mode, from the agent's side. This only steers the overlay — it never posts a chat message. |
The agent barely has to construct anything: each annotation that reaches it carries its own event id, and many arrive with a ready-to-run `vibe show reply …` line. Whether to answer on the page or just edit the page content is the agent's call, per situation.
An agent can also declare a note straight in the page it writes, with an `agent-note` attribute on any element it authors:
```jsx theme={null}
```
That kind of note lives and dies with the element — rewrite or remove the element and the note follows on the next render. (Named `mark-*` anchors say *where* something is; `agent-note` says *what* the agent wants to tell you about it.)
**The lifecycle, in one breath:** marks are conversation bubbles. Unread ones show as a violet dot; reading one retires it for good. A reply stays paired to the annotation it answers. Agents are guided to leave only one or two marks per turn; at most five render inline and the rest fall into the badge; and a mark whose anchor no longer resolves degrades into the badge list rather than being guessed onto the wrong spot.
The page carries the conversation; the chat keeps the transcript. Between the two, pointing at your agent's work and getting an answer back is just… talking. See [Show Pages](/concepts/show-pages) for everything a page can be in the first place.
# Apps & the Dock
Source: https://docs.avibe.bot/concepts/apps-dock
The Show Pages your agent builds become real apps — installed in the App Library, kept in the Dock, opened in windows.
Every [Show Page](/concepts/show-pages) your agent builds is really an app it made for you. The [Workbench](/concepts/workbench) treats it like one: install it in the **App Library**, keep the ones you use in the **Dock**, and open it in a window beside your chat. This is the [Agent OS](/concepts/agent-os) model made literal — your agent doesn't just answer, it hands you software you can keep.
## Two layers: installed and docked
Apps live in two overlapping sets:
* **Installed** — everything in the App Library's **Apps** list. The built-in apps (Files, Terminal, Editor, and the App Library itself) are always installed; a Show Page becomes installed when you add it.
* **Docked** — the subset you keep in the **Dock**, the tile strip along the bottom. Docking an app puts a tile there; undocking removes the tile but leaves the app installed.
Built-in apps can be docked or undocked freely, but never removed from the list. A Show Page can be undocked (tile gone, still installed) or removed entirely (gone from the Apps list — the page itself is untouched). The Dock can even be empty; when it is, it shows a shortcut to open the App Library, so you're never stranded.
Right-click any Dock tile for **New Window**, **Show All Windows**, **Open in New Tab**, and **Unpin from Dock**. Drag tiles to reorder them — your Dock and its order follow you across devices.
## The App Library
The **App Library** is a built-in app that manages everything. Reach it from its own Dock tile, the **App Library** entry in the sidebar, the empty-Dock shortcut, or by right-clicking the Apps launcher in the bottom-left corner. It has two tabs.
### Apps
The installed set — built-ins plus every Show Page you've added.
* **Reorder** — drag the grip handle at the front of a docked row; the order syncs with the Dock.
* **Dock / Undock** — toggle whether the app shows in the Dock. The row stays in the list either way.
* **Remove App** — on a Show-Page row (marked with an **AI** badge), takes it out of the Apps list. The page itself is untouched, and built-in apps have no Remove.
* **Click a row** to open the app.
### ShowPage
The full inventory — every Agent Session has a Show Page, so this lists them all, not just the ones you've installed. Each row shows the page's status, its visibility (private / public / offline), and its live link.
* **Add to Apps** installs the page as an app (and docks it). Once installed, the same control becomes **Remove App**.
* **Click the title or icon** — there's an open affordance on hover — to open the app in a window.
* **Expand a row** for its details panel, where you can:
* **Rename** the page. This renames the session, so the new name shows everywhere.
* **Upload an icon** — see [Icons](#icons) below.
* Set **visibility** and manage the **share link** and its custom suffix.
## Windows
Opening an app — a Dock tile, a Library row, ⌘K, or a keyboard shortcut — opens a Mac-style window you can drag, resize, minimize, maximize, and close. A Show Page window shows the live page, so it keeps updating as the agent edits it.
The title bar carries these buttons on the right:
* **Annotate** — turn on Show Page annotation and mark what the agent should change.
* **Open Chat** — jump back to the session that owns the page. The window minimizes so the chat is in front; its Dock tile brings it back. Watch the page change in the Dock thumbnail while you tell the agent what to do next.
* **Share** — set visibility and manage the share link without leaving the window.
* **Open in New Tab** — open the page in a full browser tab.
A public page opens the same way inside the window, through your own authenticated view; the anonymous link you hand to other people still lives at `/p/`.
## Keyboard & windows
* **⌥1**–**⌥9** (Option / Alt) — jump to the *N*th app in the Dock.
* **⌥W** — close the focused window. Typing surfaces (text inputs, the editor, the terminal) keep ⌥W for character entry, so it only closes a window when your focus is elsewhere.
* **⌘K** — search opens apps and every Show Page (installed or not); press Enter to open a result as a window.
* Closing the browser tab while a window is open triggers the browser's own "leave site?" confirmation, so you don't drop a window by reflex.
## Icons
An app's icon comes from the page's own files, resolved in this order:
| Priority | Where the icon comes from | Notes |
| - | - | - |
| 1 | An explicit `` in the workspace `index.html` | The href must be a **relative file inside the workspace** — SVG, PNG, ICO, JPEG, or WebP, up to 2 MiB; a leading `` is honored. If the exact path doesn't exist on disk, the same path is also tried under `public/` — matching Vite's publicDir root-mapping, so `href="./icon.png"` with the file at `public/icon.png` works. Absolute paths, external URLs, `data:` URIs, and JS-injected icons don't count — the icon must exist as a file on disk. |
| 2 | A conventional favicon file | `favicon.` at the workspace root, then under `public/` — trying `svg`, `ico`, `png`, `webp`, `jpg`, `jpeg` in that order. |
| — | None of the above | A colored letter tile drawn from the app's title. |
You can also **upload** an icon from a page's details panel in the App Library — it's saved as a conventional `favicon.` at the workspace root (priority 2). A usable explicit `` still wins over an uploaded file, because Avibe never edits your HTML. The default Show Page template's `` includes a comment spelling these rules out, so the agent building your page knows to give it an icon — dropping a `public/favicon.svg` is enough.
## On mobile
Windows are desktop-only, but your apps still come with you. The bottom **Apps** tab — where **More** used to be — opens a drawer that mirrors your Dock: the same apps in the same order, because docking syncs across devices. Tap an app to open it full-screen; long-press to manage it. The former More items now live as chips along the drawer's footer: **Settings**, **Account**, **Appearance**, and **More…**
## You can just ask
You don't install apps by hand any more than you invoke [Show Pages](/concepts/show-pages) by hand. Ask for the outcome, let the agent build the page, and keep the ones worth keeping — the good tools your agent makes become part of how you work, right where you already operate it.
# The Agent Harness
Source: https://docs.avibe.bot/concepts/harness
Durable primitives that let your agent work on its own timeline — schedule, wait, run in the background, and report back.
Most AI tools only act when you type. The **Agent Harness** gives your agent its own timeline: a small set of durable primitives it can combine to start work, wait for the right moment, run in the background, and come back with results — without you babysitting a terminal.
## The primitives
* **Run** — execute one Agent job now. Synchronous when you want an answer, or `--async` to run in the background.
* **Task** — a *time* trigger. "Every weekday at 9am", "tonight", "once after lunch." Recurring (`--cron`) or one-off (`--at`).
* **Watch** — a *condition* trigger. Wait for a PR review, a CI result, a deployment, a file, a log line, or a long-running process — then act.
* **Runs** — the history. Inspect what happened, continue from a run, or cancel work when the situation changes.
All four share one run record, so a scheduled task and a watched condition produce the same kind of inspectable Agent Run.
## Ask in plain language
You don't memorize flags. Ask your agent:
* "Watch this PR and come back when there's actionable review feedback."
* "Run the deployment check every weekday morning and post the summary here."
* "Start a separate investigation session for this incident, but report the conclusion to this channel."
* "If CI fails, summarize the logs; if it passes, tell me whether the PR is mergeable."
The agent composes the Harness commands behind the scenes.
## Sessions and delivery
A Harness run can **continue** the conversation it came from — same thread, same context — or **fork** a fresh session for an independent investigation. When configured with a delivery target, it reports back to the originating thread, a parent channel, or the [Workbench](/concepts/workbench) Inbox. A standalone definition can intentionally omit delivery; its result remains available in run history instead.
For CLI-driven branching, use `vibe agent run --fork-session `.
Avibe creates a new Agent Session and asks the native backend to fork the source
context. The fork keeps the source backend; `--agent`, `--model`, and
`--reasoning-effort` are allowed only as same-backend overrides.
## Why it matters
This is the concrete, shipped step toward [tension-driven agency](/concepts/philosophy): an agent that can leave the current chat turn, wait, return, branch, and keep records — instead of only reacting to your latest message. Self-initiated turns show up live in the [Workbench](/concepts/workbench).
## Reference
Full CLI for each primitive is in [Commands](/reference/commands): `vibe agent`, `vibe task`, `vibe watch`, and `vibe runs`.
# Local-first architecture
Source: https://docs.avibe.bot/concepts/local-first
Understand what stays local, what connects to chat platforms, and what avibe.bot is for.
# Local-first architecture
Avibe runs on your machine.
Your codebase, working directory, agent CLI, agent process, logs, and local configuration stay local. Local-first is an architectural stance, not a setting — see [Design Philosophy](/concepts/philosophy).
## Data flow
```text theme={null}
You
-> chat app
-> Avibe on your machine
-> Claude Code / OpenCode / Codex
-> Avibe
-> chat app
-> You
```
Avibe is the local runtime that lets your AI colleague live in chat while the actual agent work stays on your machine. It does not add a hidden LLM loop between you and your chosen agent.
## Why this matters
* No hosted coding VM is required.
* No public inbound port is required for normal chat control.
* The agent sees the same local project state you would see in a terminal.
* Token overhead stays near zero because Avibe does not act as a second reasoning agent in front of your chosen agent.
## What leaves your machine
Your code at rest, working directory, Agent process, logs, local configuration, and local Agent credentials stay on your machine. Local-first does not mean offline-only.
This table is the authoritative boundary inventory. It covers every network path that carries user content or metadata derived from that content, in every available mode. A new path must be added here before it ships.
| Path | Personal Avibe | Enterprise-managed Avibe |
| - | - | - |
| Chat apps and Remote Web UI | Messages pass through the chat service you choose. Remote Web UI browser traffic returns to your machine through its secure tunnel; the avibe.bot application authenticates access but does not proxy that browser content. | Same boundary. |
| Agent model calls | Your Agent sends task prompts and context to its configured AI provider. Agent and Model Hub credentials stay on your machine. | Same boundary. Organization Model Service settings do not change your Agent models. |
| Voice input | Audio and transcript-cleanup text go through avibe.bot to Avibe's cloud models. | Audio and transcript-cleanup text go through avibe.bot to the provider configured by your organization. |
| Platform free pool | This is the default model source for personal Voice input. Avibe's cloud models process the Voice content listed above. | Never used as a fallback. Missing organization models surface as unavailable instead. |
| Organization BYOK credentials | Not used. | Provider API keys entered in Config Center are encrypted at rest on avibe.bot, cannot be read back, and stay bound to the endpoint addresses they were saved for. They are used only by Model Service on the server. |
| Model Service usage records | avibe.bot stores per-instance token-count metadata for Model Service calls. | Same boundary; organization usage is still attributed by Avibe instance. |
Each external platform or provider handles the traffic it receives under its own policies.
## What avibe.bot is for
`avibe.bot` provides the hosted control plane for secure remote Web UI access and the separate Model Service for Voice input.
When you run:
```bash theme={null}
vibe remote
```
Avibe helps pair your local Web UI with an authenticated remote URL. Browser traffic goes through the tunnel to your local machine rather than through the avibe.bot application. Your codebase and agent runtime remain local. Access is **fail-closed** — auth, routing, and host checks default to deny — so a misconfiguration locks you out rather than exposing your machine.
# Model Hub
Source: https://docs.avibe.bot/concepts/model-hub
Connect subscriptions and API keys once, then control which source each Agent model uses and how it recovers.
Model Hub is Avibe's default local model gateway. It keeps upstream credentials and routing on your machine, lets several Agent backends share the same source, and moves a request to the next configured source when the current one can recoverably no longer serve it.
Model Hub routes your own models to your Agents on your machine. It is separate from [Model Service](/concepts/model-service), which supplies cloud models for Avibe features such as Voice input.
The **Models** page has three tabs:
* **Sources & gateway** configures where models come from and how each Agent reaches them.
* **Usage** shows calls metered by the Gateway. See [Explore usage](#explore-usage).
* **Subscription quota** shows the limits of each subscription signed in as a gateway Source and what its use is worth at API prices. See [Check subscription quota](#check-subscription-quota).
Open **Models > Sources & gateway**. The page has two parts:
* **Sources** lists the subscriptions and API keys you own. It is an inventory, not a priority list.
* **Gateway** shows each Agent backend and the effective Route chain for each model, inherited from default routing or saved as a manual override.
## Choose gateway or direct mode
Gateway mode is the default on a fresh installation. An existing installation with no Model Hub configuration stays in **Direct** mode until you switch each backend from the Models page.
The choice is per backend and reversible. Switching back to Direct keeps your Sources and Route chains, but that backend resumes using its own native configuration. A **Native** hop inside a Gateway Route chain is still Gateway mode: Avibe owns fallback and recovery for that chain.
## Add a Source
### Add a subscription
1. In **Sources**, select **Add subscription** and choose the vendor.
2. Choose where the credential stays.
3. Select **Sign in** and complete the vendor flow.
The recommended choice depends on the vendor:
* **Claude:** **Use natively** is recommended. Claude Code uses its local login. You can explicitly choose **Sign in as a gateway source** to supply other Agents, but Avibe shows the account-restriction warning before sign-in.
* **ChatGPT:** **Sign in as a gateway source** is recommended. It makes usage, [quota](#check-subscription-quota), and takeover visible. Native Codex sign-in remains supported, but quota exhaustion will not trigger Gateway takeover and its usage stays outside Model Hub.
Each backend can have only one Native Source because its official CLI exposes one current login. Add additional accounts as gateway-held Sources. You can keep both channels by adding them one at a time.
### Add an API key
1. Select **Add API key**.
2. Enter an optional name, a Base URL, and the API key. A custom Base URL can point to a relay, aggregator, or self-hosted compatible service.
3. Select **Add**. Avibe connects once, authenticates, identifies the interface, and fetches the model list before saving.
**Fetch models** runs the same check without saving anything. If Avibe connects but cannot identify the interface, choose a one-time interface hint and retry. The hint only changes probe order; Avibe still requires a successful response before it can save the Source. The identified interface is fixed after save. To change it, create a new Source.
If the interface is identified but the model list does not return, you can retry or select **Add anyway**. The Source is saved without a discovered inventory, and you can add models manually from Source details.
### Maintain the model list
After a Source is added, Avibe opens **Source details > Models**. From there you can:
* Select **Refetch** to test the saved Source, update its health, and refresh discovered models. This is the only saved-Source refresh action.
* Add a model manually when discovery cannot find it.
* Edit the exact reasoning tiers accepted by any discovered or manual model. No tier is selected or filled by default.
* Remove models you added manually. Models reported by the upstream are managed by refetch instead.
Refetch preserves manual models and the reasoning tiers you edited. Inventory changes can change automatic matching. If a change would remove effective hops or leave models without supply, Avibe shows the affected hops and models before asking you to confirm. A failed fetch keeps the last list the page actually read.
For API-key Sources, the model list is matching evidence, not a list of the only models they may serve. A missing entry does not block an API-key request, and removing a manually added model does not delete a saved route. An explicitly retired Source/model pair cannot be used. Backend model support, Source compatibility, credentials, and health still apply; an unknown model does not acquire reasoning tiers that the Source has not declared for that exact model.
Subscriptions, whether signed in as gateway Sources or used natively, keep their existing model support. They still participate in automatic matching and manual routes, but new or changed subscription hops must pass the existing model-list and retirement checks. Routing does not extend the models supported by the Gateway or native CLI for a subscription.
## Configure default routing
In **Gateway**, choose a backend and open **Default routing** to select its default Sources and arrange their order. Models without a nonempty saved manual override follow these defaults; an empty saved chain also inherits them. Each effective Route chain is an ordered list of exact pairs: a Source and the upstream model it should call.
For example, suppose two API-key Sources have the default order A, then B, and you request `model-x`. If only B lists `model-x`, the chain contains only B. If neither Source lists it, the chain is A, then B, using `model-x` unchanged at each hop. It does not try an unmatched A before a known match on B.
Avibe first includes all eligible matches in default order, including matching subscriptions. Only when there are no matches does it use eligible default API-key Sources with the requested model ID unchanged. Subscriptions are not candidates for unknown-model passthrough. Native Claude matching recognizes its supported aliases and versions; other backends and API Sources use exact model IDs. Temporary unavailability does not turn a matched chain into passthrough.
New models follow defaults automatically. Changes to default membership, order, or matching evidence update inherited routes; they leave saved manual chains unchanged. The dialog shows how many models inherit defaults and how many have saved overrides. Changes apply only to the selected backend.
Select **Save** once to apply the default membership and order, including changes to inherited routes; there is no second affected-routes confirmation. Avibe still checks the exact impact with the server. If that impact changes while saving, the save stops and keeps your draft for retry. Removing a Source from defaults keeps manual routes that use it; deleting the Source itself removes its references through a separate guarded change.
## Manage a backend's model list
The models an Agent backend offers in Gateway mode come from its model list in Model Hub. In **Gateway**, select **Manage models** on a backend to add, edit, reorder, and remove its models. The order there is the order the Agent sees in its model pickers.
You can also open that list from the place where you pick a model. In Avibe's Web interface, every model list for a Gateway backend ends with **Add model**: the chat header, the new-session composer, project settings, the Agents page, and the channel and DM routing settings. It opens Model Hub with that backend's model list in front.
* **Add model** appears only for a backend in Gateway mode, and only for the instance Owner, who is the only person who can open Model Hub. A backend in Direct mode lists its own native models, so there is nothing for it to open.
* Closing Model Hub returns you to where you were, including an unsent message or a partly filled **New Agent** form, on desktop and mobile.
* The model list reads again when you return, so a model you just added is ready to pick. Until that read finishes, the list shows it is loading rather than models from before your visit.
## Edit a model route
Open a model in **Gateway** to inspect its chain. For an inherited route, select **Edit route** to start a manual draft. You can:
* add or remove a hop;
* reorder hops;
* change a hop's explicit upstream model mapping, including an exact ID absent from an API-key Source's model list; and
* select **Save** to store a nonempty chain as a manual override.
Manual hops may use compatible Sources outside this backend's defaults. Saving a nonempty chain creates a manual override, even if it is identical to the automatic result. An empty chain is treated as no override: saving it restores inherited routing, not a disabled model.
If a configuration Save requires a Gateway restart, Avibe waits for existing request transfers, including streams, to finish or close before restarting. New requests wait while the change is applied; saving does not cut off an active stream.
The first runnable hop is used. Avibe walks the remaining hops when a hop is already blocked, or when it hits a fallback-eligible quota, rate, upstream, or network failure before output begins. Blocked hops stay visible in their planned positions; temporary health changes do not reorder the chain or substitute another model.
On upgrade, empty routes saved by earlier versions follow current defaults, including those Avibe originally generated. Nonempty routes keep their exact hops and order as manual overrides, even if originally generated, identical to the automatic result, or using models no longer listed. Retaining a stale subscription hop does not bypass subscription model checks. Use **Restore automatic** to make a nonempty override follow current defaults.
### Restore automatic routing
In the route dialog footer, select **Restore automatic** to preview the inherited chain. Removing the last hop from a manual draft opens the same restore preview. This changes only the draft, and the result may be **Passthrough** or **Unconfigured**. **Undo restore** brings back the preceding manual draft.
On **Save**, Avibe checks the effective route's impact and asks you to confirm if needed before removing the override and applying inherited routing. The saved route stays unchanged until saving succeeds. **Cancel** or closing the dialog writes nothing. If saving fails, the draft stays available to retry.
## Read the status
Each model's route badge explains where its chain comes from:
| Badge | What it means |
| - | - |
| **Automatic** | Matching Sources form the chain in backend default order. |
| **Manual** | A nonempty saved override supplies the exact hops and order. |
| **Passthrough** | No eligible default Source has a match; eligible API-key defaults receive the requested model ID unchanged. |
Hover over or focus a badge for its explanation, or tap it on touch devices without opening the route dialog. Escape or interaction outside the help dismisses it. These badges describe routing, not Source health or a guarantee that the upstream accepts the model; stopping the Gateway does not change the route's origin.
If inheritance produces no eligible hops, the model shows **Unconfigured**. This includes an unmatched model whose defaults contain only subscriptions. Use **Configure default routing** to choose eligible default Sources, or save a nonempty manual route. Health changes and request errors do not change the route's origin.
Source rows use these states:
| What you see | What it means |
| - | - |
| **Saved** | Configuration is stored, but a successful model request with the current configuration has not yet been recorded. This is not an error or a health guarantee. |
| **In use** | The Source is included in at least one effective route. |
| **Standby** | The Source is healthy but is not currently supplying a configured route. |
| **Unavailable · retrying automatically after ...** | Quota, rate, or network trouble put the Source in cooldown. Avibe retries after the shown delay. |
| **Sign in again**, **Out of balance**, **Credential revoked**, or **Account restricted** | The Source needs your action and will not recover by waiting. |
| **Error** | Avibe could not classify the failure. It will not clear automatically. |
**Saved** uses neutral styling. Its connection hint explains the status; it does not ask you to repair anything. A successful model request updates pending verification. Actual cooldown, credential, or error states take priority over **Saved**.
Each Gateway backend shows one supply status for its selected model:
| What you see | What it means |
| - | - |
| **Gateway · Healthy** | The intended first hop is serving. |
| **Gateway · Degraded** | A later hop is serving, or part of the chain is blocked. Requests can still complete. |
| **Gateway · All sources are cooling down** | No hop is runnable yet, but every blocker will retry automatically. |
| **Gateway · No source is available** | The chain is empty or at least one blocker needs action. |
| **Gateway · No model selected** | The backend is in Gateway mode but has no selected model to summarize. |
**Taken over** appears only when a recoverably unavailable first hop has handed the request to a later hop. A successful takeover is silent in the conversation. The Models page shows the current Source, the paused path, and the temporary replacement; the next turn returns to the first hop after it recovers, without changing your saved order.
## Explore usage
Open **Models > Usage** to see calls metered by the Gateway. The trend appears
above the details table.
| Range | Chart |
| - | - |
| **24 hours** | An hourly line chart, including the current partial hour and the preceding 23 hours. |
| **7 days** | A daily line chart. |
| **30 days** or **60 days** | A daily stacked bar chart. |
The page displays the returned range and UTC offsets from the machine running
Avibe. Hourly statistics begin with the version that records them. Older
daily-only usage stays in daily totals; it is not redistributed into hourly
counts. Hours it could belong to are marked incomplete, with the notice
**Includes historical usage without hourly time**. This can cover adjacent
dates when the old record has no time-zone information. Recorded hourly
counts remain visible, but incomplete history is not a complete zero.
Select one or more Sources or models to filter the summary, chart, and table
together. Each Source is a configured account or API-key connection, so two
accounts remain distinct even if they use the same vendor or display name.
Choose all tokens, input, output, cache reads, or request count as the metric.
Group token trends by token
type, model, or Source, or show the total; request counts support total, model,
and Source grouping. Model grouping keeps the same model on different Sources
separate. Legend toggles change chart visibility, not the report filters.
With more than six model or Source series, colors repeat; use their labels,
details, or filters to distinguish them.
Hover over or click a time point to see its exact figures. Clicking elsewhere
closes ordinary details. The pin button in the detail corner explicitly pins
or unpins the time point; pinned details remain visible when you click
elsewhere, and the table shows that interval. Unpinning restores the table's
full filtered range. Escape closes the detail and clears any pin. Changing
the range, filters, metric, or chart grouping also clears the pin. Keyboard
users can focus a time point and press Enter or Space to reach the pin control.
The table shows recorded counts grouped by model or Source. Select the active
metric column header to reverse the sort order. **Export CSV** uses the current
filters and any pinned interval, exporting bucket-level Source/model records
rather than the table's grouped or sorted layout. It includes time bounds
and a history-completeness flag; unavailable token values are left blank.
For unusually long Source IDs, the Source ID column can contain a shortened
internal ledger key instead of the original ID.
Input already includes cached input. Total tokens are input plus output;
token-type series split this into noncached input, cache reads, and output.
The cache share is cached input divided by all input.
Request count measures upstream calls, so one Agent turn can contribute
several requests after fallback. Token counts depend on upstream reports:
missing reports are not zero usage. Calls made outside the Gateway are not
included.
**At API price** is an estimate: the same usage priced at the vendor's
published API prices, not an amount charged. The page shows the date of the
price table it used, and every day is priced at that current table. A figure
marked **≥** is a lower bound: some requests reported no token counts, some
usage has no price, or part of the history is incomplete. Models with no
known price show **No price yet**; they are left out of the total, never
counted as zero, and the left-out token count is shown. To add or correct a
price, see [Correct prices](#correct-prices).
## Check subscription quota
Open **Models > Subscription quota** to see every subscription signed in as a
gateway Source. The page refreshes every five minutes; **Refresh now** reads it
immediately.
Each account shows its limits as the vendor reports them, such as the 5-hour
and weekly limits and any per-model weekly limit, with the share used, when it
resets, and whether the current pace lasts until the reset. If a reading fails,
the page keeps the last one and says how old it is. A subscription that does
not report quota says so.
The page also values each account's metered use at API price, the same
estimate as [Explore usage](#explore-usage):
* **Last 7 days at API price** covers the trailing seven days.
* **This cycle at API price** covers the current billing cycle when the
account has a renewal day set in the price override file. Otherwise the page
shows **Last 30 days at API price**.
* **Paid back** compares that period's value with the plan's monthly fee, as a
multiple of the fee or as the amount still to pay back.
The monthly fee comes from the plan the vendor reports, or from the plan you
set in the price override file. Built-in fees cover Claude Pro, Max 5x, and
Max 20x, and ChatGPT Plus and Pro. When the plan is unknown, such as a Team or
Enterprise seat, the page shows the value but no payback, and the summary
leaves that account out of the payback total.
A value marked **≥** is a lower bound, so its payback is at least the multiple
shown. The page never states a shortfall over usage it could not price. Only
calls through the Gateway are valued; use from other devices or apps on the
same account still counts toward the vendor's limits but not toward the value.
### Correct prices
Prices come from the [models.dev](https://models.dev) catalog that Avibe
already caches for the model picker. To price a model the catalog does not
list, correct a price, or set an account's plan, create
`~/.avibe/state/model_hub_prices.json`. It is read on every page load, so
changes apply the next time the page reads usage; no restart is needed.
Entries in this file take precedence over models.dev.
Every member is optional:
```json theme={null}
{
"models": {
"my-relay-model": {"input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75},
"relay-alias": {"alias": "claude-sonnet-5"}
},
"plans": {"team_seat": {"fee_usd": 30}},
"sources": {"src_abc123": {"plan": "team_seat", "renewal_day": 14}}
}
```
* **`models`** is keyed by model ID. Prices are USD per 1 million tokens.
`input` and `output` are required; `cache_read`, `cache_write` (five-minute
cache), and `cache_write_1h` are optional. A missing `cache_read` or
`cache_write` is priced as input, and a missing `cache_write_1h` as twice
input. Instead of prices, an entry can give `alias` to use another model's
price. Model IDs are matched without a date suffix, a bracketed suffix such
as `[1m]`, or a `provider/` prefix. Keys longer than 128 characters are
ignored.
* **`plans`** sets or adds a monthly fee in USD for a plan key. The built-in
keys are `claude_pro`, `claude_max_5x`, `claude_max_20x`, `chatgpt_plus`, and
`chatgpt_pro`.
* **`sources`** is keyed by Source ID, as shown in the **Source ID** column of
the **Usage** CSV export. Source IDs that Avibe creates look like
`src_abc123`. If that column shows a shortened internal ledger key instead,
the override cannot match it. `plan` sets the account's plan and wins over the
plan the vendor reports. It can be a built-in key, a key you added under
`plans`, or a vendor plan name such as `max 20x`. `renewal_day` (1–31) sets
the day of the month the billing cycle renews; a day past the end of a short
month renews on its last day.
A value that is not a valid number in range, such as a negative, non-numeric,
or extremely large price or fee, is ignored, and the rest of the file still
applies. An invalid `input` or `output` drops that model's entry, so the model
keeps its models.dev price; an invalid optional price is treated as missing.
If the whole file cannot be read, Avibe ignores it and prices from models.dev
alone.
## Understand errors and recover
### Latest recorded turn
The route dialog checks the latest retained, settled turn that Avibe can attribute exactly to this backend and model. If it ended with a terminal error, **Latest recorded turn** shows the recorded time and historical Source/model. **View error details** opens that same record's safe structured details, including the reason and, when available, HTTP status and an observed error code. Raw upstream messages and credentials are excluded.
A later recorded success or cancellation, or no retained record, leaves no old error panel. Failed reads offer **Retry**. This is not a record of every request: OpenCode's shared-process requests remain untracked when they cannot be attributed to an exact turn.
Error codes depend on what the upstream protocol actually returns. An observed `model_not_found` gets a model-not-found explanation; a generic Anthropic `not_found_error` is not rewritten to that code. Without a specific code, the panel uses the recorded reason. Route badges and Source health are separate from these details.
### Messages on the Models page
| Message | What to do |
| - | - |
| **Gateway component not installed · click to install** | Open the confirmation, then install and start the component. No backend changes mode unless you switch it separately. |
| **Gateway not started · click to start** or **Gateway not running** | Start the Gateway, then retry the action. Route origin and draft previews remain available; they do not mean the Gateway is ready to serve requests. |
| **Could not read the source list · the gateway itself is fine** | Select **Retry**. Only the Source list failed; other Gateway state remains valid. |
| **Could not read this backend's supply · the gateway itself is fine** | Select **Retry** for that backend. Do not add a Source merely because this read failed. |
| **Authentication failed: 401 Unauthorized** | Check or replace the API key, then retry. |
| **Wrong address: 404 Not Found** or **Network unreachable: connection timed out** | Correct the Base URL or network path, then retry. |
| **Connected and authenticated — but we cannot tell which interface it speaks** | Choose an interface hint and retry. Nothing is saved until a real response proves the interface. |
| **The interface is identified — but its model list did not come back this time** | Retry, or choose **Add anyway** and maintain the list manually. |
| **Sign-in did not complete. You can retry.** | Retry the vendor sign-in. Closing the dialog cancels the flow Avibe is tracking. |
| **The fetch did not come back. The list below is the last one this page actually read** | Keep working from the retained list or select **Try again**. |
### Messages in a turn
| Situation | What Avibe reports | Recovery |
| - | - | - |
| The Route chain is empty | The requested model has no configured route and points you to Models. | Configure eligible backend defaults, or save a nonempty manual route. An empty override already inherits defaults. |
| Every hop is cooling down | A waiting message with the next recovery time. | Wait. Avibe retries automatically. |
| No hop can run and at least one blocker needs action | An interrupted message with the classified blockers. | Repair the named Source, or edit the Route chain. |
| The request itself is incompatible | **This request is incompatible; switching Sources will not help.** | Change the request, tools, parameters, or model rather than reordering Sources. |
| The upstream reports `model_not_found` | A model-not-found explanation when retained in **Latest recorded turn**. A **Passthrough** badge stays **Passthrough**; the error does not mark the Source unhealthy or trigger fallback. | Check the exact model ID and upstream support, then change the model or its route. |
| The local Gateway stops during a request | A Gateway-down error; if output had started, Avibe also says the output may be incomplete. | Restore the Gateway and retry. Avibe does not replay partial output or blame a Source. |
| A Source fails after output has started | If another hop is now current: **The next turn has switched Sources; retry.** Otherwise Avibe shows the same waiting or interrupted result as an exhausted chain. | Retry as a new turn. Avibe never replays a partially streamed turn. |
| You cancel the turn | The normal canceled-turn message, with no Model Hub supply message. | Start another turn when ready. |
### Recovery by cause
* **Cooldown or takeover:** wait for the displayed retry time. Recovery and the return to the first hop are automatic and do not change the chain.
* **Expired subscription login:** follow **Sign in again** for that Source.
* **Exhausted balance:** top up with the vendor, then open Source details and select **Refetch**.
* **Revoked API key:** replace the key in the existing Source, then refetch. The Source identity and every Route position stay intact.
* **Restricted account:** follow the vendor remedy or move the affected model to another Source.
* **Unclassified Error:** fix the suspected upstream problem, then use **Refetch**. A successful current check clears the blocker.
* **Model rejected by the upstream:** verify the exact model ID and upstream support, then edit the model or route. Absence from an API-key Source's fetched list alone does not mean the model is unusable; subscriptions retain their existing model checks.
* **Source missing:** edit the Route chain. Adding a new Source does not repair a hop that refers to the removed Source.
* **Native CLI unavailable:** restore the backend's local CLI and login, then retry.
* **Need an immediate escape hatch:** switch only the affected backend to **Direct**. Your Sources and Route chains remain saved for when you switch back.
# Model Service
Source: https://docs.avibe.bot/concepts/model-service
Understand the cloud models that power Avibe Voice input, and who chooses them.
Model Service supplies the cloud models used by Avibe product features such as Voice input. These models are separate from the models your Agents use.
Voice input sends audio through avibe.bot for transcription.
See the [network boundary inventory](/concepts/local-first#what-leaves-your-machine) for where Voice content, provider credentials, and usage records go in each mode.
## Personal Avibes
A personal Avibe paired with avibe.bot uses Avibe's shared model pool, with no model or API key to configure. Personal Voice input always uses Model Service; custom Voice input models are not available.
## Enterprise organizations
In an enterprise organization, an organization owner or admin uses bring your own key (BYOK) to configure the models once. Members share that configuration, and usage is charged to the organization's provider account.
## Config Center
Config Center is the administration surface for Model Service on avibe.bot:
* **Organization settings > Model service** lets an organization owner or admin configure Voice recognition, Chat, Embedding, and Multimodal models; verify the configuration; and inspect usage by Avibe. Configuration can be prepared before an organization moves to Enterprise and becomes active after the plan changes.
* **Platform administration > Model service** lets the Avibe platform admin manage the shared pool for personal Avibes, inspect usage, and apply per-Avibe limits. This surface is not available to personal users.
Each capability uses a provider, endpoint address, model, and API key. The organization keeps responsibility for its provider account and charges.
## Model Service and Model Hub
| | Model Service | [Model Hub](/concepts/model-hub) |
| - | - | - |
| Powers | Avibe Voice input | Your Agents |
| Models come from | Avibe's shared pool or your organization | Subscriptions and API keys you add |
| Runs through | avibe.bot | Your machine |
| Configured by | Avibe or an organization admin | You |
Changing Model Hub routes does not change the models used by Voice input. Changing Model Service does not change the models used by your Agents.
# Design Philosophy
Source: https://docs.avibe.bot/concepts/philosophy
What Avibe believes about how humans and AI should work together — and the principles we build by.
Avibe is built on a few strong convictions about how people and AI should work together. This page is the *why* behind the product: the beliefs that decide what we build, and what we refuse to.
## AI is a colleague, not a tool
A tool waits for instructions, does one thing, and stops. A colleague does the task, notices the adjacent problem, asks for judgment when it matters, and comes back when something changes.
The interface should match that. People already collaborate by messaging — interrupting, following up, working in threads — so Avibe puts the agent where that behavior already lives: a browser Workbench and the chat apps you use, not a 1975 terminal and not yet another dashboard. → [Vision](/concepts/vision)
## Your machine is the home, not a tab in someone's cloud
Most AI products want to *be* the whole stack: their app, their cloud, their subscription, your code uploaded to their box. Avibe inverts that. One command turns your own machine into the place the Agent lives; your code, local state, and the Agent's execution stay there.
Local-first is an architectural stance, not a setting. Remote Web UI uses avibe.bot for identity and a secure tunnel back to your machine. Model-backed features have explicit provider boundaries instead of hidden ones. → [Complete boundary inventory](/concepts/local-first#what-leaves-your-machine)
## Own the agent, never get locked in
Avibe drives the *official* Claude Code, Codex, and OpenCode — the agents you already trust — over their real CLIs, not a cut-down embedded copy. You bring your own subscription or keys and switch per task.
There is no middleman: no second reasoning loop sitting between you and your agent, burning tokens on its own persona before your work even starts. The agent you chose is the agent that runs. As those agents get better, Avibe gets better with them — and an Avibe-native agent is on the roadmap *alongside* the ones you bring, never instead of them.
## An operating system, not a wrapper
A wrapper bolts a chat box onto an agent. An operating system gives agents a place to live and a way to act.
Avibe gives every agent one unified world model — agents, sessions, Show Pages, and the Harness — so an agent can schedule itself, build its own loops, run on its own timeline, and reach you through a real interaction layer. That is the difference between a gateway and a home. → [What is Avibe](/concepts/agent-os)
## Constraints are features
A chat message is short. A thread holds context. Media is simple. These limits are not compromises — they push the agent to communicate concisely and in context, the way a good colleague does. [Show Pages](/concepts/show-pages) follow the same discipline: when a paragraph won't do, the agent hands you a page built for the task instead of a wall of text.
## Tension-driven agency
The longer-term direction is an agent that lives on its own timeline. It senses the gap between how things are and how they should be, then acts through explicit, auditable tools.
Every perception is an event in an **Inbox → Processing → Outbox** loop: a message, a CI result, a file change, a schedule firing. A user's message is one signal in that stream — not the only thing that wakes the agent up. The [Harness](/concepts/harness) is where this lives today: run, schedule, watch, inspect.
## The colleague test
We measure progress against one question: does it feel like a colleague? Proactive, context-aware, living on its own timeline — picking up where you left off, asking the right question when it's unsure, going quiet when you're heads-down, and leaving a note about what it touched.
That is the bar. Everything in Avibe is built to move it closer.
# Remote Web UI
Source: https://docs.avibe.bot/concepts/remote-ui
Use vibe remote to open your local Avibe Web UI from another device.
# Remote Web UI
Your Avibe runs on your machine. You don't sit in front of it 24/7.
You're on a plane. At a café. Holding someone else's borrowed laptop. The bot just pinged you that a job needs attention — and the control panel is back home.
```bash theme={null}
vibe remote
```
One command. Your local Web UI becomes reachable from any browser on Earth — through a secure avibe.bot tunnel.
* 🌍 **Your own `you-app.avibe.bot`** — 30-second sign-in, your slug for life
* 🔒 **Fail-closed at every join** — auth, routing, host checks default to "deny"
* 📱 **Mobile-aware UI** — thumb-friendly layout, designed for borrowed screens
* ⏱ **24-hour sessions** — cookie auto-renews mid-session, no sudden logouts
No VPN. No port forwarding. No "wait what's my IP again." No public webhooks pointed at your laptop. **The Remote Web UI data plane stays on your machine**; avibe.bot handles the control-plane handshake.
## What it does
`vibe remote` guides you through:
* avibe.bot sign-in.
* Pairing your local Avibe instance.
* Creating a secure tunnel to your local Web UI.
* Opening the Web UI from another device.
## What it does not do
It does not move your coding agent into the cloud.
Your codebase, agent process, credentials, and working directory stay on your local machine. The remote URL is for Web UI access.
## The trust model
For Remote Web UI, avibe.bot is the **control plane**, not the data plane — the front door, not the house. It proves it is you and opens a tunnel; browser traffic returns to your local Web UI without passing through the avibe.bot application.
This Remote Web UI boundary does not cover model-backed features. See the [complete boundary inventory](/concepts/local-first#what-leaves-your-machine) for Voice input, Agent providers, and their available modes.
```text theme={null}
your phone ──> avibe.bot (identity only) ──────────> sign-in
your phone ──> Cloudflare tunnel ──> your machine's Web UI (your data)
```
* **Identity via OIDC + RS256.** Sign-in uses standard OpenID Connect (PKCE) with RS256-signed tokens. avibe.bot publishes a JWKS, so your *local* Avibe verifies a session's signature on its own — it doesn't have to phone home on every request.
* **Cloudflare Tunnel, run locally.** `cloudflared` runs on your machine and dials out. Browser traffic reaches your Web UI through that tunnel; it does not proxy through avibe.bot's servers, and no inbound ports are opened on your machine.
* **Fail-closed at every join.** Auth, routing, and host checks all default to deny. A misconfiguration locks you out — it doesn't quietly expose your machine.
→ The same stance, end to end: [Local-first](/concepts/local-first) · [Design Philosophy](/concepts/philosophy)
## Who can sign in
Remote access is a private workspace, not a team gateway. Only the email addresses you authorize can sign in to your public URL — bind the ones you trust, and nobody else gets in, even with the link. No team seats, no role matrix: just you and the people you explicitly invite.
## When to use it
Use `vibe remote` when:
* You want to configure Avibe from your phone.
* Avibe is running on a remote development box.
* You need to check the dashboard away from the machine running the agent.
For normal chat-based control, you can keep using Slack, Discord, Telegram, WeChat, or Lark directly.
## Pairing and the tunnel
Pairing happens once per instance:
1. Sign in at avibe.bot and create a remote-access bot.
2. Copy the one-time pairing key (`vrp_…`).
3. Paste it into `vibe remote`, or pass it directly: `vibe remote pair `.
After pairing, manage the tunnel with `vibe remote status`, `vibe remote start`,
and `vibe remote stop`. The tunnel itself is run locally by `cloudflared`; the
public URL only proxies traffic into your local Web UI.
## Sign-in sessions
The public URL is protected by an avibe.bot sign-in. After you sign in on a
device:
* The session lasts about 24 hours.
* Activity past the half-life slides the session forward, so an active browser
rarely needs to sign in again.
* Sign out from a device with the dashboard's sign-out action; the tunnel
itself keeps running for other devices and for future sign-ins.
If a device reports the session as expired, sign in again at the public URL.
## Stopping remote access
`vibe remote stop` shuts down the cloudflared tunnel but keeps the pairing
config so you can resume later with `vibe remote start`. Running `vibe remote`
again with a new pairing key replaces the configuration.
# Show Pages
Source: https://docs.avibe.bot/concepts/show-pages
Let your agent hand you a live web page — a dashboard, diagram, diff, or report — not just text.
Text is a narrow channel. **Show Pages** let your agent *show* you something: a dashboard, a diagram, a diff, a report, or a small interactive app — a real web page, generated for the task at hand and reachable from your phone.
## How it works
* Each Agent Session gets one canonical Show Page.
* The agent writes a small web app (React/Vite) into a local, session-scoped directory on your machine.
* Avibe serves it through a managed runtime and gives you a URL — reachable from anywhere through the same [`vibe remote`](/concepts/remote-ui) tunnel.
* The page hot-reloads as the agent edits it, so what you're looking at stays current.
* You control visibility: keep it **private**, **publish** a shareable link when you want one — and give that public link a custom, memorable suffix (e.g. `/p/q3-roadmap/`) instead of a random one — or take it **offline**.
## What the agent can build
A Show Page is a real front-end, so the agent reaches for the right tool for the job:
* Diagrams and flowcharts (Mermaid), mind maps (Markmap), node graphs (React Flow).
* Charts and metric dashboards.
* Side-by-side comparisons, diffs, and decision tables.
* Small interactive explainers and clickable prototypes.
## When it helps
* A plan, architecture, or migration that lands better as a diagram than a wall of text.
* A metrics dashboard or comparison you want to inspect, not scroll past.
* A review or report you'd rather click through than read top to bottom.
## Pin it to the Dock
A Show Page is really an app your agent built for you — so you can keep it around like one. In the [Workbench](/concepts/workbench), open the same controls where you set visibility and flip **Pin to Dock**: the page joins your [apps](/concepts/apps-dock), gets its own tile, and opens in a window you can move, resize, and leave running beside your chat. Pinning is independent of visibility — a private page can still be pinned — and it never publishes or deletes anything.
From there it behaves like any other app: reorder or undock it, open it with ⌘K or a keyboard shortcut, give it an icon, and reach it from your phone. See [Apps & the Dock](/concepts/apps-dock) for the full story.
## Point at what you see
A Show Page isn't one-way. Turn on **annotation** and you can click an element, box a region, or mark up a screenshot right on the page, add a word, and send it to your agent — which can answer *on the page*, pinned next to what you pointed at. See [Annotating Show Pages](/concepts/annotating-show-pages) for the full loop, including public-link permissions.
## You can just ask
You don't invoke Show Pages by hand. Ask for the outcome — "draw me the request flow", "put the options in a comparison table", "show the migration as a checklist" — and the agent decides a page beats a paragraph, builds it, and sends you the link. It's the same instinct behind [constraints are features](/concepts/philosophy): when text won't do, show it.
The page lives on your machine; avibe.bot only carries the tunnel.
# Skills
Source: https://docs.avibe.bot/concepts/skills
Give your agents reusable skills, managed in one place across Claude Code, Codex, and OpenCode.
**Skills** are reusable capabilities you give your agents — packaged instructions and helpers an agent loads on demand. A skill can teach an agent your conventions, wrap a tool, or encode a workflow you repeat. Avibe manages them in one place, across every backend, so you set them up once instead of re-explaining your work every session.
## What a skill is
A skill is a small bundle — a `SKILL.md` of instructions plus any commands or helpers it needs — that an agent pulls in when a task calls for it. Skills range from "follow our PR workflow" to "use this CLI to query Sentry" to "search large files with ripgrep." The agent loads a skill only when it's relevant, so the working context stays lean.
## One library, every agent
* Manage **global** skills (available in every project) and **per-project** skills from the [Workbench](/concepts/workbench).
* The same skills layer works across Claude Code, Codex, and OpenCode — you don't redo setup per agent. A skill can target one backend or all of them.
* Browse a registry and install a skill with a click, or add your own from a Git source.
* Avibe manages skills through the open **`askill`** toolchain, installed as a managed dependency so it's ready when you need it.
## Global vs per-project
* **Global** skills are your standing toolkit — conventions and helpers you want everywhere.
* **Per-project** skills live with a repo: its build steps, its test commands, its house style — so an agent picks them up only in that project.
Both kinds are visible side by side in the Workbench, with their source and version, and they apply no matter which backend runs the task.
## A quick example
Say every repo at your shop follows the same review flow. Capture it once as a skill — "branch, commit with a conventional message, open a non-draft PR, wait for review, fix, merge" — and every agent you run can follow it without you spelling it out again. Add a second skill that wraps your deploy CLI, and "ship it" starts meaning the same thing to all three backends.
## Why it matters
Skills are how an agent gets better at *your* work over time — your conventions, your workflows, your repeated tasks — without you re-explaining them every session. Set them up once; every agent you run inherits them. As the library grows, so does the leverage of every new session.
→ Manage them in the [Workbench](/concepts/workbench) · part of the [Agent OS](/concepts/agent-os) world model.
# Thread sessions
Source: https://docs.avibe.bot/concepts/thread-sessions
Use chat threads as isolated, resumable agent sessions.
# Thread sessions
In Avibe, a chat scope can map to an agent session.
The practical rule:
```text theme={null}
Thread = session
```
Start five threads, run five independent jobs, and keep their context separate.
## Why it works
Chat threads are a natural unit of work:
* One production incident.
* One feature branch.
* One refactor.
* One investigation.
* One follow-up review.
The agent does not need a custom dashboard to understand the conversation boundary. The chat app already gives it one.
## Resume from anywhere
A session outlives the moment. Start a thread on your desktop, reply from your phone hours later, and the agent picks up with the same context — the thread *is* the memory. The [Workbench](/concepts/workbench) Inbox shows the same sessions you reach from chat.
## Routing and switching
Sessions compose with agent routing. Point different channels or projects at different agents — `#frontend` to OpenCode, `#backend` to Claude Code — and each thread runs the agent you mapped. You can also switch the agent mid-thread by prefixing a message with its name, without losing the session's context. Configure routing from the [Workbench](/concepts/workbench).
## Best practices
* Start a new thread for a new task.
* Reply in the same thread to continue the same task.
* Use short, explicit acceptance criteria.
* Stop or archive sessions that are no longer useful.
## Example
Top-level message:
```text theme={null}
Fix the login redirect bug. Reproduce it first, then patch the smallest root cause and run the relevant tests.
```
Thread reply:
```text theme={null}
Good. Also check whether the same redirect path affects signup.
```
# Vaults
Source: https://docs.avibe.bot/concepts/vaults
Give Agents controlled access to secrets while keeping secret values out of Avibe's own Vault responses.
**Vaults** let an Agent use a credential without Avibe exposing its value through Vault responses. Agents refer to secrets by name, tag, or Skill tag; Avibe handles storage, policy, approval, and delivery at the boundary where the credential is actually needed.
## The core rule
Avibe's Vault APIs return names, value-free metadata, approval states, or public signatures — not secret values. This keeps the value out of chat and model context as long as the command receiving it does not print or otherwise disclose it.
`vibe vault run` cannot sanitize a child process's stdout or stderr. If that process prints its environment or includes a credential in diagnostic output, the output can return to the Agent and enter model context. Only run commands you trust not to expose secret-bearing output.
For a static secret, Avibe can inject the value into a child process or attach it to an authenticated HTTP request. For a signing key, the private key stays in custody and only a public signature comes back.
## Standard and Protected preview
| Protection | Status | What happens on use |
| - | - | - |
| **Standard** | Shipped | The Agent can use the secret according to its policy; an entry can still be configured to ask first. |
| **Protected** | Pre-launch preview | The intended flow asks you to approve the exact operation and unlock it with your passkey. Do not store real credentials in it yet. |
Protected Vaults are designed for end-to-end encrypted custody, but the current build does not yet enforce the immutable sandbox integrity gate required for real users. The UI demonstrates the passkey flow; Protected must not hold production credentials, wallets, or other real secrets until that gate is enabled.
## Static secrets and keypairs
* **Static secret** — an API key, token, password, or connection string. Use it with `vibe vault run` for process-local environment injection or `vibe vault fetch` for authenticated HTTP egress.
* **Keypair** — a deployment signing key. Its private key is not exportable and cannot be used with `run` or `fetch`; use `vibe vault sign` to sign a 32-byte digest. Protected keypair custody has the same pre-launch restriction above.
## When an Agent needs a missing secret
1. The Agent creates a request with the secret name, reason, and non-secret metadata.
2. The request appears in **Vaults** in the Workbench.
3. You review the request, choose Standard, and enter the value in the browser. Protected is preview-only in the current build.
4. Avibe resumes the requesting Agent Session after the secret is ready.
This keeps the credential value out of the request and setup conversation even when the Agent is the one that discovers the requirement.
## Common commands
```bash theme={null}
vibe vault list
vibe vault request OPENAI_API_KEY --reason "Need OpenAI API access"
vibe vault run --env OPENAI_API_KEY -- python sync.py
vibe vault fetch --auth GITHUB_PAT --url https://api.github.com/user
vibe vault sign WALLET_KEY --digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```
Use `vibe vault find` and `vibe vault tags` when the Agent should select by metadata instead of an exact name.
See [Commands](/reference/commands) for the CLI map.
# Vision
Source: https://docs.avibe.bot/concepts/vision
Why Avibe puts AI agents in the communication channels humans already use.
# AI as colleague, not tool
Most AI tools still behave like terminals: you type a command, the model does work, it returns a result, and it stops.
Avibe starts from a different belief: the best human-AI interface should look more like collaboration with a colleague. For the full set of convictions behind the product, see [Design Philosophy](/concepts/philosophy).
## Why chat
Humans collaborate by talking, interrupting, noticing, following up, and working in threads. The group chat, DM, and channel are already where this behavior lives.
Putting AI into chat forces the machine to adapt to human communication patterns instead of forcing humans to live inside another dashboard.
## The colleague test
A tool waits for instructions.
A colleague does the task, notices adjacent problems, asks for judgment when needed, and comes back when something important changes.
Avibe is useful today because it puts real agents into the same chat threads where human work already happens. Coding is the first strong workload, but not the product boundary. The longer-term direction is tension-driven agency: an AI colleague that senses gaps between how things are and how they should be, then acts through explicit, auditable tools.
## The architecture
* Inbox: user messages, code changes, CI results, system events.
* Processing: sensing tensions, reasoning, prioritizing, planning.
* Outbox: auditable actions such as sending a message, modifying a file, or notifying a human.
The chat message is one signal in the stream, not the whole interface.
## Where it's heading
The [Harness](/concepts/harness) is the first shipped piece of that timeline. From here the arc runs toward an agent that increasingly acts on its own initiative — and an Avibe-native agent tuned for this runtime, alongside the official CLIs you bring. The bar stays the same: it should feel less like a tool you operate and more like a colleague you work with.
# The Workbench
Source: https://docs.avibe.bot/concepts/workbench
Operate Avibe from your browser: chat with your agent and manage sessions, Apps, the Harness, Vaults, and Skills.
The **Workbench** is Avibe's browser app — a first-class way to operate your machine's agent, right alongside chat.
Open it locally with `vibe`, or reach it from anywhere with [`vibe remote`](/concepts/remote-ui).
## What you can do
* **Chat with your agent** directly in the browser — the same sessions you'd reach from Slack or Discord.
* **Talk instead of type** — built-in voice-to-text lets you brief the agent by speaking. On desktop, press **Option+Z** on macOS or **Alt+Z** on Windows and Linux to start, press it again to finish, or press **Esc** to cancel. Change the shortcut for the current browser under **Settings > Shortcuts**.
* **Open Show Pages** — when the agent builds a [Show Page](/concepts/show-pages), you view it right here.
* **Run apps from the Dock** — the Show Pages your agent builds install as [apps](/concepts/apps-dock): keep the ones you use in the Dock, open them in windows, and manage them in the App Library.
* **Answer interactive prompts** — when the agent needs a decision, it pops buttons or a short form instead of making you type it out.
* **Inbox** — a live timeline of every turn, including the self-initiated turns your [Harness](/concepts/harness) tasks and watches produce.
* **Agents** — configure your backends (Claude Code, Codex, OpenCode), models, and per-project routing.
* **Vaults** — provide and approve [secrets](/concepts/vaults) without exposing their values through Vault responses.
* **Skills** — manage [Skills](/concepts/skills) for your agents.
* **Projects and sessions** — start, resume, and organize work across projects.
## Organize projects
Projects keep a fixed order across desktop and mobile. Initially they follow
creation order, with new projects added at the end. Chat activity and renaming
do not move them.
Drag a project header to change its position. On a phone, hold the header briefly
before dragging; a normal swipe still scrolls. Projects animate into place and
the order is saved on your Avibe instance, so it follows you across devices.
Click or tap the header to expand its sessions. For keyboard access, focus the
header, press **Space**, move with the arrow keys, and press **Space** to drop or
**Esc** to cancel. Reordering requires permission to manage projects.
Sessions within each project keep their own order: pinned sessions first,
then most recently active sessions.
## Install it as an app
The Workbench is a PWA. Add it to your desktop or phone home screen and it behaves like a native app — its own window, and a push notification the moment a job needs you. You leave the agent running on your machine and carry the control surface in your pocket.
## Browser and chat are both first-class
Avibe is not "a chat bot with a settings page." The Workbench and your chat apps are two equal ways to talk to the same local Agent: open the browser when you want a richer view, use chat when you're on the move. Your Agent, code, and local state stay on your machine. See the [Local-first boundary inventory](/concepts/local-first#what-leaves-your-machine) for the network paths available from either surface.
# Install Avibe
Source: https://docs.avibe.bot/get-started/install
Install Avibe on macOS, Linux, or Windows with WSL.
# Install Avibe
Avibe runs locally on the machine where your data and coding agents live.
## macOS and Linux
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash
```
Open source — [view the script on GitHub](https://github.com/avibe-bot/avibe/blob/master/install.sh) or [audit it before running](#audit-before-running). The short URL is a 307 redirect to that file.
Verify the install:
```bash theme={null}
vibe version
vibe doctor
```
Start the service and setup wizard:
```bash theme={null}
vibe
```
## Windows
The recommended Windows path is WSL:
* Use Windows for your browser and chat apps.
* Use Ubuntu in WSL for Avibe, agent CLIs, and your code repository.
From Ubuntu in WSL:
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash
vibe
```
Native PowerShell installation is available, but WSL is usually smoother for Python, Node, Git, and coding agent CLIs:
```powershell theme={null}
irm https://raw.githubusercontent.com/avibe-bot/avibe/master/install.ps1 | iex
```
## Audit before running
Prefer to read the script before piping it to `bash`? Fetch it locally first, inspect it, then run it:
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh -o install.sh
cat install.sh # or: less install.sh
bash install.sh
```
`https://avibe.bot/install.sh` is a 307 redirect to the same file on GitHub raw, so both URLs serve identical content.
## What the installer does
The installer:
* Installs the `vibe` CLI.
* Uses PyPI first and falls back to GitHub when needed.
* Prints PATH guidance if the command is installed but not visible in the current shell.
* Leaves your chat platform credentials and agent credentials for the setup wizard.
## Upgrade
Re-run the installer:
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash
```
## Uninstall
Run the installer with `--uninstall`. It stops Avibe, then removes every `vibe` command and install file it put on this machine. A `vibe` it did not install is left alone. Your settings, sessions, and other data in `~/.avibe` (and the legacy `~/.vibe_remote`) are kept:
```bash theme={null}
bash -o pipefail -c 'curl -fsSL https://avibe.bot/install.sh | bash -s -- --uninstall'
```
To delete your data too, add `--purge`. It lists everything it will delete and asks before deleting. **Deleted data cannot be recovered.** Where no terminal can answer, it also needs `--yes`.
```bash theme={null}
bash -o pipefail -c 'curl -fsSL https://avibe.bot/install.sh | bash -s -- --uninstall --purge'
```
For a native PowerShell install, run the Windows installer with `-Uninstall`. Add `-Purge` to delete your data too, and `-Yes` where the session cannot prompt for confirmation:
```powershell theme={null}
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/avibe-bot/avibe/master/install.ps1))) -Uninstall
```
The uninstaller never deletes through a link. Anything behind a link is reported for you to remove yourself.
# Setup wizard
Source: https://docs.avibe.bot/get-started/setup-wizard
Use the local Web UI to configure the always-on workbench, optional chat platforms, agent backends, and project routing.
# Setup wizard
Run:
```bash theme={null}
vibe
```
Avibe starts a local Web UI and opens the setup wizard.
## What you configure
The wizard walks through:
* The Avibe Workbench — an always-on local web chat surface (nothing to set up).
* Optional chat platforms — Slack, Discord, Telegram, WeChat, or Lark / Feishu.
* Agent backends and their model providers.
* Agent CLI paths and the default working directory.
* Channels or chats where Avibe should respond.
* Health checks for the selected setup.
Finishing — or skipping — the wizard marks setup complete, so you are not sent back to it on the next launch. You can change anything later in Settings.
## The Avibe Workbench is always available
You do not need a third-party chat app to use Avibe. The **Avibe Workbench** is a built-in web chat that lives in the local Web UI and is always enabled — it is the one surface you cannot turn off. Connecting Slack, Discord, and the others is optional and additive.
On a phone, open the Workbench URL and use your browser's **Add to Home Screen** to install it as an app.
Workbench-only is a complete setup. You can finish the wizard with no chat platform connected and add platforms later when you want them.
## Chat platforms (optional)
Connect the chat app where you already work. Each platform you enable gets its own credential step in the wizard; you can also skip them all and add platforms later in Settings.
| Platform | Best for |
| - | - |
| Slack | Team workflows, threads, Socket Mode, mature interactivity |
| Discord | Community and personal servers |
| Telegram | Lightweight personal and group bots |
| WeChat | Mobile-first China workflows |
| Lark / Feishu | China/Asia workspaces and enterprise chat |
## Agent backends
Enable one or more backends. The wizard auto-detects installed CLIs, offers a one-click install for any that are missing, and gives each backend a **Configure model provider** button — the same provider settings you will find later under Settings, so there is nothing to redo.
| Backend | Best for |
| - | - |
| Claude Code | Deep reasoning and complex codebase work |
| OpenCode | Fast local setup and extensibility |
| Codex | OpenAI coding workflows |
You can enable multiple backends and route different channels to different agents.
## Prefer the wizard over manual config
Avibe stores persistent config under your local user directory. You can inspect config files when debugging, but first-time setup should go through the wizard because it validates credentials and platform state.
# Avibe Docs
Source: https://docs.avibe.bot/index
Avibe is the local-first Agent OS: your AI partner lives on your own machine, reachable from your browser or any chat app.
# Your AI partner lives on your own machine
Avibe is the local-first Agent OS. One command turns your machine into a home for your AI partner — driving the official Claude Code, Codex, and OpenCode you already use — and you reach it from your browser or any chat app while your code and Agent runtime stay at home.
## What Avibe is
Avibe is not an agent framework, not a hosted coding VM, and not a middleman that sits between you and your agent.
It is the operating layer your agent lives in:
* **Local-first, and yours.** Your AI partner, its execution, and its local state stay on your own machine. The [boundary inventory](/concepts/local-first#what-leaves-your-machine) shows every network path available in each mode.
* **One substrate, every first-party agent.** Drive the official Claude Code, Codex, and OpenCode through a single Harness — bring your own subscription or keys, switch per task, never locked into one vendor's silo.
* **Operate it from anywhere.** A browser Workbench — installable as a desktop or mobile app, with push notifications — plus Slack, Discord, Telegram, WeChat, and Lark are all first-class ways to talk to it.
* **It keeps its own timeline.** The Agent Harness lets your partner schedule work, wait for conditions, run jobs in the background, and come back with results.
* **Vault responses never reveal secret values.** [Vaults](/concepts/vaults) let Agents request and use Standard credentials by name, with explicit safeguards for command output. The Protected passkey flow is a pre-launch preview.
* **It can show, not just tell.** Show Pages let the agent hand you a live page — a dashboard, a diagram, a report — reachable from your phone.
Coding is the first strong workload, not the product boundary.
> Avibe is built with Avibe — developed end-to-end on its own runtime, steered from the browser and the phone, at the desk or away from it.
## The Agent Harness
Avibe gives agents a few durable primitives: run one job, schedule a time
trigger, watch a condition, and inspect run history. In practice, you can ask
in plain language:
* "Watch this PR and come back when there is actionable review feedback."
* "Check deployment health every weekday morning and post the summary here."
* "Start a separate investigation session for this incident and report back to this channel."
The agent composes the commands behind the scenes. You do not need to memorize
every flag to get useful automation.
## Meet Vibey
Lives in your Slack, Discord, Telegram, Lark, or WeChat. Reads the room. Picks up where you left off. Asks the right question when it's not sure. Goes quiet when you're heads-down. Ships at 2am because that's when the vibe hits — then leaves a note about what it touched.
> Avibe is the home. Vibey is the colleague who lives in it.
Forgets nothing. Holds opinions. Says thanks when you fix its bugs.
## Install in one command
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash && vibe
```
Open source — view the [script on GitHub](https://github.com/avibe-bot/avibe/blob/master/install.sh). The short URL is a 307 redirect to that file.
Then follow the browser setup wizard.
## Common paths
* New to Avibe: start with [Quickstart](/quickstart).
* Want the model first: read [What is Avibe](/concepts/agent-os).
* AI assistant helping a user install: use [Install for AI agents](/ai/install-for-ai).
* Choosing a chat platform: start with [Slack](/platforms/slack), [Discord](/platforms/discord), or [Telegram](/platforms/telegram).
* Reach your Avibe from your phone or a remote server: read [Remote UI](/concepts/remote-ui).
## Source
Avibe is open source:
* GitHub: [avibe-bot/avibe](https://github.com/avibe-bot/avibe)
* Product: [avibe.bot](https://avibe.bot)
# Discord
Source: https://docs.avibe.bot/platforms/discord
Connect Discord channels to Claude Code, OpenCode, or Codex through Avibe.
# Discord
Discord works well for personal servers, community servers, and lightweight mobile workflows.
## What you get
* Talk to a local coding agent from any Discord channel.
* Keep conversations separate — Avibe opens a new thread per task to mirror Slack-style sessions.
* Route selected channels to selected agent backends.
* Receive streamed progress and completion updates.
## Set up the bot
1. Open the [Discord Developer Portal](https://discord.com/developers/applications) → **New Application** and name it.
2. Go to **Bot → Add Bot** and copy the **Bot token**.
3. Under **Bot → Privileged Gateway Intents**, enable **Message Content Intent** (required). Server Members Intent is optional.
4. Under **OAuth2 → URL Generator**, select the **bot** scope and these permissions: View Channels, Send Messages, Create Public Threads, Send Messages in Threads, Add Reactions, Attach Files. Open the generated URL and invite the bot to your server.
5. In the Avibe wizard, choose **Discord**, paste the bot token, **Validate**, pick your server, and enable channels.
> The most common Discord miss is leaving **Message Content Intent** off — the bot connects but never sees message text. For DMs, Discord has no threads, but sessions are still isolated per message.
## Smoke test
Send a short message in an enabled Discord channel:
```text theme={null}
Say hello and tell me what backend you are using.
```
Then run locally:
```bash theme={null}
vibe status
```
## Outbound proxy
When the host running Avibe cannot reach Discord directly, set `proxy_url` on the Discord config block from the Web UI. Both HTTP/HTTPS proxies and SOCKS proxies are supported (any `socks*://` scheme — `socks4`, `socks4a`, `socks5`, or `socks5h`). Saving the config block only persists the change; run `vibe restart --delay-seconds 60` afterwards so the new transport applies to live connections.
## Common issues
| Symptom | Check |
| - | - |
| Bot silent | Bot token, server install, channel selection |
| Bot connects but ignores messages | **Message Content Intent** is enabled in the Developer Portal |
| Messages arrive but no response | Agent backend enabled and CLI path valid |
| Wrong project | Channel routing and default working directory |
| Discord unreachable from host | `proxy_url` on Discord config; check firewall and TLS errors in logs |
# Slack
Source: https://docs.avibe.bot/platforms/slack
Use Slack as a collaboration surface for the agents your Avibe runs locally.
# Slack
Slack is the most polished Avibe surface today — it supports threads, Socket Mode, buttons, modals, and rich interaction patterns.
## What you get
* Mention the bot to start a task.
* Continue work in a thread — each thread is an isolated, resumable session.
* Approve interactive prompts (buttons, modals) without opening a terminal.
* Receive completion notifications.
## Set up the app
The wizard does the heavy lifting. In the Avibe setup wizard, choose **Slack** and:
1. Click **Create Slack App** — Slack opens with a manifest pre-filled (name, scopes, events, and Socket Mode all set).
2. Pick your workspace, click **Create**, and install the app to the workspace.
3. Follow the accordion to copy the **Bot token** (`xoxb-…`) and the **App-level token** (`xapp-…`).
4. Click **Validate Tokens**, then finish and start the service.
What the app needs (for manual setup)
If you'd rather build the app by hand at [api.slack.com/apps](https://api.slack.com/apps):
* **Socket Mode: enabled** — Avibe connects out over Socket Mode, so there are no public inbound webhooks.
* An **app-level token** (`xapp-…`) with the **`connections:write`** scope.
* A **bot token** (`xoxb-…`) with the message, mention, file, and reaction scopes: `app_mentions:read`, `channels:history` / `channels:read`, `groups:history` / `groups:read`, `im:history` / `im:read` / `im:write`, `mpim:history` / `mpim:read` / `mpim:write`, `chat:write`, `users:read`, `commands`, `files:read` / `files:write`, `reactions:read` / `reactions:write`.
* **Event subscriptions** for `app_mention`, the `message.*` events, and `reaction_added` / `reaction_removed`; **Interactivity** enabled.
The **Create Slack App** button pre-fills all of this as a manifest, so manual setup is only for the curious.
## Use it in Slack
* Invite the bot to a channel: `/invite @Avibe`.
* **Mention the bot** to start; **reply in the thread** to continue the same session.
* To use it in a **DM**, send `bind ` with the bind code shown in the Web UI.
* Route to a specific agent by prefixing your message: `AgentName: do the thing`.
## Smoke test
After the wizard reports a healthy Slack connection, mention the bot in an enabled channel:
```text theme={null}
@Avibe say hello and tell me which project directory you are running in
```
Reply in a thread to continue the same agent session.
## Outbound proxy
When the host running Avibe cannot reach Slack directly, set `proxy_url` on the Slack config block from the Web UI. Both HTTP/HTTPS proxies and SOCKS proxies are supported (any `socks*://` scheme — `socks4`, `socks4a`, `socks5`, or `socks5h`). Saving the config block only persists the change; run `vibe restart --delay-seconds 60` afterwards so the new transport applies to live connections.
## Common issues
| Symptom | Check |
| - | - |
| Bot does not answer | Bot is invited to the channel and the channel is enabled |
| Socket Mode fails | App-level token has the `connections:write` scope, and Socket Mode is enabled |
| Events arrive but no agent starts | Selected backend CLI exists on PATH |
| Thread loses context | Reply inside the same thread, not as a new top-level message |
| Slack unreachable from host | `proxy_url` on Slack config; check firewall and TLS errors in logs |
# Telegram
Source: https://docs.avibe.bot/platforms/telegram
Use Telegram chats and groups as mobile collaboration spaces for local AI agents.
# Telegram
Telegram is a lightweight way to delegate work to local AI agents from your phone, a group, or a forum topic.
## What you get
* Send tasks to a local AI agent from a DM, group, or forum.
* Keep work local while you control it from anywhere.
## Set up the bot
1. In Telegram, open [@BotFather](https://t.me/BotFather), send `/newbot`, and choose a display name plus a username ending in `bot`. Copy the token.
2. In the Avibe wizard, choose **Telegram**, paste the token, and **Validate**. (If your region blocks Telegram, set a proxy URL in the same step before validating — see below.)
3. Back in **@BotFather**, set the switches that decide how the bot behaves in groups:
* **`/setprivacy` → Disable** — so the bot sees normal group messages, not only mentions. *This is the #1 setup miss.*
* **`/setjoingroups` → Enable** — if you'll use it in groups or forums.
* **`/setcommands`** — publish `start`, `settings`, `new`, `resume`.
## Bind, then discover chats
Telegram has no "list every chat" API, so Avibe discovers chats from inbound messages. On first run, in order:
1. Finish setup and start the service.
2. Copy the bind command from the final summary screen.
3. DM the bot `bind ` to become the first admin, then send `/start` to confirm.
4. To use a group or forum, add the bot there, send one message, then **refresh the Telegram chat list** in group settings and enable it. Forum auto-topics need admin / topic-management rights.
## Group defaults
The wizard exposes two Telegram defaults: **require explicit targeting in groups** (respond only to commands, mentions, or replies — good for busy groups) and **forum auto-topic mode** (a top-level message opens a new topic; needs admin / topic rights).
## Smoke test
```text theme={null}
Say hello and tell me which project directory you can see.
```
If the bot does not answer, run:
```bash theme={null}
vibe doctor
```
## Outbound proxy
If Telegram is blocked in your region, set `proxy_url` — easiest in the wizard's Proxy field before validating, or on the Telegram config block in the Web UI. HTTP/HTTPS and any `socks*://` scheme (`socks4`, `socks4a`, `socks5`, `socks5h`) are supported. Saving only persists the change; run `vibe restart --delay-seconds 60` to apply it. Note: Avibe does **not** fall back to a direct connection if the proxy is down — fix or remove `proxy_url` to recover.
## Common issues
| Symptom | Check |
| - | - |
| Group messages ignored | `/setprivacy` is set to **Disable** |
| Bot works in DM but not groups | `/setjoingroups` is **Enable** |
| Chat not listed | Send a message there first, then refresh discovered chats |
| Agent missing | Selected backend CLI is installed and visible on PATH |
| Telegram unreachable from host | `proxy_url` on Telegram config; check firewall and TLS errors in logs |
# WeChat and Lark
Source: https://docs.avibe.bot/platforms/wechat-lark
Use WeChat or Lark / Feishu for mobile-first and Asia-focused Avibe workflows.
# WeChat and Lark
Avibe also supports WeChat and Lark / Feishu, so the agent can live where your real work conversations already happen. Both connect out like the other platforms — no public inbound port for normal chat control — and the in-app setup wizard walks you through the platform-specific credentials.
## WeChat
WeChat suits mobile-first personal workflows and China-native daily communication.
In the setup wizard, choose **WeChat** and follow the platform-specific prompts to connect your account, then select the chat where Avibe should respond. After it reports healthy, send a short smoke-test message in that chat.
## Lark / Feishu
Lark / Feishu suits teams already living in enterprise chat, approvals, and that collaboration ecosystem.
In the setup wizard, choose **Lark / Feishu**, configure the app credentials it asks for, and select the chats or channels where Avibe should respond. Lark connects over its WebSocket transport, so there are no inbound webhooks to expose.
> Setup specifics for WeChat and Lark are wizard-guided and evolve with each platform's own console. Follow the prompts in the wizard rather than a static field list, and use `vibe doctor` if a connection doesn't come up healthy.
## Outbound proxy
When the host running Avibe cannot reach WeChat or Lark / Feishu directly, set `proxy_url` on the matching platform config block from the Web UI. Both HTTP/HTTPS proxies and SOCKS proxies are supported (any `socks*://` scheme — `socks4`, `socks4a`, `socks5`, or `socks5h`). Saving the config block only persists the change; run `vibe restart --delay-seconds 60` afterwards so the new transport applies to live connections.
## Shared troubleshooting
| Symptom | Check |
| - | - |
| Messages do not arrive | Platform credential, app installation, selected chat scope |
| Agent does not start | Backend enabled, CLI path valid, working directory exists |
| Responses appear in the wrong place | Channel or chat routing settings |
| WeChat / Lark unreachable from host | `proxy_url` on the matching config block; check firewall and TLS errors in logs |
# Quickstart
Source: https://docs.avibe.bot/quickstart
Install Avibe, launch the setup wizard, and send your first task from chat.
# Quickstart
This guide gets Avibe running on macOS or Linux with one chat platform and one coding agent.
## 1. Install Avibe
```bash theme={null}
curl -fsSL https://avibe.bot/install.sh | bash
```
Open source — view the [script on GitHub](https://github.com/avibe-bot/avibe/blob/master/install.sh). The short URL is a 307 redirect to that file.
Start it:
```bash theme={null}
vibe
```
The browser setup wizard opens automatically. If it does not, use the local URL printed in the terminal.
## 2. Install a coding agent
Choose at least one backend.
OpenCode:
```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```
Claude Code:
```bash theme={null}
npm install -g @anthropic-ai/claude-code
```
Codex:
```bash theme={null}
npm install -g @openai/codex
```
Verify:
```bash theme={null}
opencode --version || true
claude --version || true
codex --version || true
```
## 3. Configure the setup wizard
In the wizard, choose:
1. A chat platform: Slack, Discord, Telegram, WeChat, or Lark / Feishu.
2. An agent backend: Claude Code, OpenCode, or Codex.
3. A project working directory.
4. The channels or chats where Avibe should respond.
No chat app yet? You can skip the platform step — the built-in **Avibe Workbench** (a local web chat in the Web UI) is always on. Send the smoke-test message below from the Workbench instead, and add a chat platform later. See the [setup wizard](/get-started/setup-wizard).
## 4. Send a smoke-test message
In the enabled chat, send:
```text theme={null}
Say hello and tell me which project directory you are running in.
```
Then check local status:
```bash theme={null}
vibe status
```
## 5. Take it with you (avibe.bot Cloud)
Your Avibe shouldn't be stuck on your desk. From a phone, tablet, or borrowed laptop:
```bash theme={null}
vibe remote
```
One command pairs you with a personal `you-app.avibe.bot` URL through a secure avibe.bot tunnel. Your codebase and Agent runtime stay on your machine; the tunnel carries Web UI traffic back to it. See [avibe.bot Cloud](/concepts/remote-ui) for the full remote-access setup and the [Local-first boundary inventory](/concepts/local-first#what-leaves-your-machine) for every other network path.
# Commands
Source: https://docs.avibe.bot/reference/commands
Common Avibe CLI and chat commands.
# Commands
## Local CLI
### Service lifecycle
| Command | What it does |
| - | - |
| `vibe` | Start Avibe and open the local Web UI |
| `vibe status` | Show local service and configuration status |
| `vibe restart` | Restart all services |
| `vibe restart --delay-seconds N` | Restart `N` seconds from now so an active conversation can reply first |
| `vibe stop` | Stop the local Avibe service |
| `vibe doctor` | Run diagnostics for common setup issues |
| `vibe version` | Print the installed version |
Inside an Avibe desktop app, for example when one of its agents runs them,
`vibe stop` and `vibe restart` act only on the Avibe that app runs. If the Avibe
running on this machine belongs to another desktop app or was started some
other way, such as from a terminal, the command changes nothing, explains why,
and exits with status 3. This includes `vibe restart --delay-seconds N`, and a
restart requested from the Web UI shows the same refusal instead of restarting.
To stop or restart the running Avibe, run the command from wherever that Avibe
was started, or quit the other desktop app. Commands run from an ordinary
terminal outside a desktop app are not affected.
### Remote Web UI
| Command | What it does |
| - | - |
| `vibe remote` | Guided sign-in and pairing for the avibe.bot tunnel |
| `vibe remote pair ` | Pair using a one-time key copied from avibe.bot |
| `vibe remote status` | Show pairing and tunnel state (add `--json` for machine output) |
| `vibe remote start` | Start the cloudflared tunnel after pairing |
| `vibe remote stop` | Stop the tunnel without removing the pairing |
### Updates
| Command | What it does |
| - | - |
| `vibe check-update` | Check if a newer release is available |
| `vibe upgrade` | Upgrade Avibe to the latest release |
### Utilities
| Command | What it does |
| - | - |
| `vibe screenshot` | Capture the local desktop to a PNG file |
| `vibe runtime clean` | Remove stale Show, Git, Model Hub, and tmux runtime installs and archives; keeps each current runtime plus one rollback version, and exits nonzero if any cleanup fails |
| `vibe runtime clean --dry-run` | Preview what a cleanup would remove (files and bytes) without deleting anything |
| `vibe data retention` | Show how many old internal trace events are eligible for cleanup, the last run, and reclaimable database space |
| `vibe data retention --run [--days N] [--compact]` | Delete internal tool-call trace events older than the window now; add `--compact` during a maintenance window to also VACUUM the database when safe |
Show Runtime archives accumulate under `~/.avibe/runtime/show-runtime/downloads`
as new versions are installed. Cleanup keeps the archive used by the current
runtime plus the rollback version, and removes only verified, completed
archives. `vibe doctor` reports when stale archives are reclaimable.
Internal agent trace events (`agent_events` tool-call traces — diagnostic
material, never chat messages) are retained for 30 days by default. A daily
background pass deletes only older traces; chat history, deliveries, and
newer traces are never touched. Configure the window or opt out via the
`runtime.agent_events_trace_retention_days` and
`runtime.agent_events_trace_retention_enabled` config fields. The automatic
pass never compacts the database — physical space is reclaimed by the
explicit `vibe data retention --run --compact` maintenance command (best run
during a maintenance window or with the service stopped, because VACUUM
briefly holds the database's sole writer lock), which compacts only
after a free-space safety preflight and reports a reason when it defers.
### Show Pages
| Command | What it does |
| - | - |
| `vibe show status` / `path` / `list` | Inspect, resolve, or list the session's [Show Page](/concepts/show-pages) |
| `vibe show update --visibility private\|public\|offline` | Set visibility, a custom public link, or take the page offline |
| `vibe show annotate --on\|--off [--mode smart\|screenshot]` | Turn the user's [annotation](/concepts/annotating-show-pages) overlay on/off or switch mode (no chat message) |
| `vibe show reply --message "…"` | Answer a page annotation, anchored where the user pointed |
| `vibe show mark --message "…"` | Leave a callout on an element (same target replaces) |
| `vibe show marks` / `vibe show unmark …` | List active marks / retire one or more |
Show Pages are the agent's visual surface and the [annotation](/concepts/annotating-show-pages) loop
runs over them: the user points at the page, the agent answers back on it. The
agent drives these commands — a user rarely runs them directly.
### Vaults
| Command | What it does |
| - | - |
| `vibe vault list` / `find` / `tags` | Discover secret names and value-free metadata without revealing values |
| `vibe vault request ` | Ask the user to provide a missing secret in the Workbench |
| `vibe vault run` | Inject selected static secrets into one child process |
| `vibe vault fetch` | Attach a static credential to an authenticated HTTP request at egress |
| `vibe vault access` / `await` | Request approval for protected use and read the completed request |
| `vibe vault sign` | Sign a 32-byte digest with a keypair; the private key is never exported |
Agents refer to [Vaults](/concepts/vaults) by secret name, tag, or Skill tag.
Standard secrets are available now. Protected operations describe a pre-launch
passkey flow and must not hold real secrets until the immutable sandbox integrity
gate is enforced. Avoid commands that print environment variables or
secret-bearing debug output when using `vibe vault run`.
### Agent Harness
| Command | What it does |
| - | - |
| `vibe agent run` | Run one Agent job now; add `--async` for one-shot background work, or `--fork-session` to branch from an existing Session |
| `vibe runs list` / `show` / `cancel` | Inspect and manage concrete Agent Run records |
| `vibe task add` | Save a recurring or one-off time trigger that creates Agent Runs later |
| `vibe task list` | List saved tasks (use `--brief` or `--all`) |
| `vibe task show` / `update` / `pause` / `resume` / `run` / `remove` | Manage one saved task |
| `vibe watch add` | Run a managed waiter that creates a follow-up Agent Run when it succeeds |
| `vibe watch list` / `show` / `pause` / `resume` / `remove` | Manage one watch |
Together these commands form the Avibe Harness. A user can ask their
agent to watch a PR, wait for CI, schedule a daily status check, start a
separate investigation session, or fan out background checks. The agent can
combine the primitives without making the user memorize every flag.
Each subcommand accepts `--help` for the full argument list, including
`--session-id`, `--fork-session`, `--post-to`, `--deliver-key`, `--message`,
`--message-file`, `--cron`, `--at`, `--async`, and `--timezone` where
applicable.
Use `vibe agent run --fork-session --message "..."` when a new
Agent Session should branch from an existing Session's native backend context.
The fork keeps the source backend. `--agent`, `--model`, and
`--reasoning-effort` may override the forked Session only when the Agent backend
does not change.
## Chat usage
| In chat | What it does |
| - | - |
| Mention the bot | Start a task or ask a question |
| Reply in thread | Continue the same agent session |
| `/stop` | Stop the current session where supported |
| Plain message in enabled scope | Send work to the configured agent |
# Reverse proxy & custom domains
Source: https://docs.avibe.bot/self-hosting/reverse-proxy
Serve Avibe's Web UI behind your own reverse proxy on a custom HTTPS domain.
# Reverse proxy & custom domains
Avibe's Web UI listens on `127.0.0.1:5123`. The simplest way to reach it from elsewhere is the [avibe.bot tunnel](/concepts/remote-ui). To front it yourself with your own reverse proxy on a custom domain — for example **nginx on `https://avibe.example.com`** — declare your proxy and its public domain as trusted using the two settings below.
## Configure
Set both environment variables where the `vibe` service runs (shell profile, service-manager unit, or container env), then restart Avibe:
```bash theme={null}
# The address Avibe sees your proxy connect FROM — the direct peer, not the browser.
# Same-machine nginx → 127.0.0.1. Another host/container → its IP or CIDR. Comma-separate multiple.
VIBE_UI_TRUSTED_PROXY_IPS=127.0.0.1
# The full public origin your proxy serves — with scheme, no path. Comma-separate multiple.
VIBE_UI_TRUSTED_PUBLIC_ORIGINS=https://avibe.example.com
```
Both are required together — with only the proxy IP set, the custom domain still won't load. (You can also set the origins in the config file as a list under `ui.trusted_public_origins`.)
Then have nginx forward the browser's host and scheme:
```nginx theme={null}
server {
listen 443 ssl;
server_name avibe.example.com;
# ssl_certificate / ssl_certificate_key ...
location / {
proxy_pass http://127.0.0.1:5123; # your Avibe Web UI address
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# Live updates use WebSockets
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
On a non-standard external port, also forward `proxy_set_header X-Forwarded-Port $server_port;` and include that port in the declared origin.
## Authentication is your responsibility
This mode treats your proxy's requests as local and does **not** add an Avibe sign-in. Put your own authentication in front of the proxy (nginx basic auth, Authelia, an SSO proxy, …), or keep it on a private network (VPN / LAN only). Don't expose the declared domain to the open internet without your own auth.
## Using it with the avibe.bot tunnel
If you also run the tunnel, your proxy must reach Avibe over a **non-loopback** address. A loopback (`127.0.0.1`) proxy is refused while the tunnel is enabled, so that a request coming through the tunnel can't impersonate your custom domain.
Bind Avibe to a LAN or bridge address, point nginx there, and set `VIBE_UI_TRUSTED_PROXY_IPS` to that address (not `127.0.0.1`). Or run just one of the two.
## Troubleshooting
Load the Web UI on your custom domain. If the page returns `503`, or a state-changing action returns `403`:
* confirm **both** variables are set, and `VIBE_UI_TRUSTED_PUBLIC_ORIGINS` matches the browser's origin exactly — scheme included, no trailing path, and any non-default port;
* confirm the proxy's real source IP is the one in `VIBE_UI_TRUSTED_PROXY_IPS`;
* confirm nginx forwards `Host`, `X-Forwarded-Host`, and `X-Forwarded-Proto`, and that you restarted Avibe;
* if you also run the tunnel and your proxy is on loopback, that combination is refused by design — see above.
The service log flags entries that were ignored or didn't take effect.
# Common issues
Source: https://docs.avibe.bot/troubleshoot/common-issues
Fix common Avibe installation, platform, and agent setup problems.
# Common issues
## `vibe` command missing
Check whether the installer printed PATH guidance.
Then inspect:
```bash theme={null}
command -v vibe || true
echo "$PATH"
```
If installed through `uv tool`, the tool bin directory may not be loaded in your current shell.
## Agent CLI not found
Verify the selected backend:
```bash theme={null}
command -v claude || true
command -v opencode || true
command -v codex || true
```
Install the missing backend or update the CLI path in the setup wizard.
## Chat bot is silent
Check:
* The platform credential is correct.
* The bot or app is installed into the workspace/server/group.
* The channel or chat is enabled in Avibe.
* The selected backend is enabled.
* The working directory exists.
Then run:
```bash theme={null}
vibe doctor
```
## Slack bot is silent
Check:
* Socket Mode is enabled.
* Bot token scopes are correct.
* App-level token is correct.
* Bot is invited to the channel.
* Channel is selected in Avibe.
## Telegram group is silent
Check:
* Bot privacy mode.
* Whether the bot needs to be mentioned.
* Whether the group appears in discovered chats.
* Whether the group is selected in Avibe.
## Web UI is unreachable from another device
Localhost only works on the same machine.
Use:
```bash theme={null}
vibe remote
```
This opens the local Web UI through a secure avibe.bot tunnel.
## Custom domain returns 503 or 403
If you front the Web UI with your own reverse proxy on a custom domain and the page returns `503` (or a state-changing action returns `403 invalid origin`), Avibe hasn't been told to trust that domain.
Declare **both** `VIBE_UI_TRUSTED_PROXY_IPS` (your proxy's IP) and `VIBE_UI_TRUSTED_PUBLIC_ORIGINS` (e.g. `https://avibe.example.com`), and forward the host headers — the proxy IP alone still returns `503`. See [Reverse proxy & custom domains](/self-hosting/reverse-proxy).