Skip to main content

Getting Started with Vibecontrols

This guide walks you through setting up Vibecontrols from scratch — from installing the binaries on your machine to running your first session.

The whole process takes about five minutes.

Two binaries​

Vibecontrols ships two separate binaries distributed as npm packages:

PackageBinaryPurpose
@vibecontrols/agentvibeThe agent runtime — runs on each machine where you want to host sessions, tunnels, AI workflows
@vibecontrols/clivibecontrolsThe CLI for managing everything from the backend side (vibes, sessions, vibedecks, webhooks, etc.)

You install both.

Step 1: Sign in to the web app​

  1. Go to app.vibecontrols.com and sign in (Burdenoff Workspaces identity).
  2. If you don't have an account, click Register to start.
  3. Pick or create a workspace.

Step 2: Install the CLI + agent​

On the machine where your code lives:

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

Verify:

vibe --version
vibecontrols --version

Step 3: Authenticate the CLI​

vibecontrols auth login

OAuth2 device-code flow opens a browser. After you authorize:

vibecontrols auth status
vibecontrols workspace list
vibecontrols workspace set <workspace-id>

CLI tokens are stored at ~/.config/vibecontrols-cli/auth.json (mode 0600). Platform tokens auto-refresh every ~1 hour; workspace tokens every ~15 minutes.

Step 4: Start the agent​

vibe start

On first run, the agent:

  1. Detects missing system dependencies (tmux, ttyd, cloudflared) and offers to install them via vibe setup.
  2. Picks port 3005 (or the next free port if 3005 is taken).
  3. Stands up an outbound Cloudflare tunnel so the backend can reach it.
  4. Generates an agentApiKey and stores it locally.
  5. Persists data under ~/.boff/vibecontrols/agents/<agentId>/ (encrypted SQLite) and per-profile config under ~/.boff/vibecontrols/profiles/<profile>.json.

Background it as a daemon so it survives logout:

vibe autostart install

This registers a systemd user service (Linux/WSL), launchd plist (macOS), or Task Scheduler entry (Windows). On Linux you may need loginctl enable-linger <user> first.

Step 5: Register the target in the web app​

Navigate to Targets → Add Target in the web app. The platform pushes OAuth credentials to your running agent via POST /api/agent/gateway-auth, after which the agent finalizes (fetches the per-workspace encryption key, loads plugins) and appears in your Agents list with Active status.

Step 6: Create your first vibe​

vibecontrols vibes create \
  --name my-api \
  --path /home/me/code/my-api \
  --type REPOSITORY \
  --description "My REST API project"

Vibe types: PROJECT, WORKSPACE, REPOSITORY, MONOREPO, PACKAGE, CUSTOM.

List your vibes:

vibecontrols vibes list

Step 7: Open a session inside the vibe​

vibecontrols sessions create \
  --name dev \
  --vibe-id <vibe-id> \
  --agent <agent-id> \
  --type TMUX

Session types: TMUX, WEZTERM, ZELLIJ, SSH, TERMINAL, SCRIPT, CUSTOM. The session gets a browser-accessible URL (via ttyd, exposed through the agent's outbound tunnel) for in-browser attach + sharing.

Verify everything works​

vibe health                     # local agent health probe
vibecontrols agents list --active
vibecontrols sessions list --status RUNNING

What's next​

  • Working with Vibes — full CRUD, env vars, git metadata, hierarchy
  • Sessions & Terminals — all seven session types, attach, share, send commands
  • VibeDecks — build a Stream-Deck-style grid of action buttons
  • AI Prompts — define reusable prompts and dispatch them
  • Tunnels — expose ports via Cloudflare quick tunnels or VibeTunnels (frp)