@alfe.ai/console-client

Runtime-agnostic WebSocket client for the Alfe console service. It keeps one authenticated outbound connection open and multiplexes browser console traffic to the OpenClaw gateway on the agent host.

Part of Alfe — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the documentation to get started.

Install

npm install @alfe.ai/console-client

Usage

import { ConsoleServiceClient, resolveAlfeConsole } from '@alfe.ai/console-client';

const { apiKey, consoleWsUrl } = resolveAlfeConsole();
if (!apiKey || !consoleWsUrl) throw new Error('Alfe console is not configured');

const client = new ConsoleServiceClient({
  apiKey,
  wsUrl: consoleWsUrl,
  onConnectionChange: (connected) => {
    console.info(`console ${connected ? 'connected' : 'disconnected'}`);
  },
});

client.start();
// Later: client.stop();

resolveAlfeConsole() resolves values in this order:

1. Explicit function overrides.
2. ALFE_API_KEY and ALFE_CONSOLE_WS_URL environment variables.
3. The API key in ~/.alfe/config.toml, with the console URL derived from its stage prefix.

Remote URL overrides must exactly match the stage encoded by the API key. ws:// overrides are accepted only on loopback for local development; URLs with credentials, query parameters, fragments, or paths other than /ws are rejected before the bearer is attached.

Security boundary

The cloud API key and remote console authority are validated as one capability. Tunnel frames are treated as untrusted input even though the cloud WebSocket is authenticated. Requests are limited to the configured local gateway origin, browser-supplied gateway tokens are replaced, credentials are omitted from logs and cloud-facing errors, payloads and queues are bounded, and in-flight local work is discarded when its owning cloud connection closes.

Links

• 🌐 Website: https://alfe.ai
• 📚 Docs: https://docs.alfe.ai