Vibeface

Chat with a bot. Run work on your own computers. Keep the results in one conversation.

English · 简体中文

Note

Vibeface is in Nightly. Before the first stable release, protocol, data, and API changes do not preserve backward compatibility. Use the same version on all computers in your network.

Contents

• What you can do
• Get started
• Add another device
• Public discovery service
• Privacy and permissions
• Documentation
• Build from source
• Repository layout
• Contribute
• License

What you can do

• Ask in chat. Give a bot a name and a job, then use its conversation to ask for work and review results.
• Choose a computer. Run tasks on your own Mac or Linux computer using Codex, Claude Code, pi, opencode, or Cursor.
• Continue elsewhere. Approved computers share conversations, task updates, and saved results. Open a synced conversation on another computer and choose to continue there.
• Check from your phone. Connect through a browser or the native iOS and Android apps.

Vibeface coordinates the work. You provide the Agent, its login and model access, and the project folder on each computer. Project files, dependencies, and logins do not move with the conversation.

Get started

You need an Apple Silicon Mac, Linux x64, or Linux ARM64 with glibc, plus a supported Agent set up on that computer.

1. Install Nightly. The installer selects and verifies the complete package for your platform:

   curl -fsSL https://raw.githubusercontent.com/leaperone/vibeface/main/install.sh | bash -s -- --channel nightly --install-root "$HOME/.local/share/vibeface" --bin-dir "$HOME/.local/bin"
   export PATH="$HOME/.local/bin:$PATH"
   vibeface --version

2. Run the Node, the service that connects this computer to Vibeface:

   vibeface

3. Open http://localhost:4790 in the browser on that computer.

4. Create your personal network. Download the recovery file and keep its password somewhere safe.

5. Choose an Agent in the computer's AI settings, complete its login, and check availability. A login from your usual terminal may not apply to Vibeface's private directory.

6. Create a bot and send a message. To work on a project, enable task execution and add the project folder in the AI settings.

The default data directory is ~/.vibeface. The first run initializes only a missing or empty directory. See the quick start for the full walkthrough.

Add ~/.local/bin to your shell configuration to use vibeface in new terminals. For an existing installation, use vibeface update for updates and vibeface service to manage the background service. Do not run the installer again. See installation and updates for update configuration and other installation options.

With Node.js 22 or newer, you can also install the CLI from npm with npm install -g @leaperone/vibeface@nightly. npm manages updates for that installation.

Add another device

Create a join link in Add device on a device that manages your network. Open it in another browser or the phone app. For another computer, run:

vibeface join '<join link>' --name '<device name>'

Compare the six-digit code on both devices before approving. Join the existing network instead of creating a new one. Read first-time setup for joining and recovery.

Public discovery service

The default public discovery service provides address hints, signed connection entries, and short-lived Relay admission:

vibeface://82169062e48d543dc9af8e02340c5248d6fcbe43fceb7d593ab069e7e483c235@discovery.vibeface.dev:4792

New personal Nodes connect by default to obtain address hints, a signed catalogue of public entries and relays, and short-lived admission grants. Mobile and browser clients use the same discovery service through HTTPS, while LAN connections remain preferred. Discovery does not relay application data; the public entry forwards ciphertext, without distributing its operator token. Use --bootstrap off during first initialization to disable public bootstrap, or configure a self-hosted service. See Use the public discovery service for configuration, visible metadata, and connection limits. Joining a personal network still requires an invitation and approval.

Privacy and permissions

• You approve each device that joins your private network. Only add devices you trust.
• Connections are encrypted. A public entry point forwards encrypted traffic without becoming a member of your network.
• Configured credentials stay on the computer. A secret sent in chat becomes part of the shared conversation.
• Approved computers and your chosen model service process task content. Connection encryption does not encrypt files on disk.
• Agents can run commands and change files. Project folder settings are not an operating system sandbox.
• If a task result is unknown, check the original task before sending it again. Syncing history never starts old tasks.

Read the privacy and security guide before enabling access to your projects.

Documentation

Detailed guides are currently in Chinese.

Guide	Use it to
Quick start	Install Vibeface and finish the first conversation.
User guide	Manage bots, tasks, notifications, and computers.
Product overview	Understand what Vibeface does and its limits.
Agent support	Set up coordination and task execution.
History sync	See what syncs and how to continue on another computer.
Installation and updates	Manage packages, background services, and updates.
Troubleshooting	Diagnose connection and task problems.
Node reference	Configure connections, Agents, and recovery.
CI	Find the checks for a change.

File delivery is experimental and off by default. Paid delivery uses a local test chain, with no real assets.

Build from source

You need Rust 1.91+, Node.js 22.12+, pnpm 11.9.0, and wasm-bindgen-cli 0.2.129.

rustup target add wasm32-unknown-unknown
bash scripts/build-web-crypto.sh
bash scripts/build-web.sh
cargo build --release -p vibeface -p vibeface-core --locked
bash scripts/package-node.sh

The platform package is written to .artifacts/packages/. See source setup for running it and release instructions for packaging details.

Repository layout

.
├── apps/
│   ├── app/         # Web app
│   ├── cli/         # Command line
│   ├── core/        # Node service
│   ├── mobile/      # iOS and Android apps
│   └── www/         # Public website
├── crates/          # Shared Rust libraries
├── packages/
│   ├── client/      # Shared app client
│   ├── docs/        # User and developer guides
│   └── theme/       # Shared styles
├── contracts/       # Experimental file delivery contracts
├── scripts/         # Build, package, and verification tools
├── tests/           # Fixtures and end-to-end tests
└── install.sh       # Package installer

Contribute

Open an Issue with your platform, vibeface --version, and the relevant vibeface status output. Remove credentials and personal data before sharing logs.

For a pull request, start from main, use a separate branch, and run the checks that match your changes. See CI for the required checks.

License

This repository does not include a LICENSE file yet. Until a license is published, all rights are reserved.