ArmadaOS Bridge

One-click local model connection. No tunnels. No API keys.

ArmadaOS Bridge connects your local AI models (Ollama, CLIProxyAPI, LM Studio, etc.) to your ArmadaOS instance via a persistent WebSocket connection. Run it on your Mac, your PC, or both — and all your local models appear in ArmadaOS automatically.

Quick Start

# Install globally
npm install -g armadaos-bridge

# Authenticate
armadaos-bridge login --token YOUR_TOKEN

# Start the Bridge
armadaos-bridge start

That's it. Your local models are now available in ArmadaOS.

How It Works

Your Machine                              ArmadaOS Cloud
┌─────────────────────┐                  ┌──────────────┐
│ armadaos-bridge     │───WebSocket───▶  │ Engine       │
│  ├─ Ollama :11434   │                  │  ├─ /ws/bridge│
│  ├─ CLIProxy :8317  │                  │  └─ routes    │
│  └─ LM Studio :1234 │                  │     requests  │
└─────────────────────┘                  │     back thru │
                                         │     the WS    │
                                         └──────────────┘

1. Bridge auto-discovers local AI providers (Ollama, CLIProxyAPI, LM Studio, etc.)
2. Establishes an outbound WebSocket to the ArmadaOS Engine
3. Registers all discovered models with the Engine
4. Engine proxies inference requests back through the WebSocket
5. Bridge routes requests to the correct local provider

No inbound ports. No tunnels. No Ngrok. Your API keys never leave your machine.

Commands

| Command | Description | |---|---| | armadaos-bridge start | Start the Bridge (foreground) | | armadaos-bridge start --daemon | Start the Bridge (background) | | armadaos-bridge stop | Stop the running Bridge | | armadaos-bridge status | Show Bridge status and discovered providers | | armadaos-bridge login | Authenticate with ArmadaOS | | armadaos-bridge logout | Remove stored credentials | | armadaos-bridge config show | Show current configuration | | armadaos-bridge config set <key> <value> | Update a config value | | armadaos-bridge config path | Show config file location |

Auto-Discovery

Bridge automatically scans these well-known ports:

| Port | Provider | |---|---| | 11434 | Ollama | | 8317 | CLIProxyAPI (Gemini) | | 8080 | LocalAI | | 1234 | LM Studio | | 3001 | Claude Proxy | | 5000 | Custom Provider |

Add custom ports in bridge.yaml:

discovery:
  customPorts:
    - port: 9000
      name: "My Custom Model Server"
      id: "custom-server"

Multi-Device

Run Bridge on multiple machines simultaneously. All models from all devices appear as one unified pool in ArmadaOS.

Mac (Ollama)  ──WebSocket──▶  Engine  ◀──WebSocket──  PC (CLIProxyAPI)

Configuration

Config file location:

• macOS: ~/Library/Application Support/armadaos-bridge/bridge.yaml
• Windows: %APPDATA%/armadaos-bridge/bridge.yaml
• Linux: ~/.config/armadaos-bridge/bridge.yaml

Requirements

• Node.js 18+
• At least one local AI provider running (Ollama, CLIProxyAPI, LM Studio, etc.)

License

MIT