runtime - nself-org/cli GitHub Wiki

Plugin Runtime Management

Commands: start, stop, restart, logs, ps, health

Complete plugin lifecycle management as external Node.js processes.

Overview

The plugin runtime system allows you to run nself plugins as external Node.js processes with full lifecycle management, automatic setup, and health monitoring.

Auto-Handled:

  • โœ… Shared utilities build (one-time)
  • โœ… Dependencies installation (pnpm install)
  • โœ… TypeScript compilation (pnpm build)
  • โœ… Environment setup (.env with DATABASE_URL + ENCRYPTION_KEY)
  • โœ… Process management (PIDs, logs, graceful shutdown)
  • โœ… Health checks via /health endpoints

Commands

nself plugin start

Start one or all installed plugins.

Usage:

nself plugin start <name>      # Start specific plugin
nself plugin start --all       # Start all installed plugins
nself plugin start -a          # Same as --all

What It Does:

  1. Checks if shared utilities are built (builds if needed)
  2. Installs dependencies if node_modules/ missing
  3. Compiles TypeScript if dist/ missing
  4. Creates .env file with DATABASE_URL and ENCRYPTION_KEY
  5. Starts plugin in background
  6. Saves PID to ~/.nself/runtime/pids/<name>.pid
  7. Logs to ~/.nself/runtime/logs/<name>.log

Examples:

# Start single plugin
nself plugin start vpn

# Start all plugins
cd ~/Sites/myproject/backend
nself plugin start --all

Output:

โ„น Starting vpn...
โœ“ vpn started (PID: 12345)
Logs: nself plugin logs vpn

nself plugin stop

Stop one or all running plugins.

Usage:

nself plugin stop <name>       # Stop specific plugin
nself plugin stop --all        # Stop all running plugins
nself plugin stop -a           # Same as --all

What It Does:

  1. Sends SIGTERM for graceful shutdown
  2. Waits up to 5 seconds
  3. Sends SIGKILL if still running
  4. Removes PID file

Examples:

# Stop single plugin
nself plugin stop vpn

# Stop all running plugins
nself plugin stop --all

Output:

โ„น Stopping vpn (PID: 12345)...
โœ“ vpn stopped

nself plugin restart

Restart a running plugin (stop + start).

Usage:

nself plugin restart <name>

Examples:

# Restart after code changes
nself plugin restart vpn

# After updating .env
nself plugin restart torrent-manager

nself plugin logs

View plugin logs.

Usage:

nself plugin logs <name>          # Show last 50 lines
nself plugin logs <name> -f       # Follow logs (live tail)
nself plugin logs <name> --follow # Same as -f

Log Location: ~/.nself/runtime/logs/<name>.log

Examples:

# View recent logs
nself plugin logs vpn

# Follow logs live (Ctrl+C to exit)
nself plugin logs vpn -f

# Debug startup issues
nself plugin start discovery
nself plugin logs discovery

Output:

2026-02-14T22:12:44.078Z INFO  [vpn:config] Configuration loaded
2026-02-14T22:12:44.162Z INFO  [vpn:main] ๐Ÿš€ Starting VPN Plugin...
2026-02-14T22:12:44.163Z INFO  [vpn:database] Initializing database schema

nself plugin ps

List all running plugins (alias: running).

Usage:

nself plugin ps
nself plugin running    # Same command

Examples:

nself plugin ps

Output:

=== Running Plugins ===

vpn                  PID: 12345    Port: 3200
torrent-manager      PID: 12346    Port: 3201
content-acquisition  PID: 12347    Port: 3202
subtitle-manager     PID: 12348    Port: 3204

Total: 4 running

nself plugin health

Health check all running plugins.

Usage:

nself plugin health

What It Does:

  1. Checks if process is running (PID exists)
  2. Reads port from .env
  3. Tries HTTP GET http://localhost:<port>/health
  4. Reports status for each plugin

Examples:

nself plugin health

Output:

=== Plugin Health Check ===

โœ… vpn - Healthy (port 3200)
โœ… torrent-manager - Healthy (port 3201)
โš ๏ธ  discovery - Running but not responding (port 3000)
โŒ metadata-enrichment - Not running

3/4 plugins healthy

Environment Setup

Automatic .env Creation

When starting a plugin, the CLI auto-creates ~/.nself/plugins/<name>/ts/.env with:

# Auto-generated by nself plugin start
DATABASE_URL=postgresql://user:pass@host:port/database
ENCRYPTION_KEY=<random-32-char-key>
PORT=<from-plugin.json>
LOG_LEVEL=info

DATABASE_URL Detection: The CLI reads your project's .env files in order:

  1. .env.dev (checked first)
  2. .env.local
  3. .env

It looks for either:

  • DATABASE_URL=<full-connection-string>
  • Or builds from: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT

ENCRYPTION_KEY Generation: Stored at ~/.nself/encryption.key (generated once, reused for all plugins).

Custom Configuration

To customize plugin environment:

# Edit the auto-generated .env
vim ~/.nself/plugins/vpn/ts/.env

# Add plugin-specific variables
echo "VPN_PROVIDER=nordvpn" >> ~/.nself/plugins/vpn/ts/.env

# Restart to apply
nself plugin restart vpn

Runtime Directory Structure

~/.nself/
โ”œโ”€โ”€ shared/                      # Symlink to plugins/_shared (auto-created)
โ”œโ”€โ”€ encryption.key               # Master encryption key (auto-generated)
โ”œโ”€โ”€ plugins/
โ”‚   โ”œโ”€โ”€ _shared/                 # Shared utilities for all plugins
โ”‚   โ”‚   โ””โ”€โ”€ dist/               # Built shared code
โ”‚   โ””โ”€โ”€ vpn/
โ”‚       โ”œโ”€โ”€ plugin.json          # Plugin manifest
โ”‚       โ””โ”€โ”€ ts/
โ”‚           โ”œโ”€โ”€ .env            # Auto-generated environment
โ”‚           โ”œโ”€โ”€ node_modules/   # Auto-installed dependencies
โ”‚           โ”œโ”€โ”€ dist/           # Auto-compiled TypeScript
โ”‚           โ””โ”€โ”€ src/            # Plugin source code
โ””โ”€โ”€ runtime/
    โ”œโ”€โ”€ logs/                    # Plugin logs
    โ”‚   โ”œโ”€โ”€ vpn.log
    โ”‚   โ”œโ”€โ”€ torrent-manager.log
    โ”‚   โ””โ”€โ”€ ...
    โ””โ”€โ”€ pids/                    # Process IDs
        โ”œโ”€โ”€ vpn.pid
        โ”œโ”€โ”€ torrent-manager.pid
        โ””โ”€โ”€ ...

Troubleshooting

Plugin Fails to Start

# Check logs
nself plugin logs <name>

# Common issues:
# 1. Missing database tables
nself plugin <name> init

# 2. TypeScript compilation errors
cd ~/.nself/plugins/<name>/ts
pnpm build

# 3. Missing dependencies
cd ~/.nself/plugins/<name>/ts
pnpm install

DATABASE_URL Not Found

Ensure your project has .env with database credentials:

# Option 1: Direct URL
DATABASE_URL=postgresql://user:pass@host:port/database

# Option 2: Individual vars (auto-composed)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=mypassword
POSTGRES_DB=myproject_db
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

Shared Utilities Error

If you see "Shared utilities not found":

cd ~/Sites/nself-plugins/shared
pnpm install && pnpm build

# Then retry
nself plugin start --all

Port Already in Use

# Find what's using the port
lsof -i :3200

# Stop the conflicting process
# Or change plugin port in .env
vim ~/.nself/plugins/vpn/ts/.env
# Change: PORT=3200 โ†’ PORT=3210
nself plugin restart vpn

Complete Workflow Example

# 1. Start your nself backend
cd ~/Sites/myproject/backend
nself start

# 2. Install plugins you need
nself plugin install vpn
nself plugin install torrent-manager
nself plugin install subtitle-manager

# 3. Start all plugins
nself plugin start --all

# 4. Check status
nself plugin ps

# 5. Health check
nself plugin health

# 6. View logs
nself plugin logs vpn -f

# 7. Run your application (plugins are available via HTTP)
pnpm dev

# 8. Stop when done
nself plugin stop --all
nself stop

Integration with Docker (CS_N Alternative)

Plugins can run either as:

Option A: External Processes (current approach)

  • โœ… Simple setup
  • โœ… Auto-handled dependencies
  • โœ… Easy debugging (logs, restart)
  • โŒ Manual process management

Option B: Docker via CS_N

# Add to .env
CS_1=vpn:express-js:3200
CS_2=torrent-manager:express-js:3201

# Build and start
nself build && nself start
  • โœ… Unified with other services
  • โœ… Auto-restart on failure
  • โŒ More complex setup
  • โŒ Shared utilities path issues

Recommendation: Use external processes (Option A) during development, Docker (Option B) for production.

Related Commands

See Also

ษณSelf CLI v1.0.9. MIT licensed. Docs CC BY 4.0.

GitHub ยท Issues ยท Discussions ยท nself.org ยท docs.nself.org

โš ๏ธ **GitHub.com Fallback** โš ๏ธ