Self-Hosted Package Installation Guide

Overview

The ManageLM installer is a single self-extracting .sh.gz file that includes the portal, agent source, and a bundled Node.js runtime. No prerequisites need to be installed on the target server — just download, extract, and run.

The installer handles both first install and upgrades. On upgrade, your configuration (.env) is preserved automatically.

Requirements

• Linux (x64 or arm64) — Debian, Ubuntu, RHEL, Rocky, AlmaLinux, etc.
• PostgreSQL 15+ — application database
• Redis 7+ (or Valkey) — sessions, pub/sub, rate limiting
• A domain name with trusted TLS for production. Agents verify the certificate chain against the host's system trust store and reject self-signed or untrusted CAs — this applies even on private networks. See Reverse Proxy for the options.
• 1 GB RAM minimum

Node.js is bundled in the installer — no system packages required beyond the database and cache.

Download

Download the latest release for your architecture from GitHub Releases.

Then extract and run:

gunzip managelm-<version>-linux-<arch>.sh.gz

Install

Run the installer as root:

sudo bash managelm-<version>-linux-<arch>.sh

The installer will prompt for:

For unattended installation, use --yes to accept all defaults:

sudo bash managelm-<version>-linux-<arch>.sh --yes

Other flags:

  --install-dir DIR   Override install directory (default: /opt/managelm-server)
  --user USER         Service user (default: managelm)
  --port PORT         Portal port (default: 3000)
  --no-systemd        Skip systemd service registration

Configure

Set up PostgreSQL and Redis first — see PostgreSQL Setup and Redis Setup below for the full procedure (creating the user, granting schema access, enabling persistence). The portal will fail to start until both are reachable with valid credentials.

Once PostgreSQL and Redis are running, edit the .env file:

sudo vi /opt/managelm-server/portal/.env

At minimum, set these values:

# How browsers and agents reach the portal
SERVER_URL=https://managelm.example.com

# PostgreSQL connection (created in the PostgreSQL Setup section below)
DATABASE_URL=postgresql://managelm:your-password@localhost:5432/managelm

# Redis connection
REDIS_URL=redis://localhost:6379

# Sender email (only effective when SMTP_HOST is also set)
[email protected]

Then start the service:

systemctl start managelm-server

Check it's running:

systemctl status managelm-server
curl -s http://localhost:3000/health

First Steps After Install

Once the portal is running:

1. Set up a reverse proxy with TLS (nginx or Apache) for production.
2. Register your account at your SERVER_URL. The first user becomes the account owner.
3. Configure the LLM — Local (Ollama), Cloud, or Proxied access mode.
4. Import skills from the built-in catalog.
5. Install an agent on your first server.
6. Connect Claude via MCP.

Reverse Proxy

Place a reverse proxy in front of the portal for TLS. WebSocket support is required for agent connections.

nginx

server {
    listen 443 ssl http2;
    server_name managelm.example.com;

    ssl_certificate     /etc/ssl/certs/managelm.pem;
    ssl_certificate_key /etc/ssl/private/managelm.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Apache

<VirtualHost *:443>
    ServerName managelm.example.com

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/managelm.pem
    SSLCertificateKeyFile /etc/ssl/private/managelm.key

    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]

    ProxyTimeout 86400
</VirtualHost>

SMTP / Email

The portal sends emails for account verification, password resets, and team invitations. When SMTP_HOST is not set, email sending is disabled entirely — no connection attempts are made.

To enable emails, configure an SMTP relay (Brevo, Mailgun, SendGrid, etc.):

SMTP_HOST=smtp.brevo.com
SMTP_PORT=587
SMTP_SECURE=starttls
SMTP_USER=your-username
SMTP_PASS=your-password

PostgreSQL Setup

ManageLM requires PostgreSQL 15+ (16 recommended). The portal runs migrations automatically on startup and needs full control over its schema.

1. Create the database and user

   # Connect as a PostgreSQL superuser
   sudo -u postgres psql
   
   -- Create the ManageLM user
   CREATE USER managelm WITH PASSWORD 'your-strong-password';
   
   -- Create the database owned by that user
   CREATE DATABASE managelm OWNER managelm;
   
   -- Connect to the new database
   \c managelm
   
   -- Grant full schema permissions (required for migrations)
   GRANT ALL ON SCHEMA public TO managelm;
   
   -- PostgreSQL 15+ changed defaults — grant CREATE explicitly
   ALTER DEFAULT PRIVILEGES IN SCHEMA public
     GRANT ALL ON TABLES TO managelm;
   ALTER DEFAULT PRIVILEGES IN SCHEMA public
     GRANT ALL ON SEQUENCES TO managelm;
   
   \q

2. Allow remote connections (if PostgreSQL is on a different host)

   # In postgresql.conf
   listen_addresses = '*'
   
   # In pg_hba.conf — allow the portal host
   host  managelm  managelm  10.0.0.0/8  scram-sha-256

   Restart PostgreSQL: systemctl restart postgresql

3. Set DATABASE_URL in .env

   DATABASE_URL=postgresql://managelm:your-strong-password@localhost:5432/managelm

4. Test the connection

   psql "postgresql://managelm:your-strong-password@localhost:5432/managelm" -c "SELECT 1;"

Redis Setup

ManageLM requires Redis 7+ (or Valkey). It is used for real-time agent communication, session state, and pub/sub — it must be available at all times.

1. Enable persistence (recommended)

   # In redis.conf
   appendonly yes
   appendfsync everysec

2. Set REDIS_URL in .env

   # Without authentication
   REDIS_URL=redis://localhost:6379
   
   # With authentication (Redis 6+ ACL)
   REDIS_URL=redis://username:password@redis-host:6379

3. Test the connection

   redis-cli ping
   # Expected: PONG

Environment Variables

All settings are in /opt/managelm-server/portal/.env. The full reference is the same as the Docker guide.

Required

Strongly recommended

Set this before adding cloud connectors, configuring an LLM API key, enrolling agents, or generating a PKI CA — the portal starts without it (warning only), but any feature that encrypts data at rest will fail until it's configured. Rotating the key invalidates existing encrypted rows, so set it once and keep it.

Database & Redis

SMTP & DKIM

Optional

Advanced

File Layout

/opt/managelm-server/
├── nodejs/          # Bundled Node.js runtime
│   └── bin/node
├── portal/          # ManageLM portal application
│   ├── dist/        # Compiled backend (bytecode)
│   ├── web/dist/    # Frontend build
│   ├── node_modules/
│   ├── cluster.cjs  # Multi-worker entry point
│   ├── loader.cjs   # Bytecode loader
│   ├── .env         # Configuration (root:managelm 640)
│   └── ...
└── agent/           # Agent source (served to managed hosts)
    ├── managelm-agent.py
    ├── lib/
    └── bin/

All files are owned by root:root except .env which is root:<service-user> 640. The service user can read the configuration but cannot modify any binaries.

Upgrading

Download the new release and run it on the same server. The installer detects the existing installation and upgrades in place:

gunzip managelm-<version>-linux-<arch>.sh.gz
sudo bash managelm-<version>-linux-<arch>.sh

The upgrade will:

• Stop the running service
• Replace compiled code, static assets, and the bundled Node.js runtime
• Reinstall production dependencies
• Update the systemd unit file
• Preserve your .env (never overwritten)
• Restart the service

Database migrations run automatically on startup.

Backup & Restore

PostgreSQL holds the durable data and is the only thing you strictly need to back up. Redis is rebuilt from PostgreSQL on portal startup; back it up only if you want to preserve in-flight sessions across restores. Don't forget to copy .env — it holds ENCRYPTION_KEY and is not regenerable.

Backup

# PostgreSQL (run regularly)
pg_dump -U managelm managelm > managelm-backup-$(date +%F).sql

# Configuration (contains ENCRYPTION_KEY — store securely)
cp /opt/managelm-server/portal/.env ./env-backup-$(date +%F)

# Optional — Redis snapshot (in-flight session state)
redis-cli BGSAVE
cp /var/lib/redis/dump.rdb ./redis-backup-$(date +%F).rdb

Restore

# Stop the portal
systemctl stop managelm-server

# Restore PostgreSQL
psql -U managelm managelm < managelm-backup-YYYY-MM-DD.sql

# Restore configuration (if needed)
cp env-backup-YYYY-MM-DD /opt/managelm-server/portal/.env

# Start the portal — Redis state rebuilds automatically (users will need to log in again)
systemctl start managelm-server

Monitoring

# Service status
systemctl status managelm-server

# Health check
curl -s http://localhost:3000/health

# Live logs
journalctl -u managelm-server -f

# Last 100 lines
journalctl -u managelm-server -n 100

Uninstall

# Stop and disable the service
systemctl stop managelm-server
systemctl disable managelm-server
rm /etc/systemd/system/managelm-server.service
systemctl daemon-reload

# Remove the install directory
rm -rf /opt/managelm-server

# (Optional) Remove the service user
userdel managelm

This does not remove PostgreSQL or Redis data. Drop the database manually if no longer needed:

sudo -u postgres dropdb managelm
sudo -u postgres dropuser managelm

Troubleshooting

Portal won't start

Agents can't connect

Database permission errors

Email not sending

.env permission denied