Remote Hosts

Remote Hosts - Remote Server Access for Claude

Allows Claude to connect to predefined remote hosts and run commands without needing credentials repeated each time.

Quick Start

# List configured hosts
rhost list

# Run a command on a host
rhost exec <host-id> "command"

# Interactive shell (for user, not Claude)
rhost shell <host-id>

# Check host connectivity
rhost ping <host-id>

# View recent logs
rhost logs <host-id> [service]

# Database access (credentials from keychain)
rhost cred list                                    # List stored credentials
rhost cred set <host-id> mysql <username>          # Store MySQL password (interactive)
rhost mysql <host-id> --user <user> --query "SQL"  # Run MySQL query

Host Configuration

Hosts are stored in ~/.remote-hosts/hosts.yaml:

hosts:
  ppe-db:
    hostname: 10.0.0.50
    user: admin
    key: ~/.ssh/ppe-access-2025
    description: "PPE environment database server"
    environment: ppe

  ppe-web:
    hostname: 10.0.0.51
    user: admin
    key: ~/.ssh/ppe-access-2025
    description: "PPE webservice server (container host)"
    environment: ppe
    docker: true  # Has docker installed

CLI Reference

Host Management

# Add a host
rhost add <host-id> --hostname <ip> --user <user> --key <path>
  --description "description"
  --environment dev|ppe|prod
  --docker                    # Mark as docker host

# List all hosts
rhost list
  --environment <env>         # Filter by environment

# Show host details
rhost show <host-id>

# Remove a host
rhost remove <host-id>

# Test connectivity
rhost ping <host-id>

Remote Execution

# Run a command
rhost exec <host-id> "command"
  --timeout 30                # Command timeout in seconds

# Run command with sudo
rhost exec <host-id> --sudo "command"

# Get a file
rhost get <host-id> <remote-path> [local-path]

# Put a file
rhost put <host-id> <local-path> <remote-path>

Docker Commands (for docker hosts)

# List containers
rhost docker <host-id> ps

# View container logs
rhost docker <host-id> logs <container>
  --tail 100
  --follow

# Exec into container
rhost docker <host-id> exec <container> "command"

# Restart container
rhost docker <host-id> restart <container>

Logs & Debugging

# View system logs
rhost logs <host-id>
  --service <name>            # journalctl -u <service>
  --tail 100
  --since "1 hour ago"

# Check disk space
rhost df <host-id>

# Check memory
rhost free <host-id>

# Check processes
rhost top <host-id>

Credential Management (macOS Keychain)

Store service credentials securely in the macOS Keychain for database access and other services.

# Store credentials (prompts for password)
rhost cred set <host-id> <service> <username>

# Examples:
rhost cred set ppe-db mysql vlink_admin
rhost cred set ppe-db postgres dbuser

# List all stored credentials
rhost cred list

# Delete credentials
rhost cred delete <host-id> <service> <username>

Credentials are stored in macOS Keychain with the format {host-id}:{service}:{username}.

MySQL Commands

Run MySQL queries on remote hosts using credentials from the Keychain.

# Run a query (uses credentials from keychain)
rhost mysql <host-id> --user <username> --query "SQL"
  --database <db>             # Optional database name
  --timeout 60                # Query timeout

# Examples:
rhost mysql ppe-db --user vlink_admin --query "SHOW DATABASES"
rhost mysql ppe-db --user vlink_admin --database mydb --query "SELECT * FROM users LIMIT 5"

Setup workflow:

# 1. Store credentials first (one-time)
rhost cred set ppe-db mysql vlink_admin
# (prompts for password, stores in keychain)

# 2. Run queries (uses stored credentials)
rhost mysql ppe-db --user vlink_admin --query "SHOW TABLES"

If credentials are not found, you'll see:

No MySQL credentials found for vlink_admin on ppe-db.
Store them with: rhost cred set ppe-db mysql vlink_admin

Environment Tags

Hosts can be tagged with environments for organization:

• dev - Development servers
• ppe - Pre-production/staging
• prod - Production (commands require confirmation)

Security Notes

1. SSH keys stay local - Only key paths are stored in config, not key contents
2. Service credentials in Keychain - MySQL/database passwords stored securely in macOS Keychain (not in files)
3. Prod safeguards - Production hosts require confirmation for destructive commands
4. Audit trail - Commands are logged to ~/.remote-hosts/history.log

For Claude

When debugging remote issues:

1. Use rhost ping first to verify connectivity
2. Use rhost exec to run diagnostic commands
3. For docker hosts, use rhost docker logs to check container logs
4. Check rhost df and rhost free for resource issues

For database queries:

1. First check if credentials exist: rhost cred list
2. If credentials exist for the host/service/user, use: rhost mysql <host-id> --user <user> --query "SQL"
3. If credentials don't exist, tell the user to run rhost cred set <host-id> mysql <username> in their terminal (requires interactive password input)
4. NEVER extract credentials from container environment variables or other sources - always use the keychain

Important: The rhost cred set command requires interactive terminal input for the password. Claude cannot run this directly - the user must run it themselves.