Skip to content
AI

CLI Companion

Run VarianTrade AI jobs locally on your machine using your own provider CLI tools.

Full documentation context

Overview

The CLI Companion (variantrade-bridge) is a local agent that executes AI jobs on your computer using provider command-line interfaces that you have already signed into. This allows you to utilize subscription services you already pay for (such as Claude Pro or ChatGPT Plus) without exposing your API keys, session tokens, or browser cookies to the VarianTrade server.

Installation

The companion must be installed via Cargo, the Rust package manager. Pre-built binaries are not published.

To install the companion, you need a Rust toolchain (version 1.86 or newer) from rustup.rs. Run:

cargo install variantrade-bridge

Command Reference

The companion tool supports the following commands:

providers

Lists the provider CLIs supported by this build and shows which ones are currently detected on your system path.

variantrade-bridge providers

enroll

Enrolls the machine with your VarianTrade account.

variantrade-bridge enroll --code <CODE> --provider <PROVIDER>
  • --code: The one-time enrollment code obtained from Telegram.
  • --provider: The CLI provider to use (defaults to claude).
  • --name: Optional custom label for this device.

run

Starts the execution loop. The companion will poll VarianTrade for queued jobs, execute them locally, and return only the text outputs.

variantrade-bridge run --interval <SECONDS> --timeout <SECONDS>
  • --interval: Poll interval in seconds when the queue is empty (defaults to 5).
  • --timeout: Maximum seconds allowed for a single CLI invocation (defaults to 180).

status

Displays the local enrollment state, selected provider, server connection status, and configuration file path.

variantrade-bridge status

Enrollment Process

  1. In Telegram, send /ai_connections and tap Use local CLI or Set up this computer to generate a one-time enrollment code.
  2. The code expires after 15 minutes and can only be used once.
  3. Run the enroll command on your machine with the code.
  4. The server registers the device and returns a unique device secret, which is saved locally with owner-only access permissions (0600 on Unix systems).

Security and Job Boundaries

The companion implements several safety features to protect your machine:

  • No Arbitrary Commands: The application drives provider CLIs using a fixed command table defined in the source code. It does not invoke a shell (sh -c), preventing arbitrary command injection.
  • Credentials Stay Local: The companion does not store or transmit your provider API keys, tokens, or session cookies. It authenticates to VarianTrade using a device-specific secret hash.
  • Single Job Execution: The device claims and processes only one job at a time.
  • Execution Limits: Each job is bounded by a configurable execution timeout and size caps on the inputs and outputs.
  • Sanitized Error Reporting: If a job fails, the companion reports only a short error category (such as max_attempts or timeout) rather than the raw command output, preventing error messages from leaking sensitive context or credentials.

Revoking a Device

You can disconnect any enrolled machine at any time:

  1. Send /ai_connections in Telegram and navigate to your computer list.
  2. Select Revoke [Device Name].
  3. Confirm the revocation.

The server immediately deletes the secret hash for that device. Any subsequent request from the local companion will be rejected, and any pending or running jobs for that device are cancelled.