@alfe.ai/gateway

Local gateway daemon for Alfe — the always-on control plane for agent integrations.

Overview

The gateway daemon is a standalone Node.js process that:

• Maintains a persistent WebSocket connection to Alfe cloud (@alfe/gateway-service on Fly.io)
• Exposes a Unix socket at ~/.alfe/gateway.sock for local plugin IPC
• Translates between the cloud protocol and local IPC protocol
• Survives OpenClaw restarts — it's the always-on bridge between cloud and agent
• Queues commands when plugins are offline (5min TTL)

Architecture

Alfe Cloud ←—— control WS ——→ @alfe.ai/gateway  (daemon, always running)
                                     ↕  IPC (~/.alfe/gateway.sock)
                              @alfe.ai/openclaw    (OpenClaw plugin, Phase 2)
                                     ↕
                                OpenClaw process

Prerequisites

1. Run alfe login to configure your API key in ~/.alfe/config.toml
2. Node.js 22+
3. pnpm

Usage

Via alfe CLI (recommended)

# Start daemon (foreground)
alfe gateway start

# Check status
alfe gateway status

# Stop daemon
alfe gateway stop

# Install as system service (auto-start on boot)
alfe gateway install

# Remove system service
alfe gateway uninstall

# View logs
alfe gateway logs

# Full health check
alfe doctor

Via standalone binary

# Start daemon
alfe-gateway daemon

# Status
alfe-gateway status

# Stop
alfe-gateway stop

IPC Protocol

Plugins connect to ~/.alfe/gateway.sock and speak newline-delimited JSON:

Request (plugin → daemon)

{ "type": "req", "id": "uuid", "method": "register", "params": { "name": "my-plugin", "version": "1.0.0", "protocolVersion": 1, "capabilities": ["integrations"] } }

Response (daemon → plugin)

{ "id": "uuid", "ok": true, "payload": { "status": "registered", "daemonVersion": "0.1.0", "protocolVersion": 1 } }

Event (daemon → plugin)

{ "type": "event", "event": "cloud.status", "payload": { "connected": true } }

Phase 1 Methods

| Direction | Method | Description | |-----------|--------|-------------| | Daemon→Plugin | integration.install | Install an integration | | Daemon→Plugin | integration.remove | Remove an integration | | Daemon→Plugin | integration.configure | Update integration config | | Daemon→Plugin | integration.health | Check integration health | | Daemon→Plugin | integration.activate | Activate an installed integration | | Daemon→Plugin | integration.deactivate | Deactivate a running integration | | Daemon→Plugin | integration.list | List installed integrations | | Plugin→Daemon | register | Register plugin with daemon | | Plugin→Daemon | status | Get daemon health status | | Plugin→Daemon | integration.list | List known integrations | | Plugin→Daemon | integration.report | Report integration status |

File Locations

| File | Path | |------|------| | Config | ~/.alfe/config.toml | | Socket | ~/.alfe/gateway.sock | | PID file | ~/.alfe/gateway.pid | | Logs | ~/.alfe/logs/gateway.log | | launchd plist | ~/Library/LaunchAgents/ai.alfe.gateway.plist | | systemd unit | ~/.config/systemd/user/alfe-gateway.service |

Security

• Socket file is chmod 0600 (owner-only access)
• PID file prevents multiple daemon instances
• Secrets pass through in-memory only — never persisted to disk
• Auth via user's api_key from ~/.alfe/config.toml

Development

# From monorepo root
pnpm install
pnpm --filter @alfe.ai/gateway build
pnpm --filter @alfe.ai/gateway test

# Dev mode (auto-restart on changes)
pnpm --filter @alfe.ai/gateway dev

Cloud Protocol

The daemon speaks the following message types with the cloud gateway service:

| Direction | Message | Description | |-----------|---------|-------------| | Outbound | SERVICE_REGISTER | Register daemon with cloud | | Inbound | SERVICE_ACK | Cloud acknowledges registration | | Inbound | COMMAND | Cloud sends a command to execute | | Outbound | COMMAND_ACK | Daemon reports command result | | Inbound | DESIRED_STATE | Cloud pushes desired integration state | | Outbound | RECONCILIATION_REPORT | Daemon reports reconciliation results | | Inbound | PING | Cloud heartbeat | | Outbound | PONG | Daemon heartbeat response |

See src/protocol.ts for full type definitions.

Completed

• @alfe.ai/openclaw plugin connecting via IPC (packages/openclaw/)
• Integration manifest spec (packages/integration-manifest/)
• Integration registry — now DynamoDB-backed via services/integrations/
• Reconciliation engine (src/reconciliation.ts) — converges local state to cloud desired state

Roadmap

• Dashboard integration management (backend wired, UI in progress)
• Voice migration to integration model (packages/openclaw-voice/ exists, not yet full integration)