remote

Synopsis

ralph-tui remote <subcommand> [options]

The remote command manages connections to ralph-tui instances running on other machines. This enables monitoring and controlling multiple instances from a single TUI.

Subcommands

add

Add a new remote server configuration.

ralph-tui remote add <alias> <host:port> --token <token>

Arguments:

• <alias> - A unique name for this remote (e.g., prod, staging, dev)
• <host:port> - Server hostname and port (port defaults to 7890 if omitted)
• --token <token> - Authentication token from the remote server

Examples:

# Add a remote server with explicit port
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...
 
# Add with default port (7890)
ralph-tui remote add staging staging.local --token YWJjZGVmMDEyMzQ1...
 
# Add localhost for testing
ralph-tui remote add local localhost --token dGVzdDEyMzQ1Njc4...

Alias naming rules:

• Must start with a letter
• Can contain letters, numbers, dashes, and underscores
• Examples: prod, staging-1, server_2, MyServer

list / ls

List all configured remotes with their connection status.

ralph-tui remote list
ralph-tui remote ls  # Alias

Output includes:

• Connection status (✓ connected, ✗ disconnected)
• Server URL
• Latency (when connected)
• Token preview (first 8 characters)
• Last successful connection time

Example output:

Configured Remotes
══════════════════════════════════════════════════════════════

  ✓ prod
    URL:    ws://server.example.com:7890
    Status: connected (45ms)
    Token:  OGQwNTcx...
    Last:   1/19/2026, 3:30:00 PM

  ✗ staging
    URL:    ws://staging.local:7890
    Status: Connection timed out (5s)
    Token:  YWJjZGVm...

──────────────────────────────────────────────────────────────
Total: 2 remote(s)

remove / rm

Remove a remote server configuration.

ralph-tui remote remove <alias>
ralph-tui remote rm <alias>  # Alias

Example:

ralph-tui remote remove staging
# Output: ✓ Remote 'staging' removed

test

Test connectivity to a remote server.

ralph-tui remote test <alias>

This command:

1. Connects to the remote server
2. Authenticates with the stored token
3. Reports connection success/failure and latency
4. Updates the "last connected" timestamp on success

Example:

ralph-tui remote test prod
# Output:
# Testing connection to 'prod'...
#   URL: ws://server.example.com:7890
#
# ✓ Connection successful
#   Latency: 42ms

push-config

Push your local configuration to remote instances.

ralph-tui remote push-config <alias> [options]
ralph-tui remote push-config --all [options]

Options:

Examples:

# Push config to a specific remote
ralph-tui remote push-config prod
 
# Preview what would be pushed
ralph-tui remote push-config prod --preview
 
# Push to all remotes with force overwrite
ralph-tui remote push-config --all --force
 
# Push only global config
ralph-tui remote push-config prod --scope global
 
# Push only project config
ralph-tui remote push-config prod --scope project

How it works:

1. Detection: Checks what config exists locally and on the remote
2. Scope selection: Auto-detects or uses --scope flag
3. Backup: Creates timestamped backup before overwriting (e.g., config.toml.backup.2026-01-19T12-30-00-000Z)
4. Transfer: Pushes the TOML config content over WebSocket
5. Validation: Server validates TOML syntax before writing
6. Migration: Triggers auto-migration to install skills/templates

Scope selection logic (when --scope not specified):

• If you have project config and remote doesn't → push project
• If you have global config → push global
• If you only have project config → push project

Configuration Storage

Remote configurations are stored in TOML format:

File: ~/.config/ralph-tui/remotes.toml

version = 1
 
[remotes.prod]
host = "server.example.com"
port = 7890
token = "OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ"
addedAt = "2026-01-19T00:00:00.000Z"
lastConnected = "2026-01-19T15:30:00.000Z"
 
[remotes.staging]
host = "staging.local"
port = 7890
token = "YWJjZGVmMDEyMzQ1Njc4OTBhYmNkZWYwMTIzNDU2Nzg5"
addedAt = "2026-01-18T10:00:00.000Z"

Remote Parallel Orchestration

When a ralph-tui server is running with --listen, remote clients can start, control, and monitor parallel execution through WebSocket messages.

How It Works

1. Server setup: Start ralph-tui with parallel configuration and --listen:

   BashCopy

   ralph-tui run --prd ./prd.json --listen

2. Client control: Remote clients can send orchestration commands via WebSocket

3. Event streaming: The server streams parallel execution events (worker started, task completed, merge status) to subscribed clients

Orchestration Commands

Remote clients can use these WebSocket message types:

Start Options

When starting orchestration, you can specify:

Example: Programmatic Control

// Connect to remote ralph-tui server
const client = new RemoteClient('ws://server:7890', token);
await client.connect();
 
// Start parallel execution
const result = await client.startOrchestration({
  maxWorkers: 4,
  directMerge: false,
});
 
if (result.success) {
  console.log(`Started orchestration: ${result.orchestrationId}`);
  console.log(`Total tasks: ${result.totalTasks}`);
 
  // Subscribe to events
  client.on('parallel_event', (event) => {
    console.log(`Event: ${event.event.type}`);
  });
 
  // Later: pause if needed
  await client.pauseOrchestration(result.orchestrationId);
 
  // Resume
  await client.resumeOrchestration(result.orchestrationId);
 
  // Or stop
  await client.stopOrchestration(result.orchestrationId);
}

State Response

The orchestrate:get_state command returns:

{
  orchestrationId: string;
  status: 'running' | 'paused' | 'completed' | 'failed';
  startedAt: string;        // ISO 8601 timestamp
  totalTasks: number;
  completedTasks: number;
  failedTasks: number;
  workerStates: {
    [workerId: string]: {
      status: 'idle' | 'running' | 'completed' | 'failed';
      currentTaskId?: string;
      completedTaskIds: string[];
    };
  };
}

Security

Token handling:

• Tokens are shown in preview form (first 8 characters + ...) in list output
• Full tokens are only shown when generated on the server
• All remote actions are logged to ~/.config/ralph-tui/audit.log

Related Commands

• run --listen - Run with remote listener enabled

Troubleshooting

Connection Failed

✗ Connection failed
  Error: Connection timed out (5s)

Possible causes:

• Server is not running (ralph-tui run --listen)
• Firewall blocking port 7890
• Incorrect hostname or port

Solution: Verify the server is running and the port is accessible.

Authentication Failed

✗ Connection failed
  Error: Invalid token

Possible causes:

• Token was rotated on the server
• Token was copied incorrectly

Solution: Get a fresh token from the server with ralph-tui run --listen --rotate-token and update the remote configuration.

Config Push Failed

✗ Push failed: Config already exists at /path/to/config.toml. Use overwrite=true to replace.

Solution: Use --force flag to overwrite existing config, or --preview to see what would change first.

Invalid TOML

✗ Push failed: Invalid TOML: Expected "=" at line 5

Solution: Fix the syntax error in your local config file before pushing.