Gopala documentation
Gopala runs autonomous AI agents around the clock on your own servers; these docs cover setup, configuration, security, protocols and the chat providers.
Gopala signs in as an ordinary account on Lupyd, Slack or Discord, and every conversation it serves gets its own agent in its own Firecracker microVM. Agents watch their own memory and disk, clean up after themselves, and ask the host for more when they need it. The site Gopala serves is a self-hosted control panel: a live dashboard (every number measured on the host), a configuration editor, and these docs. Start with the project README for a summary and quick setup. Known gaps are cited as “issue #N”.
| Document | Read it for |
|---|---|
| Architecture | Goals, components, crates and key types, the runtime model, the lifecycle of a conversation, resource management, the control plane and metering, network modes, token budgets, agent tools and MCP servers, harnesses (omp, Claude Code, exec; the system prompt; restarting; the agent’s own MCP servers), images, alerts, listening mode, collaboration, memory, monitoring, host-provided tools, sequence diagrams (a mention end to end, approvals, a resource request, /watch, guest reconnect), data on disk, the configuration map, design decisions and known limitations |
| Protocols | Every wire protocol: the host⇄guest control channel (including usage reports, memory settings, harness restarts and delivery text), the MCP tools exposed to guests (chat and VM tools, send_message severity, list_agents, restart_harness, the memory server), how the guest drives omp’s RPC mode and Claude Code’s stream-json, the viewer websocket and its crypto, the monitor websocket (sign-in, Lupyd tokens, authorization, subscriptions), the LLM proxy with its metering and budget refusals, the egress proxy, HTTP MCP servers, the HTTP API (sign-in, dashboard control, budgets, listening mode, monitoring, configuration) |
| Security | Threat model, trust boundaries, mitigations with code references (VM isolation, resource limits and token budgets, secrets, notifications, files root writes for the agent, other agents in a group, monitoring and endpoint authentication, the admin API and dashboard, metering, host-provided tools, the agent’s memory, network modes and the egress proxy), residual risks with issue numbers, production hardening checklist |
| Operations | Host prerequisites, installing gopala, gopala image build with image.setup recipes, the tools image and the site, networking (proxy, none, NAT), creating the bot on Lupyd, Slack and Discord, configuring (file or browser), recipes (MCP servers, budgets), sizing VMs and the host, reading /status, choosing a harness, collaboration per platform, alerts, listening mode, memory settings and sizing, monitoring rules and connecting an app, the dashboard, running under systemd, observability, troubleshooting |
| Providers | The Lupyd, Slack and Discord providers side by side: the Platform contract, conversation ids and keys, events, mention handling, notifying people (send_notifying), membership for monitoring (member), other agents (agents, from_agent), security expectations |
| References | Annotated external references: Firefly, MLS, Firecracker, omp, MCP, crates and RFCs |
The configuration reference (every key, its default and its meaning) is in
operations.md; a running Gopala also serves it as JSON Schema at
/api/config/schema.