Aikido Broker Client

A secure broker client that runs in your internal network to forward requests from the Aikido platform to your internal resources via WebSocket connections.

Securely connect internal resources to Aikido's platform. Each resource gets a unique subdomain: https://{resource_id}.aikidobroker.com

Installation

Via npm

npm install @aikidosec/broker-client

Via Docker (Recommended)

docker compose up -d

Quick Start

1. Generate CLIENT_SECRET in Aikido UI:

   • Navigate to: Settings → Broker Clients → Add New Client
   • Copy the generated CLIENT_SECRET

2. Configure environment (.env):

CLIENT_SECRET=your_client_secret_here

3. Start client:

# Using Docker
docker compose up -d

# Using Node.js directly
npm start

4. Register resources via Aikido UI - resources are managed through the Aikido platform

5. Access resources from aikido via subdomain URLs:

https://abc-123.aikidobroker.com/api/endpoint

Resource IDs are displayed in the Aikido UI when you register them.

Environment Variables

Required:

• CLIENT_SECRET - Unique client identifier (generate in Aikido UI: Settings → Broker Clients → Add New Client)

Optional:

• ALLOWED_INTERNAL_SUBNETS - Comma-separated subnet whitelist (e.g., 10.0.0.0/8,172.16.0.0/12)
• DNS_SERVERS - Custom DNS servers for internal hostname resolution (e.g., 8.8.8.8,8.8.4.4)
• NODE_EXTRA_CA_CERTS - Path to custom CA certificate bundle for self-signed certificates (e.g., /certs/corporate-ca.crt)
• HTTP_PROXY - Proxy server for HTTP requests (e.g., http://proxy.company.local:8080)
• HTTPS_PROXY - Proxy server for HTTPS requests (e.g., http://proxy.company.local:8080)
• ALL_PROXY - Universal proxy fallback for all protocols if protocol-specific proxy is not set
• BROKER_TARGET_URL - Override the broker server URL (defaults to https://broker.aikidobroker.com)

How It Works

1. Client Generation: Generate a CLIENT_SECRET in the Aikido UI before deployment
2. Client Registration: On first startup, the client registers with the broker using the CLIENT_SECRET
3. Resource Management: Resources are registered via the Aikido UI and synced to the client
4. Subdomain Mapping: Each resource gets a unique subdomain for external access
5. Secure Proxying: All requests are authenticated and proxied to your internal services

Example Configuration

# .env file
CLIENT_SECRET=aikido_broker_123_123_123456789
ALLOWED_INTERNAL_SUBNETS=10.0.0.0/8,172.16.0.0/12
HTTP_PROXY=http://proxy.company.local:8080
HTTPS_PROXY=http://proxy.company.local:8080
NODE_EXTRA_CA_CERTS=/certs/corporate-ca.crt
DNS_SERVERS=10.0.0.1,10.0.0.2

After registering resources through the Aikido UI, they will be accessible via subdomains like:

• https://xyz-123.aikidobroker.com → routes to your registered internal API
• https://abc-456.aikidobroker.com → routes to your registered internal service

Troubleshooting

# View logs
docker compose logs -f

# Check synced resources
docker compose exec broker-client cat /config/client_resources.json

# Verify connection
docker compose logs | grep "Connected to broker"