Security Model
relay enforces strict capability isolation between your main agent and external communication.
Hard Constraints
The conversation agent within each instance has no access to:
- Filesystem (read or write)
- Code execution
- Internal APIs
- Web browsing or network access beyond WhatsApp
- Role escalation or privilege modification
- Infrastructure modification
It only:
- Sends messages via WhatsApp
- Tracks todo item completion
- Manages conversation lifecycle
- Schedules heartbeat follow-ups
Conversation-Scoped Tools
Each conversation instance runs an isolated agent session with exactly four tools:
| Tool | Purpose |
|---|---|
send_message(text) | Deliver a message via WhatsApp |
mark_todo_item(todo_id, status) | Track checklist progress |
end_conversation(reason) | Close the conversation |
schedule_next_heartbeat(delay) | Set the next follow-up timer |
No tool injection. No arbitrary instructions. No escape from this scope.
Network Boundary
relay exposes exactly two network listeners:
- WhatsApp WebSocket — Baileys v7 connection to WhatsApp servers
- HTTP IPC on localhost:3214 — Bound to loopback interface only. CLI commands communicate with the daemon via this local server.
No external HTTP listeners. No webhooks (v1). No cloud connectivity.
Data Isolation
- All external input (WhatsApp messages from contacts) is isolated within the conversation instance
- Contact messages are never exposed to the main agent's execution context
- WhatsApp auth credentials are stored locally in
.relay-agent/with filesystem-level permissions - All state persists as JSON files via lowdb
Design Principle
Your main agent stays powerful. relay stays contained. Separation by design.