@burdenoff/vibe-agent 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+PORT=3005
+NODE_ENV=development
+CORS_ORIGIN="http://localhost:3000"
+AGENT_API_KEY="vibecontrols-agent-secret-key"
+DB_PATH="./vibecontrols-agent.db"
+
+# Set to 'false' to disable auto-starting the cloudflared tunnel on boot
+# AGENT_TUNNEL=false

package/LICENSE

@@ -0,0 +1,22 @@
+Proprietary License
+
+Copyright (c) 2025-2026 Burdenoff Consultancy Services Pvt. Ltd. All rights reserved.
+
+This software and associated documentation files (the "Software") are the proprietary
+property of Burdenoff Consultancy Services Pvt. Ltd. and its affiliates.
+
+UNAUTHORIZED COPYING, MODIFICATION, DISTRIBUTION, OR USE OF THIS SOFTWARE, VIA ANY
+MEDIUM, IS STRICTLY PROHIBITED.
+
+The Software is provided under a proprietary license. You may use the Software only in
+accordance with the terms of your license agreement with Burdenoff Consultancy Services
+Pvt. Ltd.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, contact: contact@vibecontrols.com

package/README.md

@@ -0,0 +1,290 @@
+# @burdenoff/vibe-agent
+
+Remote development environment management CLI with terminal multiplexing, SSH tunneling, port forwarding, and cloudflared integration.
+
+**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
+
+```bash
+npm install -g @burdenoff/vibe-agent
+```
+
+Requires **Node.js >= 18**.
+
+## Quick Start
+
+```bash
+# 1. Check system dependencies
+vibe setup --check
+
+# 2. Install missing dependencies (tmux, ttyd, cloudflared)
+vibe setup
+
+# 3. Start the agent (foreground)
+vibe start
+
+# 4. Or start as a background daemon
+vibe start -d
+
+# 5. Verify it's running
+vibe health
+vibe status
+```
+
+## 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` | API key for authentication | (auto-generated) |
+| `DB_PATH` | SQLite database path | `./vibecontrols-agent.db` |
+| `AGENT_TUNNEL` | Auto-start cloudflared tunnel | `true` |
+
+An `.env.example` file is included in the package for reference.
+
+## Command Reference
+
+### Core Commands
+
+```bash
+vibe start                      # Start agent (foreground)
+vibe start -d                   # Start as daemon
+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
+```
+
+### Setup & Configuration
+
+```bash
+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
+```
+
+### Tunnel Management
+
+Manage cloudflared tunnels that expose local ports via public URLs.
+
+```bash
+# 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)
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+--agent-url <url>   # Default: http://localhost:3005
+```
+
+This lets you manage remote agents or agents on non-default ports:
+
+```bash
+vibe health --agent-url http://192.168.1.10:3005
+vibe tunnel list --agent-url http://localhost:4000
+```
+
+## Architecture
+
+The agent runs as a Fastify HTTP server with:
+
+- **SQLite** database for local state (sessions, connections, tunnels, tasks, config)
+- **tmux** integration for terminal multiplexing
+- **cloudflared** for secure tunnel management
+- **ssh2** for SSH connection management
+- **WebSocket** proxy for real-time terminal streaming
+- **API key** authentication on all endpoints
+
+### System Dependencies
+
+| Tool | Purpose | Required |
+|------|---------|----------|
+| tmux | Terminal multiplexing | Yes |
+| ttyd | Web-based terminal | Recommended |
+| cloudflared | Tunnel management | For tunnels |
+| Node.js 18+ | Runtime | Yes |
+
+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
+
+Authentication: Include `x-agent-api-key` header with your API key.
+
+## Examples
+
+### Development Workflow
+
+```bash
+# Start agent in the background
+vibe start -d
+
+# 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
+
+```bash
+# 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](https://vibecontrols.com) development environment platform. It can operate standalone or connect to the VibeControls backend for centralized management across multiple machines.
+
+## Author
+
+**Vignesh T.V.** ([@tvvignesh](https://github.com/tvvignesh))
+[vignesh@burdenoff.com](mailto:vignesh@burdenoff.com)
+
+## License
+
+Proprietary - Copyright 2025-2026 Burdenoff Consultancy Services Pvt. Ltd. All rights reserved.
+
+See [LICENSE](./LICENSE) for details.

package/dist/app.d.ts

@@ -0,0 +1,15 @@
+import Fastify from 'fastify';
+import { Server as SocketIOServer } from 'socket.io';
+import AgentDatabase from './db/schema.js';
+/**
+ * Get the current agent API key.
+ */
+export declare function getAgentApiKey(): string;
+export declare function startServer(): Promise<Fastify.FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, Fastify.FastifyBaseLogger, Fastify.FastifyTypeProviderDefault>>;
+declare module 'fastify' {
+    interface FastifyInstance {
+        db: AgentDatabase;
+        io: SocketIOServer;
+    }
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAK9B,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,aAAa,MAAM,gBAAgB,CAAC;AA+B3C;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAWD,wBAAsB,WAAW,uSA4bhC;AAGD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,EAAE,EAAE,aAAa,CAAC;QAClB,EAAE,EAAE,cAAc,CAAC;KACpB;CACF"}