Remote Control

Secure remote control for terminal-based applications with mutual TLS authentication.

Quick Start

# Install (latest prebuilt binary, auto-fallback to source)
curl -fsSL https://raw.githubusercontent.com/IBM/remote-control/main/install.sh | sh

# Install specific version
VERSION=v0.0.1 curl -fsSL https://raw.githubusercontent.com/IBM/remote-control/main/install.sh | sh

# Build from source
INSTALL_FROM_SOURCE=1 curl -fsSL https://raw.githubusercontent.com/IBM/remote-control/main/install.sh | sh

# Initialize mTLS
remote-control init

# Run the server
remote-control server

# Launch a command
remote-control opencode

# Connect a client
remote-control connect

Installation Options

The installer supports the following environment variables:

• VERSION: Specify a release version (default: latest)
  • Example: VERSION=v0.0.1 curl -fsSL ... | sh
• INSTALL_FROM_SOURCE: Set to 1 to build from source instead of using prebuilt binaries
  • Example: INSTALL_FROM_SOURCE=1 curl -fsSL ... | sh
• REPO_URL: Custom repository URL (default: https://github.com/IBM/remote-control.git)
• NO_CLEANUP: Set to 1 to keep temporary files after installation

Note: The installer automatically falls back to building from source if:

• No prebuilt binary exists for your platform
• GitHub API rate limits are exceeded
• Network issues prevent binary download

Why Remote Control

Remote Control enables you to:

• Control from anywhere: Start a command locally, control it from anywhere
• Secure communication: Encrypted traffic and client authentication with mutual TLS (mTLS)
• Flexible deployment: Deploy the control server on your LAN, VPN, or as a public server endpoint

Common use cases:

• Control coding agent sessions from anywhere
• Manage long-running processes through network interruptions
• Collaborative debugging from multiple locations

---

Project Architecture

┌────────────┐  mTLS  ┌───────────────┐  mTLS  ┌────────────┐
│    Host    │◄──────►│     Server    │◄──────►│   Client   │
│ (runs cmd) │        │ (buffers I/O) │        │  (remote)  │
└────────────┘        └───────────────┘        └────────────┘

Components:

• Host: Wraps the target command, proxies stdout to the server and stdin from server
• Server: Maintains session state, buffers I/O for multiple clients
• Client: Connects to observe output and submit stdin to existing sessions

Key features:

• WebSocket-based bidirectional communication
• Session approval workflows
• Multi-client attachment support

---

Security

Remote Control uses mutual TLS (mTLS) for all communications:

• Server authentication: Clients verify the server certificate against a trusted CA
• Client authentication: Server verifies client certificates against a trusted CA
• Encrypted transport: All traffic is encrypted via TLS
• Separate CAs: Server and client sides use separate CA certificates for defense in depth

Certificate management:

# List certificates with expiry dates
remote-control cert list

# Verify configured certificates
remote-control cert verify

# Issue a new client certificate
remote-control cert issue <name>

---

Contributing

Development Setup

1. Build in debug mode (no optimizations):

   make build.debug

2. Run tests:

   make test

3. Generate coverage report:

   make coverage-html

Running the Server

# With default listen address
remote-control server

# Custom listen address
remote-control server --addr :9443

Configuration

Configuration is stored in ~/.remote-control/config.json by default. Customize via:

• REMOTE_CONTROL_HOME environment variable
• CLI flags: --server, --client-cert, --client-key, --client-ca

---

License

See LICENSE file for details.