Skip to main content

Managing AI Agents

An agent is the heart of VibeControls. It is a small runtime that you install on a machine — your laptop, a cloud VM, a build server — and once it is running it lets VibeControls start sessions, probe health, manage tunnels, and run AI workflows on that machine.

Installing the CLI Agent​

The VibeControls CLI is the easiest way to install and start an agent.

Install the CLI​

Download and install the VibeControls CLI from the VibeControls website or follow the quick-start instructions in the Getting Started guide inside the app.

# Install via the install script
curl -fsSL https://vibecontrols.com/install.sh | sh

# Or — for security-conscious environments — download and inspect first
curl -fsSL https://vibecontrols.com/install.sh -o install.sh
less install.sh
sh install.sh

# Or install via npm/bun
bun add -g @vibecontrols/cli

Register and Start the Agent​

Once the CLI is installed, authenticate and start your agent:

# Log in to your workspace
vibecontrols auth login

# Start the agent on this machine
vibe start

The agent will register itself with your workspace and appear under Agents in the VibeControls UI within a few seconds.

You can also run the agent as a background service so it starts automatically on boot:

vibe autostart install

The Agents List​

Navigate to Agents in the sidebar to see every agent registered in your workspace.

The list shows:

  • Agent name — the hostname or custom label you assigned
  • Status — online, offline, or unreachable
  • Last seen — timestamp of the most recent health check
  • Target — the machine this agent is running on
  • Sessions — how many active sessions are running on this agent

Click any agent row to open its detail page.

Agent Detail Page​

The agent detail page is your command center for a single machine.

Health​

The Health tab shows the current connectivity status of the agent. VibeControls runs regular probes to confirm the agent is reachable. You will see:

  • Current health status (healthy, degraded, unreachable)
  • Uptime since last start
  • Recent health check history as a timeline
  • Any error messages from failed probes

If an agent goes offline, a banner will appear prompting you to investigate or restart it.

Sessions Tab​

Lists all sessions associated with this agent. From here you can start a new session, view active ones, or open a past session's log. See the Sessions guide for full details.

Plugins Tab​

Shows all plugins installed on this agent. Plugins extend what the agent can do — adding session providers (tmux, WezTerm, Zellij), tunnel providers, SSH capabilities, AI provider integrations, and more. You can install or remove plugins from this tab.

Settings Tab​

Lets you update the agent's display name, description, and any agent-scoped configuration values. See Configurations for details on configuration scopes.

Agent Graph View​

The Agent Graph gives you a visual topology of your entire machine network.

Access it from Agents → Graph (or click the "Graph" tab in the Agents view).

The graph shows:

  • All registered agents as nodes
  • The targets they are connected to
  • Connection paths between agents and targets
  • Health status indicated by node color (green = healthy, yellow = degraded, red = offline)

Hover over any node for a quick summary. Click a node to jump to that agent or target's detail page.

The Agent Graph is especially useful when you have multiple machines that interact with each other — for example, an agent on a build server that connects to remote deploy targets.

Agent Settings​

To update global settings for an agent:

  1. Open the agent detail page
  2. Click the Settings tab
  3. Edit the name, description, or notes
  4. Add or modify agent-scoped configuration values
  5. Click Save

You can also delete an agent from its settings page. Deleting an agent removes it from the workspace but does not uninstall the software from the machine itself. To fully remove the agent runtime from the machine, run:

vibe autostart uninstall && npm uninstall -g @vibecontrols/agent

Multiple Agents on One Machine​

You can run multiple agent instances on a single machine — for example, one per project or one per user. Each instance gets its own isolated state directory and registers as a separate agent in the workspace.

To start a second instance with a different name:

vibe start --name "project-b-agent"

Troubleshooting​

  • Agent shows as offline: Check that the agent process is still running on the machine (vibe status). Restart with vibe restart.
  • Agent never appeared in the UI: Confirm you are logged into the correct workspace in the CLI (vibecontrols workspace list).
  • Health checks failing: Check that the machine has outbound internet access and that no firewall rules are blocking the agent's connection.