Outposts

Outposts are lightweight agents that execute tools in your environment. They provide secure, firewall-friendly connectivity between Hublvu and your infrastructure.

Overview

Hublvu Outpost runs within your network and executes MCP tools locally. It establishes a secure, outbound-only connection to the Hublvu cloud platform, eliminating the need for inbound firewall rules.

Key Features

• Outbound-only connections — No inbound firewall rules required
• Single binary — Lightweight Go executable with minimal dependencies
• MCP server management — Manages MCP tool servers as subprocesses
• Secure communication — JWT authentication and mTLS
• Auto-reconnection — Resilient connection handling with exponential backoff
• Non-root operation — Runs as a dedicated hublvu system user

Architecture

How it works:

1. Outpost establishes an outbound gRPC connection to Hublvu's tool-grid
2. Tool-grid sends commands to Outpost over this connection
3. Outpost executes commands via local MCP servers
4. Results are sent back through the same connection

Before You Start

Your Hublvu administrator will provide:

Item	Used For	Example
Username	Downloading packages from repository	customer
API Key	Downloading packages from repository	wBIQYo1g...
Tool-Grid Endpoint	Outpost connection to Hublvu	IP:PORT
JWT Token	Outpost authentication with tool-grid	g0lOXcq...
TLS Certificates	Secure communication	ca.crt, client.crt, client.key

note

Username/API Key are for the package repository. JWT Token is for outpost runtime authentication — these are different credentials.

JWT tokens are typically valid for 1 year. Your Hublvu administrator will notify you when a new token is needed.

System Requirements

Component	Requirement
OS	Oracle Linux 8/9, RHEL 8/9, Ubuntu 20.04+, Debian 11+
RAM	256 MB minimum
CPU	1 core
Disk	500 MB
Network	Outbound access to releases.hublvu.ai:443 and tool-grid endpoint

Installation

One-Line Install (Recommended)

curl -fsSL https://releases.hublvu.ai/install.sh | sudo bash -s USERNAME API_KEY

Replace USERNAME and API_KEY with credentials from your Hublvu admin. This installs the full package which includes outpost and MCP servers.

Manual Install (Oracle Linux / RHEL / Rocky / AlmaLinux)

Step 1: Create the repository file

sudo tee /etc/yum.repos.d/hublvu.repo > /dev/null <<'EOF'
[hublvu]
name=Hublvu Package Repository
baseurl=https://releases.hublvu.ai/repo/yum
enabled=1
gpgcheck=1
gpgkey=https://releases.hublvu.ai/repo/gpg
username=YOUR_USERNAME
password=YOUR_API_KEY
sslverify=1
EOF

Replace YOUR_USERNAME and YOUR_API_KEY with credentials from your Hublvu admin.

Step 2: Verify the repository

sudo dnf repolist hublvu

Step 3: Install the full package

sudo dnf install hublvu-outpost-full -y

This installs outpost and all MCP servers. The service is enabled but not started.

Alternative: Install minimal + individual MCP servers

# Install minimal outpost (no MCP servers)
sudo dnf install hublvu-outpost -y

# Install only the MCP servers you need
sudo dnf install hublvu-mcp-filesystem -y

Ubuntu / Debian

# Import GPG key
curl -fsSL https://releases.hublvu.ai/gpg \
    | sudo gpg --dearmor -o /usr/share/keyrings/hublvu-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/hublvu-archive-keyring.gpg] https://releases.hublvu.ai/repo/apt stable main" \
    | sudo tee /etc/apt/sources.list.d/hublvu.list

# Add authentication
echo "machine releases.hublvu.ai login YOUR_USERNAME password YOUR_API_KEY" \
    | sudo tee /etc/apt/auth.conf.d/hublvu.conf
sudo chmod 600 /etc/apt/auth.conf.d/hublvu.conf

# Install
sudo apt update
sudo apt install hublvu-outpost-full

Configuration

Step 1: Set the JWT Token (Required)

The JWT token authenticates outpost with the tool-grid.

sudo tee /etc/hublvu/outpost.env << 'EOF'
OUTPOST_SECURITY_JWT_TOKEN=paste-your-jwt-token-here
EOF
sudo chmod 600 /etc/hublvu/outpost.env

Step 2: Edit the Config File

sudo nano /etc/hublvu/outpost.yaml

Set these required values:

outpost:
  node_id: "your-server-name"          # REQUIRED: Unique name for this outpost

tool_grid:
  endpoint: "IP:PORT"                  # REQUIRED: Tool-grid IP and port from Hublvu admin
  insecure: true                       # Set to true for initial testing without TLS

security:
  skip_verify: true                    # Set to true for initial testing

note

Use the IP address (not DNS) for the endpoint — your server may not have DNS access to Hublvu infrastructure.

Step 3: Install TLS Certificates (Production)

For production, set insecure: false in config and install TLS certificates:

sudo mkdir -p /etc/hublvu/tls
sudo cp ca.crt client.crt client.key /etc/hublvu/tls/
sudo chmod 600 /etc/hublvu/tls/*.key
sudo chmod 644 /etc/hublvu/tls/*.crt
sudo chown hublvu:hublvu /etc/hublvu/tls/*

Then update the config:

tool_grid:
  insecure: false                      # Enable TLS

security:
  skip_verify: false                   # Verify TLS certificates
  cert_file: "/etc/hublvu/tls/client.crt"
  key_file: "/etc/hublvu/tls/client.key"
  ca_file: "/etc/hublvu/tls/ca.crt"

Running the Service

# Start
sudo systemctl start hublvu-outpost
sudo systemctl enable hublvu-outpost   # Auto-start on boot

# Stop
sudo systemctl stop hublvu-outpost

# Restart
sudo systemctl restart hublvu-outpost

# Check status
sudo systemctl status hublvu-outpost

MCP Servers

MCP (Model Context Protocol) servers provide tool capabilities. Outpost manages these as subprocesses.

Available MCP Servers

Server	Port	Description
Filesystem	11001	File and directory operations

Configuration

MCP servers are configured in outpost.yaml:

mcp_servers:
  - name: "Filesystem"
    enabled: true
    command: "/opt/hublvu/mcp-servers/filesystem"
    args: ["--transport", "http", "--port", "11001"]
    port: 11001

Checking Logs

# View recent logs
sudo journalctl -u hublvu-outpost -n 50

# Follow logs in real-time
sudo journalctl -u hublvu-outpost -f

# View log file directly
sudo tail -f /var/log/hublvu/outpost.log

# Check for errors only
sudo journalctl -u hublvu-outpost -p err -n 20

Updating

Oracle Linux / RHEL

sudo dnf update hublvu-outpost-full
sudo systemctl restart hublvu-outpost

Ubuntu / Debian

sudo apt update
sudo apt upgrade hublvu-outpost-full
sudo systemctl restart hublvu-outpost

Security

Authentication Layers

1. JWT Token — Authenticates this outpost to tool-grid
2. mTLS — Mutual TLS certificate authentication
3. Command Signing — HMAC-SHA256 signatures on commands

Firewall Configuration

Only outbound rules are needed:

# Outbound to Hublvu
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 50052 -j ACCEPT

# No inbound rules needed

Troubleshooting

Service Won't Start

Check logs for errors:

sudo journalctl -u hublvu-outpost -n 100

Common causes:

• Missing or invalid JWT token in /etc/hublvu/outpost.env
• Missing TLS certificates in /etc/hublvu/tls/
• Invalid tool_grid.endpoint in config

Connection Errors

1. Verify network connectivity:

   nc -zv <TOOL_GRID_IP> 50052

2. Check TLS certificates exist:

   ls -la /etc/hublvu/tls/

Authentication Errors

1. Verify JWT token is set:

   sudo grep JWT /etc/hublvu/outpost.env

2. Check for JWT-related errors in logs:

   sudo journalctl -u hublvu-outpost | grep -i "jwt\|auth\|token"

3. Common JWT issues:

   • "token expired" — Contact your Hublvu admin for a new token
   • "invalid signature" — Token may be corrupted; request a new one
   • "token not found" — Check /etc/hublvu/outpost.env has OUTPOST_SECURITY_JWT_TOKEN set

OTEL/Telemetry Errors in Logs

If you see errors like:

exporter export timeout: rpc error: code = Unavailable desc = connection error: dial tcp [::1]:4317

These are harmless — telemetry export is configured but no collector is running. To suppress:

telemetry:
  enabled: false

MCP Servers Not Working

Check if MCP server ports are listening:

ss -tlnp | grep 11001

Check MCP server logs:

sudo journalctl -u hublvu-outpost | grep -i mcp

Quick Reference

Task	Command
Start service	sudo systemctl start hublvu-outpost
Stop service	sudo systemctl stop hublvu-outpost
Restart service	sudo systemctl restart hublvu-outpost
Check status	sudo systemctl status hublvu-outpost
View logs	sudo journalctl -u hublvu-outpost -f
Check version	hublvu-outpost --version
Edit config	sudo nano /etc/hublvu/outpost.yaml
Update (RHEL)	sudo dnf update hublvu-outpost-full
Update (Ubuntu)	sudo apt update && sudo apt upgrade hublvu-outpost-full

File Locations

File	Purpose
/etc/hublvu/outpost.yaml	Main configuration
/etc/hublvu/outpost.env	Environment variables (JWT token)
/etc/hublvu/tls/	TLS certificates
/var/log/hublvu/outpost.log	Log file
/opt/hublvu/mcp-servers/	MCP server binaries
/usr/bin/hublvu-outpost	Outpost binary

Use Meaningful Names

Name outposts after their location or purpose: "prod-us-east", "dev-database", "network-monitoring".

Limit Tool Scope

Configure MCP servers with minimum necessary access. A read-only database connection is safer than full admin.

Monitor Availability

Set up alerts for outpost disconnection. Offline outposts can't execute automation.

Uninstalling

Oracle Linux / RHEL

sudo systemctl stop hublvu-outpost 2>/dev/null
sudo dnf remove hublvu-outpost-full hublvu-mcp-filesystem -y
sudo rm -rf /etc/hublvu /var/log/hublvu /opt/hublvu
sudo rm -f /etc/yum.repos.d/hublvu.repo

Ubuntu / Debian

sudo systemctl stop hublvu-outpost 2>/dev/null
sudo apt remove --purge hublvu-outpost-full hublvu-mcp-filesystem -y
sudo rm -rf /etc/hublvu /var/log/hublvu /opt/hublvu
sudo rm -f /etc/apt/sources.list.d/hublvu.list
sudo rm -f /etc/apt/auth.conf.d/hublvu.conf
sudo rm -f /usr/share/keyrings/hublvu-archive-keyring.gpg

Related Topics

• Integrations Overview — Integration architecture
• External Systems — Third-party integrations
• Agents — Configure agent tool access