VPS Agent

The Rakiba agent is a lightweight service that runs on your VPS servers, enabling remote project management, log streaming, and zero-downtime deployments from your local admin dashboard.

Overview

The Rakiba Agent is a minimal service that runs on your VPS servers, enabling your local admin dashboard to manage remote projects. It’s designed with security and simplicity in mind:

Architecture

YOUR MACHINE                              VPS SERVER
+------------------+                      +------------------+
|                  |                      |                  |
|  bb admin        |     SSH Tunnel       |  rakiba-agent    |
|  (full UI)       |=====================>|  (headless)      |
|  localhost:4000  |  localhost:18001     |  localhost:18000 |
|                  |         |            |                  |
|  +------------+  |         |            |  +------------+  |
|  | tunnel.clj |--+---------+            |  | WebSocket  |  |
|  +------------+  |                      |  | Handler    |  |
|                  |    WebSocket         |  +------------+  |
|  +------------+  |                      |        |         |
|  | agent_     |<----------------------->|  +------------+  |
|  | client.clj |  |                      |  | systemd    |  |
|  +------------+  |                      |  | control    |  |
|                  |                      |  +------------+  |
+------------------+                      |        |         |
                                          |  +------------+  |
                                          |  | your apps  |  |
                                          |  +------------+  |
                                          +------------------+

Key insight: The agent has no web UI and no authentication system. Security comes from SSH - if you can SSH to the server, you can control the agent. This is simpler and more secure than managing separate credentials.

Quick Start

1. Add VPS to Inventory

First, register your VPS (if you haven’t already):

bb vps:add root@192.168.1.100 --name prod

2. Setup Agent on VPS

Install the agent on your VPS:

bb vps:setup prod

This command:

1. Uploads the rakiba-agent binary to /usr/local/bin/
2. Creates a systemd service (rakiba-agent.service)
3. Starts the agent listening on localhost:18000
4. Enables auto-start on boot

3. Connect from Dashboard

Start your local admin dashboard:

bb admin

The dashboard automatically establishes SSH tunnels to configured VPS targets. You’ll see your remote servers in the VPS section.

Agent Commands

The agent responds to WebSocket commands from your local dashboard:

Project Management

Log Streaming

Health & Metrics

Managed Services

Deployment

SSH Tunnel Security

The agent only listens on localhost:18000. It’s not accessible from the network. Access requires:

1. SSH key access to the VPS
2. SSH tunnel forwarding a local port to the agent

This is handled automatically by the dashboard, but you can also do it manually:

# Manual tunnel (for debugging)
ssh -N -L 18001:localhost:18000 user@your-vps

# Now connect to localhost:18001 to reach the agent

Why This Approach?

Connecting to Multiple VPS

Each VPS gets its own SSH tunnel on a unique local port:

The dashboard manages these tunnels automatically. You can see tunnel status in the VPS section.

Managing Remote Projects

View Projects

The dashboard shows all projects deployed to the VPS:

Start/Stop/Restart

Select a project and use the action buttons (or keyboard shortcuts in TUI):

View Logs

Click Logs to stream logs in real-time. This runs:

journalctl -u rakiba-<project> -f

The logs are streamed over WebSocket back to your browser.

Deploying via Agent

When you run bb deploy, the deployment now goes through the agent:

bb deploy my-app --target prod

Deployment Flow

1. Build - bb build creates uberjar locally
2. Upload - JAR sent to agent via WebSocket
3. Stage - Agent saves JAR to staging directory
4. Activate - Agent performs blue/green swap
5. Health Check - Agent verifies new version is healthy
6. Complete - Old version stopped, traffic on new version

Benefits Over Direct SSH

Managing VPS Services

The agent can control managed services on the VPS:

PostgreSQL

Dashboard → Agent → systemctl restart postgresql

Valkey (Redis)

Dashboard → Agent → systemctl restart valkey

Garage S3

Dashboard → Agent → docker-compose restart garage

Viewing Service Status

The Services panel shows:

Agent Systemd Service

The agent runs as a systemd service:

# /etc/systemd/system/rakiba-agent.service
[Unit]
Description=Rakiba Agent
After=network.target

[Service]
Type=simple
User=rakiba
ExecStart=/usr/local/bin/rakiba-agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Manual Control

# On the VPS
sudo systemctl status rakiba-agent
sudo systemctl restart rakiba-agent
sudo journalctl -u rakiba-agent -f

VPS Inventory

VPS targets are stored in .remote-inventory.edn:

{:targets
 [{:name "prod"
   :host "192.168.1.100"
   :user "root"
   :port 22
   :key "~/.ssh/id_rsa"}
  {:name "staging"
   :host "192.168.1.101"
   :user "deploy"
   :port 22
   :key "~/.ssh/staging_key"}]}

This file is git-ignored by default - each developer maintains their own VPS access.

Team Collaboration

For teams, each developer:

1. Gets SSH key access to the VPS
2. Runs bb vps:add to add the VPS to their local inventory
3. Uses the dashboard to manage their deployments

There’s no shared state - if you have SSH access, you can manage the server.

Troubleshooting

Agent Not Responding

# Check agent is running on VPS
ssh user@vps "systemctl status rakiba-agent"

# Check agent logs
ssh user@vps "journalctl -u rakiba-agent -n 50"

Tunnel Won’t Connect

# Test SSH connection
ssh -v user@vps "echo ok"

# Test manual tunnel
ssh -N -L 18001:localhost:18000 user@vps
# Then in another terminal:
curl http://localhost:18001/health

”Connection Refused” in Dashboard

The SSH tunnel may have dropped. The dashboard auto-reconnects, but you can force it:

1. Go to VPS section
2. Click Reconnect on the affected VPS

Agent Binary Missing

# Re-run setup
bb vps:setup prod

Permission Denied

Ensure the SSH user has:

1. Write access to /usr/local/bin/ (for agent binary)
2. Permission to manage systemd services

# Option 1: Use root
bb vps:add root@vps --name prod

# Option 2: Add deploy user to sudoers
echo "deploy ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/deploy

Command Reference

VPS Setup

VPS Management

Dashboard Integration

Related

• Deployment - Full deployment guide
• Admin Dashboard - Local dashboard documentation
• Commands Reference - All bb vps:* commands