Skip to main content

Installing the Agent

The agent is the @vibecontrols/agent runtime. It runs on the machine where your code lives. It works on macOS, Linux, Windows, and WSL2.

What you'll learn​

  • Install (curl script — recommended — or a package manager)
  • First-run setup
  • Daemonize it
  • Verify the install

The fastest way to install on any OS is the install script. It installs the vibe binary on your PATH and pulls in what it needs:

curl -fsSL https://app.vibecontrols.com/install | bash

Prefer to read what you're running first? Download, inspect, then run:

curl -fsSL https://app.vibecontrols.com/install -o install.sh && less install.sh && bash install.sh

If vibe isn't found immediately after install, refresh your shell so the new PATH entry is picked up (or open a new terminal):

hash -r 2>/dev/null

Alternatives (package managers)​

If you already have Node/Bun and prefer a package manager, install globally instead:

npm install -g @vibecontrols/agent
# or
bun install -g @vibecontrols/agent

This installs the vibe binary on your PATH.

Install (local per-folder)​

Useful if you want different agent versions per project:

mkdir my-vibe && cd my-vibe
npm install @vibecontrols/agent
export VIBECONTROLS_PLUGIN_INSTALL_MODE=local
./node_modules/.bin/vibe start

First-run setup​

vibe start

On first run the agent:

  1. Auto-detects missing system dependencies (tmux, ttyd, cloudflared) and offers to install them via:
  vibe setup
  1. Picks a port — defaults to 3005, falls back to the next free port if 3005 is in use. Override with PORT=<n> or -p <n>.
  2. Stands up a Cloudflare tunnel so the backend can reach it without you opening firewall holes.
  3. Generates an agentApiKey and stores it locally.
  4. Stores per-agent config at ~/.boff/vibecontrols/agents/<agentId>/config.json and per-agent data in ~/.boff/vibecontrols/agents/<agentId>/agent.db (encrypted SQLite).
  5. Stores profile config at ~/.boff/vibecontrols/profiles/<profile>.json (the "default" profile uses production URLs).

The agent waits in pre-config mode until the platform pushes OAuth credentials via POST /api/agent/gateway-auth — that happens automatically when you add the target in the web app.

Daemonize it​

Once you have vibe start working in the foreground, daemonize it so it survives logout:

vibe autostart install

Behavior per OS:

OSMechanismWhere
Linux (incl. WSL2)systemd user service~/.config/systemd/user/vibe.service — requires loginctl enable-linger <user>
macOSlaunchd plist~/Library/LaunchAgents/com.vibecontrols.agent.plist
Windows 10/11Task Schedulerper-user entry, logon trigger, 3 retries on failure

Reverse it:

vibe autostart uninstall

Verify​

vibe health           # HTTP health check at localhost:3005/health
vibe status           # show all instance statuses
vibecontrols agents list --active  # see your agent on the backend

Multiple profiles on one machine​

You can run multiple agent instances side-by-side (e.g., one against prod, one against alpha):

vibe start --profile alpha       # connects to alpha backend
vibe start --profile default     # connects to prod backend

Each profile gets its own port and its own data dir under ~/.boff/vibecontrols/profiles/<name>/.

Uninstall​

vibe autostart uninstall
npm uninstall -g @vibecontrols/agent
rm -rf ~/.boff/vibecontrols

Next steps​