An automation starts a real turn, or a published Workflow version, when you run it by hand or when the schedule fires. Each run leaves an auditable Conversation and Turn.

Entry point

Open Settings → Automations. From the empty state, New or a starter template. Templates fill an editable draft. Saving and running stay manual after you edit the draft.

Create

New asks for a type first. The type is fixed at creation:

• Single session: each run creates a real turn with the chosen agent, workspace, and prompt.
• Workflow: runs one published Workflow version. To target a different version, create another automation.

The form includes name, project, agent or workflow, prompt, branch, isolation, and trigger.

Isolation:

• Create an independent worktree per run (default)
• Share the project root: uses the current checkout. The backend rejects a dirty tree or a mismatched branch, and it will not merge, push, or publish.

Trigger is Manual or a schedule. A schedule can preview the next five runs. Timezone is an IANA name.

Save when the form is complete. The list switch is Enabled. A disabled row is skipped by the scheduler.

Run and history

Run now fires one execution immediately. Run history lists Running, Completed, Failed, Cancelled, Interrupted, and Skipped. A running row can Cancel run. Workflow targets offer Open Workflow.

Import and export

Copy spec JSON copies a document that omits database identity, secrets, and machine paths. Import JSON pastes it and leaves the row disabled until you enable it. Import resolves project, agent, and workflow references on the current Host.

Engine owner

For one data directory, only one automation engine owner exists at a time: the current desktop or vibex-server. Only the owner claims due jobs. If the page says the engine is held by another host, the view is read-only until that process releases it.

On Host startup, leftover direct-turn runs become Interrupted. Runs already attached to a Workflow run follow that run’s terminal state. Neither is fired again automatically. While the Host was down, at most the most recent missed schedule is backfilled.

Finished runs and their independent worktrees are kept for 30 days by default, under a per-directory space quota. Running runs stay until they finish.

A Host is the VibeX process that owns the data directory and serves the remote protocol: this machine’s desktop app, or vibex-server. Another desktop, the browser WebUI, and a phone companion all connect to it.

Everyday single-machine use is the desktop app. Open remote listening, or switch to Server, when other devices must connect or you want a headless process. Headless setup is Install Server and WebUI.

If a Server already holds the data directory, a second desktop attaches as a client.

Open remote listening

Open Settings → Remote connection.

Service status is Running or Stopped. One listen port serves both the Web UI and the remote protocol. Default port is 17891.

Access configuration:

• Listen port: browsers and paired devices use this port. Probe reports the port’s availability.
• Auto start: open Remote Protocol when the app launches.
• Allow LAN: listen on all interfaces. Public access needs a TLS reverse proxy in front.
• Access token: generate and copy. The full value is shown once; save it before leaving the page.

Save, then Start. Status shows this-computer, LAN, and published addresses. Copy address or Open.

Listening defaults to loopback. Turn on Allow LAN before a phone scans; a 127.0.0.1 QR is unreachable from the phone.

Device pairing

Device pairing on the same page issues a five-minute code that can be redeemed once.

Device class is Companion or Workstation:

• A workstation can use conversations, Git, terminal, and plugin management. Host listen settings, admin token, backup/restore, and upgrades stay on the Host under Settings → Remote connection and System. Backup steps: Backup and restore.
• A companion is narrower. See Phone companion.

Click Generate connection code. The other device scans the QR or types the code. Long-lived credentials go in the system keychain or Android Keystore.

Paired devices lists redeemed devices. Revoke forces a new pairing before that device can connect again.

Desktop and Server must be in the same version family. A capability mismatch fails the pairing.

WebUI

Open the Web UI address from the status section in a browser. Agents, Git, and the terminal still execute on the Host. Use the host address and access token from this page.

While the Host is offline, clients read the supported offline cache. New turns and permission answers need the Host online.

The Android companion connects to a Host you control. On the phone you read conversations, send input, and answer permissions. Agent processes, the plugin kernel, and Git writes stay on the Host. The current companion is Android.

Prepare the Host

1. Keep the Host online: this desktop or vibex-server.
2. Open Settings → Remote connection, save, and Start.
3. Turn on Allow LAN so the phone can reach a non-loopback address.
4. Set Device class to Companion, then Generate connection code.

Pair on the phone

Open the Android app and scan the QR or type the one-time code. Credentials stay in the system keystore and reconnect later.

The code lasts about five minutes and can be redeemed once. Keep the pairing code and access token on the pairing UI and in the system keystore.

What you can do

• Read the timeline, send input, cancel an in-flight turn, and steer.
• Approve or deny permission requests. The result matches desktop and writes the same event log.
• Read supported artifacts and the offline cache.
• Receive terminal-state notification summaries.

Where the rest lives

Plugin authoring, Workflow and automation definitions, a full terminal, and Git commit/push stay on the Host or a paired workstation desktop.

Plugins add product capabilities to the current Host. A package may ship Skills, MCP, Workflows, or UI. Open Settings → Plugins (Plugins in the settings sidebar). Newly installed packages start disabled. Contributions become visible after you enable them.

The page

The catalog lists packages on this Host. Built-in packages show VibeX built-in and remain in the catalog; the switch only enables them. Click a row for Content and Config.

Import plugin installs a local package or a linked development directory. Third-party packages stay on this Host. Published marketplace packages: Install a Plugin from the marketplace.

Built-in packages

Shipped with the Host, disabled by default:

• Session Enhance: questions, live feedback, session lookup, and session control.
• Multi-agent: parent agents delegate subtasks; & appears in the composer. See Agent delegation.
• Workflow Creator: edit, validate, debug, and publish a DAG. See Graph Workflow.
• VibeX Office: create, analyze, and preview DOCX / XLSX / PPTX. See Files and preview.
• Plugin Development: a local dev interface for authors. Everyday use can leave it off.

Open a row, read the summary and contents, then enable. The first enable projects compatible Skills, MCP, or Workflows onto installed, enabled agents.

Later new or rebound sessions receive those tools. Sessions that were already open keep the tool list from creation.

Config

Config edits that package’s config.json, for example the four Session Enhance toggles, Office preview idle timeout, or Workflow Creator’s default completion policy. Saves apply to later new sessions or new previews. Instances already open keep their current settings.

Disable and uninstall

Turning enable off stops new turns from using the package’s contributions. History already in the event log stays.

Third-party installs can Uninstall plugin. Uninstall removes membership, agent bindings, and Skill projections. Conversation and automation history remain. Built-in packages are disabled with the switch.

A workstation desktop can change plugin facts on the Host through the application core. The management UI is Settings → Plugins.

To write a plugin, see Developer docs.

The marketplace publishes reviewed VibeX Plugins. Install with a local command or import a .vxp into the current Host. The package stays on that Host; it is not copied to other machines.

Start at the plugin marketplace. The contract is in the developer docs. Enablement is in Install and enable a Plugin.

Before you start

1. VibeX desktop is running, or npx vibex serve has started a Host.
2. The shell can run npx vibex.
3. If desktop or npx vibex serve is running, plugin add finds the local Host token and imports into the catalog. If no Host is up, the package lands in ~/.vibex/imports/ and Desktop imports it on the next launch. Default URL is http://127.0.0.1:17891; override with VIBEX_URL / VIBEX_TOKEN.

Install command

1. Open the plugin marketplace and open the plugin page.
2. Copy the Installation command. The full form is:

npx vibex plugin add https://vibex.xforver.xin/marketplace/<author>/<plugin>

Replace the URL with the plugin page on the site you are using. A local preview host is http://127.0.0.1:3100/marketplace/<author>/<plugin>.

3. Run it. The CLI asks the marketplace for a download URL, unpacks the .vxp, validates the product layout, writes a deterministic package, and imports it when a local Host is available.

4. If the archive contains more than one package, add --plugin <plugin-id>. Use --yes when stdin is not a TTY.

5. Open Settings → Plugins. A new install starts disabled. Enable it so Skills, MCP, or UI reach later new or rebound sessions. If the command says Desktop will import on next launch, quit VibeX fully and open it again.

A GitHub repository also works: npx vibex plugin add https://github.com/<owner>/<repo>. Prefer the marketplace page URL when the listing exists.

Import a package file

The plugin page offers Download package. After you have a .vxp (or zip / tar.gz):

1. Open Settings → Plugins.
2. Choose Add plugin or Import plugin and pick the file.
3. Confirm identity and permissions, then install.
4. Enable the row in the catalog.

Dropping a .vxp onto the plugins page is the same as choosing a file.

What the command does

plugin add runs in this order:

1. Detect a marketplace page, a GitHub URL, or a local file.
2. For a marketplace page, call /api/marketplace/artifact/<author>/<plugin> and follow the published download URL.
3. Unpack the archive and look for .vibex-plugin/plugin.json.
4. Validate the product package and write ~/.vibex/imports/<plugin-id>-<version>.vxp.
5. If a token is present and install is confirmed, call Host plugin_control_import.

Unpublished submissions have no marketplace download URL, so the command fails. A broken layout or an unreadable archive fails the same way.

After install

The catalog lists the plugin. Built-in rows show VibeX built-in; marketplace installs can be uninstalled. Config, disable, and uninstall are in Install and enable a Plugin.

To ship your own package, follow the developer docs, run vibex plugin pack, then submit the .vxp on the marketplace.

Page layout sets the left-to-right order of the main window regions. Kanban and Workspace each keep their own arrangement. Dragging changes order only. Width belongs to the region itself and stays the same after a swap.

The same settings page also has theme, UI zoom, monospace font, and language. This article covers region order only.

Entry point

Open Settings, then Appearance. Scroll to Page layout. The schematic has two blocks: Workspace page and Kanban page.

The main-window toolbar can show or hide Kanban regions and offers Reset Kanban layout. That is a per-window shortcut. The arrangement saved in Settings is separate.

Kanban page

Kanban has three regions:

• Session list: board columns and session cards.
• Session monitor: status and usage for the selected session.
• Session execution: timeline, composer, and execution area.

Hold a region in the schematic and drop it on another region to swap them. Save settings at the bottom of the page; the main window then follows the new order. Dragging without saving leaves the main window unchanged.

Restore default returns the Kanban schematic to the factory order. Save still required to write it back to the main window.

After save, splitters on the page still resize regions. Hiding a region from the toolbar affects the current window only and leaves the saved order unchanged.

Kanban usage: Session board.

Workspace page

Workspace has four regions:

• Sidebar panels: file tree, Git, review, and related sidebars.
• Workspace: files and preview.
• Session: timeline and composer.
• Terminal: the built-in terminal.

Same mechanic as Kanban: drag to swap in the schematic, then save. Restore default applies to the Workspace schematic only.

Files and preview: Files and preview. Terminal: Terminal.

Save and sync

Layout is stored in local frontend preferences. After the settings window saves, the main window syncs through a storage event and rearranges immediately. All windows share one arrangement.

Theme, zoom, and language changes leave layout unchanged. A new machine needs the arrangement set again. Moving Host data is described in Backup and restore; the backup preview lists the files actually included.

Prompt enhancement uses an enabled Agent to rewrite the draft in the session composer into a clearer, actionable prompt, then writes the result back into the composer. It changes the draft only. No turn is started. Original intent stays the same.

Entry point

Open Settings, then General, then Prompt enhancement. Turn on Show prompt enhancement button. The session composer toolbar then shows Prompt enhancement.

That Agent must already be enabled and ready under Settings → Agents. If the list is empty, finish Enable and authenticate first.

Configuration

In the Prompt enhancement block:

• Agent: the rewrite Agent. Changing Agent clears mode and session config chosen here.
• Refresh session controls: reload that Agent’s current modes and options.
• Mode and session config: the same kind of options as Create session, for example model. They apply only to the rewrite call.
• Use custom enhancement prompt: off uses the built-in system prompt; on lets you edit it. The built-in prompt requires JSON with exactly one top-level field, EnhancedPrompt.

Save settings afterward. Until save, the composer button still uses the last saved configuration.

A rewrite consumes that Agent’s quota or API budget under the same rules as a normal turn.

Usage

Type a draft in the session composer, then click Prompt enhancement. An empty draft or whitespace-only draft produces no request.

On success, the composer text is replaced with the rewrite. Review it, then send to start a turn. On failure, the error appears on the composer and the original draft stays.

The rewrite request includes the current session and workspace ids, plus recent messages, so the rewrite Agent can resolve ambiguity. The built-in system prompt requires using that context only when it materially helps, omitting a conversation summary from the result, and omitting Markdown fences or extra fields.

Turning it off

Turn off Show prompt enhancement button and save. The composer hides the button. Text already in the composer is unchanged.

Import local sessions scans official conversation history that an enabled Agent already stored on this machine, writes the selected items as VibeX conversations, and attaches them to a chosen project workspace. After import they appear on the board and in the session list for viewing and sending. The Agent’s original files stay in their official directories.

This is separate from Continue a previous session when creating a conversation. That path binds an Agent-native session id in the create dialog. This feature writes VibeX conversation records in bulk.

Entry point

Open Settings, then General, then Local conversations, then Import. The Import local conversations dialog opens.

You need at least one enabled Agent and at least one opened project. With no project, destination pickers in the dialog stay unusable. Open a project first: Open a project.

Scan

Choose an Agent at the top of the dialog. The scan of that Agent’s local history starts immediately and groups conversations by folder. With exactly one enabled Agent, opening the dialog selects it and starts the scan.

While scanning, the dialog shows Scanning local conversations…. On failure it shows the reason and Retry.

Results are grouped by folder. Each group shows the path, conversation count, and an Import into workspace. The search box filters by folder name, path, or conversation title. Only not yet imported hides items already imported.

Destinations and selection

Each folder needs an import target:

• When VibeX already matches a project or workspace, the dropdown is prefilled.
• Groups labeled Choose project require a manual project. With no project available, conversations in that group stay unchecked.

Check conversations to import. Select all covers importable items in the current filter that already have a target. Items marked Already imported stay unchecked.

Rescan drops the current checks and scans the same Agent again.

Import

Import (N) writes the selection. The dialog stays open until import finishes. When finished it shows three counts:

• Imported: new VibeX conversations.
• Skipped: a matching record already existed.
• Failed: rows that could not be written, with error text below.

Imported conversations appear on that workspace’s board and session list. Titles reuse the Agent-side name when present; unnamed conversations show Untitled conversation. Later send, permission, and Git actions match conversations created inside VibeX.

Close ends this pass. Open Import again for another batch.

Scope

Import writes the Host conversation store. Agent official config and auth files stay in place, for example Claude Code still uses ~/.claude. Deleting a VibeX conversation leaves Agent-side history in place. A later scan marks those items Already imported.

Commit reminder inspects uncommitted changes in the current workspace after a user turn ends. When added plus deleted lines strictly exceed the configured boundary, it hands the official instruction #commit_changes to the same Agent so it can review the diff and commit. Automation turns and internal turns skip this check.

The instruction body lives in Settings → Instructions in the official instruction market, id commit_changes. When a reminder fires, the Agent receives that body plus the current added/deleted line count.

Entry point

Open Settings, then Version control, then Commit reminder. Staging and committing in the Git panel remain manual, as in Git and review. This switch only controls the post-turn reminder.

Configuration

• Enable commit reminder: after this is on, a user-started turn that reaches a terminal state is measured.
• Reminder mode:
  • Separate reminder: start another turn immediately. The timeline shows #commit_changes. The Agent reviews and commits per the instruction.
  • Smart mode: record a pending reminder, then prepend the same instruction to your next user message on that conversation.
• Change line boundary: lines. A reminder fires only when added plus deleted lines are greater than this number. Equality skips the reminder.

Save Version control settings afterward. A very low boundary reminds after small edits; a very high boundary almost never reminds. The number currently shown on the page is the default in force.

#commit_changes tells the Agent to read git diff and git diff --staged, then stage and commit. The commit message format is a first line under 50 characters as <type>(<scope>): <subject>, a blank line, then a detailed body. Types include feat, fix, docs, style, refactor, perf, test, chore, revert. The actual commit follows the workspace diff.

Separate reminder

After a user turn completes normally, the Host counts uncommitted added and deleted lines in the workspace. Over the boundary, it starts the reminder turn. That turn’s origin is commit reminder, so a later reminder check skips it.

A workspace without a Git repository, or a failed count, skips this round. If a turn is already in flight on the conversation, the reminder waits until the conversation is idle.

Smart mode

After a user turn, if the count is over the boundary, the Host only sets pending reminder and starts no new turn. The next time you send on that conversation, the Host counts again. Still over the boundary, #commit_changes is prepended to your text. Already under the boundary, pending reminder is cleared and only your text is sent.

Turning the feature off, or switching the mode back to Separate reminder, discards a reminder that has not been sent yet.

Turning it off

Turn off Enable commit reminder and save. Later user turns skip the line count. A reminder turn already started is treated as a normal turn and can be stopped. To edit the commit-message template, open Settings → Instructions and edit the commit_changes body.

Worktree settings control where Git worktrees are created, how new task branches are named, and which commands each project runs on create and destroy. Binding a session to a tree is described in Worktree. This article covers the settings page only.

The project must already be a Git repository before a worktree can be created.

Entry point

Open Settings, then Worktrees. The page has two blocks: Global worktree settings at the top, Project worktree settings below.

Global worktree settings

These two fields apply to every project:

• Workspace directory: root used when creating task worktrees and temporary project directories. Type a path or Browse with the folder dialog. Empty uses the product default location.
• Branch prefix: default prefix for new task branches, for example vibex. The task id is appended after this prefix.

Empty prefix, spaces, a leading or trailing /, //, and the characters ~ ^ : ? * [ \ are rejected. Invalid input disables Save and shows the reason on the page.

Save in that block writes only these two fields. Project settings below are saved separately.

Project worktree settings

The Project dropdown lists projects you have opened. Each project has its own configuration. With no opened project, the dropdown shows No opened projects yet.

Lifecycle commands

• Command after create: runs after the worktree exists on disk and before the first session on that tree, for example pnpm install. Empty skips the command.
• Command before destroy: runs before VibeX deletes that worktree, for example pnpm run clean. A failing command cancels the delete; the tree stays so you can read the output.

Commands run on the Host machine. The working directory is that worktree. The toolchain those commands call must already be installed there.

Cleanup reminder

• Prompt before exceeding the limit: when on, creating another worktree that would push this project over the cap shows a confirmation.
• Worktree count limit: a positive integer. The page also shows how many worktrees the project already has.

The confirmation offers:

• Continue creating: create anyway, past the cap.
• View worktrees: abandon this create and go manage existing trees.

Worktrees owned by a running turn or automation run count toward the total and are kept on delete. Deleting the folder in the file manager leaves a stale registration, so the count drifts. Remove trees with the in-app Git worktree actions.

Save settings in the project block. Success shows Worktree settings saved.

Automations

Automations default to one independent worktree per run. They use this page’s global root and branch prefix. Project lifecycle commands run on that project’s trees. See Automations.

A message channel attaches this Host’s coding activity to Telegram, Feishu, WeCom, QQ, or a generic webhook. It is a bot configuration on the Host, separate from paired phones or workstations. Send and receive stay in the vendor IM apps.

Channel config and secrets live in the Host data directory. A remote workstation can start sessions. Creating, disabling, and rotating secrets stay on the Host machine under Settings.

Entry point

Open Settings, then Chat channels (Message channels). Three tabs: Channels, Commands, and Events.

Channels

Channels lists bots saved on this machine. New channel asks for:

• Name: the list label, required.
• Type: Telegram, Feishu bot, WeCom group bot, QQ bot, generic webhook.
• Credentials and chat binding for that type, next section.
• Enable channel: off stops event delivery and Test send. The row stays in the list.
• Authorized senders: one user ID per line. Inbound commands apply to the bound chat or group above, or to IDs on this list. Other messages are dropped. An empty list trusts only the bound chat or group.

After save, Test send posts a probe message. A row offers Edit channel, Delivery log, and Delete channel. Delete asks for confirmation and removes the secret as well.

Delivery log shows the latest delivery result and detail. On a failed send, read this log, then check credentials and network.

Telegram

Token from @BotFather. Optional chat id (negative for groups, numeric for DMs). Forum supergroups can enable Telegram topic mode: one topic per conversation; the general topic ignores plain text.

Feishu bot

App secret and group Chat ID. Groups usually require an @ mention before text is treated as a command.

WeCom bot

Add a group bot in the group settings, copy the key= value from the webhook URL, and paste it as the secret. Scan WeChat code binds a send/receive Weixin iLink bot.

QQ bot

OneBot HTTP URL for send. Optional forward WebSocket for inbound commands; empty derives it from the HTTP URL. Optional access_token. Message type is group or private, plus group id or QQ number.

Generic webhook

POST turn and permission summaries to an http:// or https:// URL. Events can add multiple URLs. Payload examples show JSON for prompt_started, prompt_finished, and similar events, with event, body, and source.

Commands

Commands sets the command prefix, for example /vibex. Authorized senders type prefix plus command in the IM. The usage list on this tab is authoritative:

• folder [n|name]: list projects, or pick by index or name.
• agent [n|id]: list agents, or pick by index or id.
• task <text>: send a task to the currently selected conversation.
• sessions: list recent conversations on this Host.
• resume [n|id]: select by index or conversation id and continue.
• cancel: cancel the in-flight turn.
• approve [always]: approve a pending permission; always keeps allowing that class of action.
• deny: deny a pending permission.
• search <keyword>: search conversations.
• today: list conversations created today.
• status: channel and Host status.
• help: list every command.

Put your own user ID in Authorized senders first, then colleagues. Permission and question cards posted to IM resolve the same pending request as the desktop. See Permission prompts.

Events

Events chooses which coding activities are pushed. Only checked items are sent:

• Task started: the Agent began a turn.
• Task finished: the Agent finished this task.
• Permission requested: approval or denial is needed in IM.
• Run error: the Agent reported an error.
• Connection status: Agent connection changed.
• Session created: a new conversation was created.
• Turn completed: a turn reached a terminal status.

Include prompt content in notifications is off by default. Off omits the raw prompt from a task-started notice so drafts stay out of IM. Turn it on and save when the raw text is required.

Daily digest is per channel and summarizes that day’s activity in the bound chat. The time shown on that channel row is authoritative.

Safety

Channels deliver summaries that omit secrets. Tokens, pairing codes, and .env stay in Host config. Point webhook URLs at receivers you control. After a channel is disabled or deleted, that IM stops receiving new events.

Run logs record diagnostics from the desktop app process. They are written to local files and kept in memory on the settings page for live viewing. Use them for startup failures, Agent connection errors, and Git or automation faults.

This page is in the desktop Settings sidebar. The current WebUI Settings sidebar has no Run logs item.

Entry point

Open the desktop Settings window, then Run logs.

Capture level

Capture level is the lowest severity written to files and to the viewer, from least to most:

• Off: recording stops.
• Error
• Warn
• Info
• Debug
• Trace
• All

Debug, Trace, and All write the most and grow files the fastest. Info or Debug is enough for routine diagnosis. Changes save immediately.

When VIBEX_LOG or RUST_LOG is set, capture level is locked. The page shows Capture level is locked by VIBEX_LOG or RUST_LOG, and the dropdown is disabled. Unset those variables and restart the app to change the level here.

Per-module overrides

Per-module overrides set a level on one module without changing the global capture level. Add picks a module name and a level. Remove deletes that override.

Modules include agents, application, automation, conversations, db, delegation, git, plugins, server, services, workflows, and others. Override only the module under investigation. Leave the rest of the process on the global capture level.

Recent logs

Recent logs shows the in-memory stream, up to 2000 lines. Tools:

• Pause / Resume: while paused the viewer stops appending; capture still writes files.
• Refresh: fetch again.
• Clear: drop the in-memory copy. Files on disk stay.
• Open folder: reveal the log directory in the file manager.
• Search: filter by message body or source.
• Level filter: show error, warn, and so on.

The footer shows Shown N / M. An empty viewer shows No logs.

If Open folder fails, check desktop permissions. Before attaching that directory to an issue, delete lines that contain paths, tokens, or raw prompts.

Versus the session timeline

Tool calls and Agent output on the session timeline belong to that conversation’s event log. See Turn control. This page is the VibeX desktop process’s own diagnostics: Host start, IPC, Git, plugin load, and similar.

Backup packs this Host’s VibeX data into a portable .vibexbak file, optionally encrypted with a passphrase. Restore requires a preview first, so overwrite targets are visible before write. Use it when moving machines, reinstalling the OS, or keeping a copy before clearing local data.

This page is under desktop Settings → System. The current WebUI Settings sidebar has no System item.

A backup covers VibeX’s own store and config. It omits project Git repositories and each Agent’s official directories (for example ~/.claude, Codex auth.json). Move those files with each Agent’s own tools.

Entry point

Open the desktop Settings window, then System, then Backup & Restore.

Export

Export backup asks for a destination path with a .vibexbak suffix. Encrypt passphrase is optional; empty packs without encryption. Click Export.

While running, the page shows Exporting VibeX backup.... Success shows Backup exported. An empty path shows Please enter a backup export path.

The archive typically includes:

• config.json, profiles.json, and db.sqlite from the Host data directory
• version-control-settings.json, instructions-metadata.json, system-settings.json
• web-service-settings.json, chat-channel-settings.json, chat-channel-secrets.json
• settings.json and mcp.json under the user VibeX directory, plus files under skills/

The preview after export, or the preview before restore, is the authoritative file list. Missing files on disk are left out of the pack.

Keep the file on a disk you control, or on an encrypted volume. Treat a pack that contains chat-channel-secrets.json and the database as confidential.

Preview

Restore backup first takes a .vibexbak path. Encrypted packs also need the decryption passphrase. Click Preview.

A successful preview shows format, version, app version, created time, file count, and paths that would be overwritten. Rows marked Will overwrite replace the live file on restore. A wrong passphrase or a damaged file shows Backup preview failed.

Preview must finish before Restore is available. Skipping preview shows Please preview the backup to restore first.

Restore

After preview, click Restore and confirm. While running, the page shows Restoring VibeX backup.... Success shows Backup restored. Restarting the app is recommended. After restart, conversations, channels, instructions, and settings match the backup.

Restore writes the current Host data directory and replaces files marked in the preview. Conversations, channels, and settings created on this machine after the backup are replaced by those files. Git commits inside project workspaces stay.

Failures

Export or restore errors show Backup export failed or Backup restore failed plus a reason. Typical causes: no write permission on the path, insufficient disk space, passphrase mismatch, or a file that is not vibex-portable-backup. Change the path or passphrase and preview again.

Clear local data returns this Host’s VibeX configuration, conversation store, and caches to a freshly installed state, then registers built-in Agent rows again. Git repositories on disk, worktree folders, and each Agent’s official directories stay in place.

This page is under desktop Settings → System. The current WebUI Settings sidebar has no System item.

Clearing is permanent. Keep conversations, channels, and settings by finishing Backup and restore first.

Entry point

Open the desktop Settings window, then System, then Clear VibeX local data. Click Clear local configuration and cache.

A confirmation dialog asks for a second confirmation. Confirm to start.

What runs

The Host stops scripts and processes still running. If a process stays running, the operation aborts. Stop it by hand, then retry.

It then deletes local config files and the cache directory, empties business tables in the conversation database, writes default settings, and registers built-in Agents again. Desktop toasts and file watchers reset.

While running, the page shows Clearing local data.... Success shows Local data cleared and asks the app to reload. After reload the board is empty. Open projects, enable Agents, and configure channels again.

Removed and kept

Removed or reset: VibeX settings, conversations and turns, workflow runs, message channel config, automations, plugin enabled state, local caches.

Kept: project folders and their Git history, Git worktree directories already created, each Agent’s official config and login (for example ~/.claude), and .vibexbak files you saved yourself.

Opening the same project afterward registers it as a newly opened repo. Worktrees that still exist on disk need a new bind as in Worktree, or cleanup with Git.

Failures

On Clear local data failed, wait for the current attempt to finish. Confirm no Agent or terminal process is stuck, then retry. If another program holds the database file, quit that program and retry.