Skip to main content

Getting Started

You'll have a working agent and your first vibe in five minutes.

What you'll learn​

  • Install the agent and CLI
  • Sign in
  • Create your first vibe
  • Open a session inside it

1. Install​

Vibecontrols ships two binaries:

PackageBinaryPurpose
@vibecontrols/agentvibeThe agent runtime — runs on the machine where your code lives
@vibecontrols/clivibecontrolsThe CLI you use to manage everything

Install both globally:

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

2. Sign in​

vibecontrols auth login

This opens a browser via OAuth2 device-code flow. After you authorize, the CLI stores your token at ~/.config/vibecontrols-cli/auth.json (mode 0600). Platform tokens auto-refresh (1h lifetime); workspace tokens auto-refresh (15min lifetime).

Confirm with:

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

→ Deep dive: Account & Sign-in

3. 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)
  3. Stands up an outbound Cloudflare tunnel so the platform can reach it
  4. Stores config under ~/.boff/vibecontrols/profiles/ and per-agent data under ~/.boff/vibecontrols/agents/<id>/

Background it as a daemon:

vibe autostart install   # systemd (Linux/WSL), launchd (macOS), Task Scheduler (Windows)

→ Deep dive: Installing the Agent

4. Create your first vibe​

vibecontrols vibes create \
  --name my-api \
  --path /home/me/code/my-api \
  --type REPOSITORY

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

List your vibes:

vibecontrols vibes list

5. 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 tunnel) for sharing.

Next steps​