Gateway Documentation
Secure remote access to your local machine
TL;DR - Quick Start
Commands.com Gateway lets you share your local AI agent with anyone through an encrypted relay. Code never leaves your machine.
- Clone: git clone https://github.com/Commands-com/commands-com-agent.git
- Build: npm install && npm run build
- Launch: npm run dev:desktop (opens the Desktop App with setup wizard)
- Connect: Share your agent with teammates via the web dashboard
- Security: AES-256-GCM encryption, zero-knowledge relay
Table of Contents
What is Gateway?
Commands.com Gateway is a secure relay for local AI agents. You run an AI agent on your machine — connected to your codebase, tools, and data — and share access with teammates, clients, or collaborators through an encrypted relay. Remote users chat with the agent from their browser. Your code never leaves your device.
Key Benefits
Zero-Knowledge Relay
End-to-end encryption means no one — not even us — can see your data
Your Local Environment
The agent runs on your machine with your files, tools, and configurations
Full Control
Configure permission profiles — read-only, dev-safe, or full access
Share with Anyone
Teammates chat with your agent from any browser, any device
Use Cases
- Share your codebase — a product owner can ask questions about what the code does, without giving repo access
- Remote collaboration — teammates interact with each other's local agents from anywhere
- Tech support — share a scoped agent with clients or family, configured for exactly what they need
- AI-assisted development — use Claude with your local codebase and MCP tools through the browser
How It Works
Architecture Overview
Gateway uses a relay server architecture with end-to-end encryption to connect your web browser to your local machine.
Local Agent
Runs on your machine, manages execution and security
Relay Server
Routes encrypted messages, cannot decrypt them
Web Dashboard
Browser-based interface with chat and controls
Connection Flow
- Installation: Install the local agent on your development machine
- Authentication: Sign in via OAuth (automatic browser popup like GitHub CLI)
- Device Pairing: Agent generates cryptographic keys and registers with relay server
- Encryption Setup: Browser and agent perform X25519 key exchange
- Secure Session: All messages encrypted with AES-256-GCM
- Prompt Execution: Remote user sends prompts, agent executes locally with configured permissions
Zero-Knowledge Architecture
The relay server only sees encrypted messages. Your code, commands, and data are never visible to us.
Getting Started
Installation
Step 1: Clone and Build
git clone https://github.com/Commands-com/commands-com-agent.git
cd commands-com-agent
npm install
npm run build
Requires Node.js 20+ and a valid Claude API key or Claude Code auth.
Step 2: Launch the Desktop App (Recommended)
npm install --prefix ./desktop
npm run dev:desktop
The Desktop App opens a guided setup wizard where you can configure your agent profile, select MCP modules, set permissions, and start the agent — all from one interface. It also streams live logs and lets you start/stop the agent with one click.
Step 3: Share with Anyone
Visit your Gateway Dashboard from any device and click "Launch Chat" to start a remote session with your agent.
CLI Alternative
Prefer the command line? Run ./start-agent.sh directly. It opens your browser for OAuth, registers your device, and connects to the relay. See the README for all CLI options.
Security Model
End-to-End Encryption
Gateway uses industry-standard cryptographic protocols to ensure your data remains private and secure.
Key Exchange
- X25519: Elliptic curve Diffie-Hellman for key agreement
- Ephemeral keys: Fresh keys for every session
- Transcript hashing: SHA-256 prevents man-in-the-middle attacks
- HKDF: Key derivation with session-specific salt
Message Encryption
- AES-256-GCM: Authenticated encryption with 128-bit tag
- Deterministic nonces: Sequence-based, direction-specific
- AAD protection: Session metadata included in authentication
- Replay prevention: Sequence numbers detect duplicate messages
Authentication
- Firebase Auth: OAuth 2.0 with Google identity
- Device keys: Ed25519 signatures for device identity
- JWT tokens: Short-lived access tokens
- Secure storage: Keys stored locally with restricted file permissions (0600)
Features
Desktop App
- Guided setup wizard for agent profiles and MCP modules
- One-click start/stop with live log streaming
- Audit trail viewer with filters and JSON export
- Configure permissions, working directory, and model
Permission Profiles
- read-only: Read, Grep, Glob only — no bash, no writes
- dev-safe: All tools except blocked ones; path restrictions
- full: Unrestricted access to all tools
- You control what remote users can do on your machine
Device Management
- Multiple devices per account
- Online/offline status indicators
- Quick launch to any device
- Easy device removal
Session Management
- Automatic reconnection on network issues
- Session persistence across page reloads
- Clean session termination
- Connection status monitoring
Troubleshooting
Device shows as offline
- Ensure the local agent is running:
node dist/index.js status - Check your network connection and firewall settings
- Restart the agent: stop the process and run
./start-agent.sh - Verify the agent is using the correct gateway URL (default: https://api.commands.com)
Connection fails during handshake
- Clear browser cache and cookies for Commands.com
- Try signing out and signing back in
- Check browser console for specific error messages
- Ensure WebCrypto API is available (HTTPS required)
Agent won't start
- Verify Node.js version is 20 or higher:
node --version - Make sure you've built the project:
npm run build - Check config at
~/.commands-agent/config.json - Update:
git pull && npm install && npm run build
Messages not appearing
- Check connection status indicator (should be green)
- Verify end-to-end encryption indicator is showing
- Refresh the page to re-establish connection
- Check browser console for cryptographic errors
Still Having Issues?
Contact support at support@commands.com with your device ID and error logs.
Frequently Asked Questions
Can Commands.com see my data?
No. All messages are encrypted end-to-end using keys that only your browser and local agent possess. The relay server only sees encrypted data and cannot decrypt it.
What happens if the relay server is compromised?
Even if an attacker gains access to the relay server, they cannot decrypt your messages. The encryption keys are derived through a secure key exchange between your browser and local agent, never passing through the relay.
Do I need to keep my machine on 24/7?
Only when you want to access it remotely. The agent must be running for remote connections. You can stop/start it anytime, and it will automatically reconnect.
Can I use this on mobile devices?
Yes! The web interface works on any device with a modern browser. However, the local agent must run on a desktop/server machine (Windows, macOS, or Linux).
How many devices can I connect?
Free tier allows 1 device. Pro tier allows unlimited devices. See pricing for details.
What about firewalls and corporate networks?
Gateway uses standard HTTPS (port 443) for all communication, which works through most firewalls. If your network blocks outbound connections, you may need to allowlist our relay server domains.
Is this open source?
Yes, the local agent is open source at github.com/Commands-com/commands-com-agent. The relay server and web interface are proprietary, but the cryptographic protocol is fully documented for security review.
Need More Help?
Our support team is here to assist you with any questions or issues.