@burdenoff/vibe-agent

Remote development environment management CLI with terminal multiplexing, SSH tunneling, port forwarding, cloudflared integration, and a plugin system.

VibeControls Agent runs as a lightweight local service on your development machine, providing a unified REST API and CLI for managing tmux sessions, SSH connections, cloudflared tunnels, port forwards, background tasks, and more.

Installation

npm install -g @burdenoff/vibe-agent

Requires Bun >= 1.3.

Quick Start

# Start the agent as a background daemon (default)
vibe start

# Or start in foreground for debugging
vibe start --foreground

# Verify it's running
vibe health
vibe status

On first run, the agent automatically:

1. Detects missing system dependencies (tmux, ttyd, cloudflared)
2. Installs them via vibe setup
3. Detects port conflicts and auto-selects the next available port

Configuration

Create a .env file in your working directory or set environment variables:

| Variable | Description | Default | | --------------- | ----------------------------- | ------------------------- | | PORT | Agent server port | 3005 | | NODE_ENV | Environment | development | | CORS_ORIGIN | Allowed CORS origin | http://localhost:3000 | | AGENT_API_KEY | Static API key (optional) | (auto-generated) | | DB_PATH | SQLite database path | ./vibecontrols-agent.db | | AGENT_TUNNEL | Auto-start cloudflared tunnel | true |

Static API Key

By default, the agent generates a new API key on each restart. To persist one:

# Auto-generate and save a persistent key
vibe config --set static-api-key=true

# Or set an explicit key
vibe config --set static-api-key=my-secret-key-here

The key is stored in ~/.vibecontrols/config.json.

An .env.example file is included in the package for reference.

Command Reference

Core Commands

vibe start                      # Start as daemon (default)
vibe start --foreground         # Start in foreground
vibe start -p 4000              # Start on custom port
vibe start -n myagent           # Start with instance name
vibe start --db-path ~/my.db    # Custom database path

vibe stop                       # Stop default instance
vibe stop -n myagent            # Stop named instance
vibe stop --all                 # Stop all instances

vibe restart                    # Restart default instance
vibe restart -n myagent         # Restart named instance

vibe status                     # Show all instance statuses
vibe status -n myagent          # Show specific instance status

vibe list                       # List all instances
vibe kill                       # Force kill default instance
vibe kill --all                 # Force kill all

vibe logs                       # Show logs (default instance)
vibe logs -f                    # Follow logs (tail -f)
vibe logs --tail 50             # Last 50 lines

vibe health                     # Health check via HTTP
vibe info                       # Detailed version/system info
vibe key                        # Display the agent API key
vibe system                     # System info from running agent

vibe update                     # Update to latest version
vibe update --check             # Check for updates without installing

Setup & Configuration

vibe setup                      # Install dependencies (tmux, ttyd, cloudflared)
vibe setup --check              # Check without installing

vibe config --list              # List all config values
vibe config --get <key>         # Get a specific config value
vibe config --set key=value     # Set a config value

Plugin Management

Extend the agent with plugins that add CLI commands, routes, or both.

vibe plugin list                                # List installed plugins
vibe plugin install @burdenoff/vibe-plugin-ssh   # Install a plugin
vibe plugin install @burdenoff/vibe-plugin-ai    # Install AI tools plugin
vibe plugin remove @burdenoff/vibe-plugin-ssh    # Remove a plugin
vibe plugin create my-plugin                     # Scaffold a new plugin
vibe plugin create my-plugin --with-ui           # Scaffold with React UI
vibe plugin create my-plugin --tag provider      # Set plugin tag

Available Plugins:

| Plugin | Description | | ------------------------------------------ | ----------------------------------------------------- | | @burdenoff/vibe-plugin-ssh | SSH connections & port forwarding | | @burdenoff/vibe-plugin-ai | AI tool detection & prompt management (SQLite + REST) | | @burdenoff/vibe-plugin-session-tmux | tmux-based session provider | | @burdenoff/vibe-plugin-tunnel-cloudflare | Cloudflare tunnel provider | | @burdenoff/vibe-plugin-ui-ssh | Web UI for SSH management | | @burdenoff/vibe-plugin-ui-ai | Web UI for AI tools & prompt templates |

Tunnel Management

Manage cloudflared tunnels that expose local ports via public URLs.

# Per-port tunnels
vibe tunnel list                # List all tunnels
vibe tunnel status              # Overview (total, active, inactive, errored)
vibe tunnel start -p 8080       # Expose local port 8080
vibe tunnel start -p 3000 -s myapp  # With preferred subdomain
vibe tunnel stop -i <id>        # Stop a tunnel
vibe tunnel delete -i <id>      # Delete a tunnel

# Agent tunnel (main agent cloudflared tunnel)
vibe tunnel agent               # Show agent tunnel status
vibe tunnel agent --start       # Start agent tunnel
vibe tunnel agent --stop        # Stop agent tunnel

Terminal Sessions (tmux)

vibe session list               # List managed sessions
vibe session list --system      # Include unmanaged tmux sessions

vibe session create --name dev  # Create session named "dev"
vibe session create --name dev --cwd ~/project --command "npm run dev"

vibe session kill -i <id>       # Kill a session
vibe session exec -i <id> -c "ls -la"   # Run command in session
vibe session capture -i <id>    # Capture session output

SSH Connections

vibe ssh list                   # List saved connections

vibe ssh add --name prod \
  --host 10.0.1.50 \
  --user deploy \
  --port 22 \
  --key ~/.ssh/id_rsa           # Add a connection

vibe ssh remove -i <id>         # Remove a connection
vibe ssh test -i <id>           # Test connectivity
vibe ssh exec -i <id> -c "uptime"  # Execute remote command

Port Forwarding

vibe forward list               # List all forwards

vibe forward create \
  --local 5432 \
  --remote-host db.internal \
  --remote-port 5432 \
  --server prod                 # Create a forward rule

vibe forward start -i <id>     # Start forwarding
vibe forward stop -i <id>      # Stop forwarding
vibe forward delete -i <id>    # Delete forward rule

Background Tasks

vibe task list                  # List all tasks
vibe task list --status running # Filter by status
vibe task run -c "npm test"    # Run command as background task
vibe task run -c "make build" --cwd ~/project

Notifications

vibe notify list                # List all notifications
vibe notify list --unread       # Show only unread
vibe notify read-all            # Mark all as read

Global Options

Every subcommand that communicates with a running agent accepts:

--agent-url <url>   # Default: http://localhost:3005

This lets you manage remote agents or agents on non-default ports:

vibe health --agent-url http://192.168.1.10:3005
vibe tunnel list --agent-url http://localhost:4000

Architecture

The agent runs as a Bun + Elysia HTTP server with:

• bun:sqlite database for local state (sessions, connections, tunnels, tasks, config)
• tmux integration for terminal multiplexing
• cloudflared for secure tunnel management
• Plugin system for extensibility (SSH, AI tools, UI plugins, and custom plugins)
• WebSocket proxy for real-time terminal streaming
• API key authentication on all endpoints
• Daemon mode by default with proper process management

System Dependencies

| Tool | Purpose | Required | | ----------- | --------------------- | ----------- | | Bun >= 1.3 | Runtime | Yes | | tmux | Terminal multiplexing | Yes | | ttyd | Web-based terminal | Recommended | | cloudflared | Tunnel management | For tunnels |

Run vibe setup --check to verify all dependencies.

REST API

When the agent is running, it exposes a REST API at http://localhost:3005/api/ with 112 endpoints across these route groups:

• /api/tmux/* - Terminal session management
• /api/ssh/* - SSH connection management
• /api/tunnel/* - Per-port tunnel CRUD
• /api/agent-tunnel/* - Agent tunnel management
• /api/port-forward/* - Port forwarding
• /api/tasks/* - Background task management
• /api/config/* - Configuration & system info
• /api/notifications/* - Notification management
• /api/files/* - File operations
• /api/git/* - Git repository scanning
• /api/bookmarks/* - Command bookmarks
• /api/projects/* - Project scanning
• /api/ai/tools - AI tool detection
• /api/ai/prompts/* - Prompt template CRUD (via AI plugin)

Authentication: Include x-agent-api-key header with your API key.

Examples

Development Workflow

# Start agent (daemon mode is the default)
vibe start

# Set up a dev session
vibe session create --name frontend --cwd ~/app --command "npm run dev"
vibe session create --name backend --cwd ~/api --command "npm start"

# Expose your dev server publicly
vibe tunnel start -p 3000

# Check everything is running
vibe session list
vibe tunnel list
vibe health

# Later, clean up
vibe stop

Remote Server Management

# Save SSH connections
vibe ssh add --name staging --host staging.example.com --user deploy --key ~/.ssh/deploy
vibe ssh add --name production --host prod.example.com --user deploy --key ~/.ssh/deploy

# Test connections
vibe ssh test -i <staging-id>

# Run remote commands
vibe ssh exec -i <staging-id> -c "docker ps"
vibe ssh exec -i <production-id> -c "systemctl status nginx"

# Set up port forwarding to access remote databases
vibe forward create --local 5432 --remote-host localhost --remote-port 5432 --server staging
vibe forward start -i <forward-id>

Part of the VibeControls Ecosystem

This agent is the local component of the VibeControls development environment platform. It can operate standalone or connect to the VibeControls backend for centralized management across multiple machines.

Author

Vignesh T.V. (@tvvignesh) [email protected]

License

Proprietary - Copyright 2025-2026 Burdenoff Consultancy Services Pvt. Ltd. All rights reserved.

See LICENSE for details.