@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-serviceon Fly.io) - Exposes a Unix socket at
~/.alfe/gateway.sockfor local plugin IPC - Reconciles integrations and state-shaped runtime config from full cloud snapshots
- Supervises the selected runtime (
openclaw,hermes, orclaude-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
- Run
alfe setup(or managed provisioning) to configure agent identity - Node.js 22+
- 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