@alfe.ai/gateway

Local gateway daemon for Alfe — the always-on control plane between an agent VM, its runtime, and Alfe cloud.

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
• Reconciles integrations and state-shaped runtime config from full cloud snapshots
• Supervises the selected runtime (openclaw, hermes, or claude-code)
• Hosts the local AI proxy and MCP bundler
• Survives runtime restarts and reports lifecycle/health back to cloud

Architecture

Alfe Cloud ←—— control WS ——→ @alfe.ai/gateway (daemon)
                                     ├── runtime supervisor → OpenClaw/Hermes/Claude host
                                     ├── integration reconciliation
                                     ├── local AI proxy + MCP bundler
                                     └── IPC (~/.alfe/gateway.sock) ← runtime plugins/CLI

Prerequisites

1. Run alfe setup (or managed provisioning) to configure agent identity
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 in foreground
alfe-gateway start

# 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": "<current CLI version>", "protocolVersion": 1 } }

Event (daemon → plugin)

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

Current methods

| Direction | Method | Description | |-----------|--------|-------------| | Daemon→Plugin | runtime.activity | Probe whether a chat turn is in flight before a planned restart | | 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 | | Plugin→Daemon | mcp.list_tools / mcp.call_tool | Inspect or invoke bundled MCP tools | | Plugin→Daemon | mcp.list_servers / mcp.add_server / mcp.remove_server | Manage local MCP servers |

IPC is owner-only, newline-delimited JSON. Requests must contain non-empty id/method fields and an object params; individual messages are capped at 1 MiB.

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 | | managed systemd environment | ~/.alfe/gateway.env (or /etc/alfe/gateway.env for root) |

Security

• Socket file is chmod 0600 (owner-only access)
• PID ownership is verified against the live process command before signals are sent
• Managed systemd credentials are stored in an owner-only (0600) environment file, not the unit text
• Credential fragments are never logged
• Auth uses the agent API key from managed environment or ~/.alfe/config.toml

Development

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

# 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 | | Outbound | COMMANDS_AVAILABLE | Daemon advertises integration commands | | Inbound | PING | Cloud heartbeat | | Outbound | PONG | Daemon heartbeat response |

DESIRED_STATE is an atomic, deletion-capable snapshot. The daemon validates every nested entry and rejects the entire frame when one row is malformed or duplicated. It also skips all mutation if local integration state cannot be read. See src/protocol.ts, src/reconciliation.ts, and DEVELOPING.md for the full contracts.

Links

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