Platforms · Lupyd
Members' apps People in a group or DM with the agent, on the ordinary Lupyd apps. They invite or message the agent, @mention it, answer approvals with yes/no replies or ✅ ❌ 1️⃣…🔟 reactions, and send the host commands /watch, /stop, /status and /help.
behavior.respond_to: every message, mentions only, or DMs only behavior.direct_messages and behavior.invites decide who can reach the agent The Lupyd app follows the agents of the person’s own conversations on /monitor, signed in with their Lupyd token Read more Platforms · Lupyd
Firefly server Lupyd's end-to-end encrypted chat (MLS, RFC 9420). It relays encrypted group and direct messages between members' devices and the agent's device and can't read them. Gopala doesn't reimplement this protocol: the Lupyd provider reuses firefly-mcp.
Read more Platforms · Lupyd
Auth0 sign-in On Lupyd the agent uses an ordinary account. On first start the Lupyd provider signs in once with LUPYD_EMAIL / LUPYD_PASSWORD (Auth0 password-realm grant, through firefly-mcp's Auth), then keeps only the refresh token in <data_dir>/lupyd/session.json (0600) and renews from it.
Only when [platforms.lupyd] is enabled; gopala web never signs in The credentials are removed from the environment and dropped after sign-in Read more Platforms · possible providers
Slack provider (gopala-slack) The agent’s Slack account is a Slack app in Socket Mode, so no public URL is needed. Each channel the agent is in is a conversation and direct messages are conversations with one person; replies stay in their thread, every split part included. Alerts render as @channel, @here, user groups and users; monitoring asks Slack for channel membership, user groups and admin/owner flags.
[platforms.slack]: bot_token_env (xoxb-) and app_token_env (xapp-) The Create an Agent page downloads the app manifest Read more Platforms · possible providers
Discord provider (gopala-discord) The agent’s Discord account is a bot application on the gateway (twilight). Each server is a conversation and its text channels and threads are its channels; direct messages are conversations with one person. It needs the Message Content intent; Server Members is optional and keeps membership answers current. Alerts can ping @everyone, @here, roles and members.
[platforms.discord]: token_env Invite permissions 274878106688 Read more Browsers and viewers
Viewer: gopala watch The reference viewer (gopala_rooms::client::watch). It takes the link <public_url>/watch#<token> (http(s) turned into ws(s)) from GOPALA_WATCH_LINK or stdin, presents the token only inside the websocket hello, unwraps each room key with its token-derived key, and prints the replayed journal followed by live events. It can only send ping.
Read more Browsers and viewers
Operator's browser The website is a stateless static frontend served by Gopala itself. The Configure page builds a gopala.toml from the server’s JSON Schema and checks it with the exact validator; with the admin token (kept in the page’s memory only) it can load the running configuration and save a new one.
Before the first run: gopala web --config gopala.toml serves the site and API without signing in to any platform Signed out, the configurator uses the schema and defaults bundled with the site and can’t check a file against the server Read more Host
Lupyd provider (gopala-lupyd) The first implementation of gopala-platform’s Platform trait. It runs the agent's own Firefly device (firefly-mcp's Agent), keeps the MLS connection up over WebTransport or WebSocket, and turns decrypted Firefly messages, reactions, invites and membership changes into platform-neutral events for the router. Everything the agent says on Lupyd goes out through it.
Enabled by [platforms.lupyd]; one Gopala can run several providers at once Scope keys carry the platform name as a prefix One process per Lupyd account and data directory (firefly-mcp.lock) Read more Host
Router (the event loop) daemon::run merges the platform-neutral events of every enabled provider and handles them one at a time in the Router. It admits DMs and invites by policy, finds or creates the conversation's scope, records every message, routes approval answers, answers /watch, /stop, /status and /help itself, and wakes the agent only when policy::triggers says so. Another agent's message takes a narrower path: it wakes the agent only by mentioning it or replying to it, within collaboration.max_agent_messages_per_hour, and is never a command or an approval answer.
Owns the scope table: one HostConversation and session per conversation, on any platform When a member leaves it revokes their watch tokens Deliveries read “alice in #general (channel 1) [message N]:”, or “researcher (agent) …” from another agent Read more Host
Approvals Open approval questions, per conversation. Parses replies (yes, ok, go ahead / no, deny, …), choice numbers and ✅ ❌ or keycap reactions from approvers, and resolves the waiting request. No answer within approvals.timeout_secs means no.
approvals.approvers: members, owner or allowlist (the same rule gates /stop) At most 3 open questions per conversation Read more Host · per conversation
HostConversation One per scope (a group or DM on one platform), shared by the router, the session and the MCP sessions. It keeps the in-memory EventLog behind wait_for_events, sends through its platform’s provider (rate-limited, split to max_message_chars), runs approval questions, and journals sessions and outbound messages to Rooms.
Scope keys are prefixed with the platform, never a username Edits and deletes only the agent’s own messages list_agents: Platform::agents with collaboration.agent_role, cached 5 minutes, dropped when members change take_agent_message: the hourly cap on wake-ups by other agents Read more Host · per conversation
Session supervisor session::run, one task per conversation: queues deliveries, waits for one of vm.max_vms slots and for its memory to fit the host’s memory budget, boots the VM with the conversation’s allocation, does the hello / HostInit handshake on vsock 1024, relays deliveries, events, usage, status and approvals, stops the VM when idle or asked to sleep, restarts it when asked, and retries crashes with backoff.
Memory budget: vm.memory_budget_mib (0 = 80% of the host’s memory) shared by all running VMs; a VM that doesn’t fit waits (“waiting for host memory”) Backoff 5 s · 2^(failures−1), at most 160 s; the conversation is told after 3 failures Guest hello within 10 s; the whole boot within vm.boot_timeout_secs Read more Host · per conversation
VmControl: the agent’s control over its VM One per conversation, behind the vm_resources, request_resources, restart_vm and sleep_vm tools. It knows the VM’s allocation, the maximums and the latest usage from the guest; decides requests for more (or less) vCPUs, memory and disk; persists grants; and asks the session to restart or sleep the VM about a second after answering.
decide: disks only grow; at least 1 vCPU and 128 MiB; within vm.max_vcpus / max_memory_mib / max_disk_gib and the host memory budget; giving back is always granted Growth: vm.grants = "never" denies, "approval" asks the conversation’s approvers, "auto" grants; disk growth must leave vm.min_free_disk_gib free on data_dir’s filesystem Grants go to <data_dir>/vms/<scope>/allocation.json (0600, atomic rename), are clamped to the current maximums on load, and apply at the next boot Every grant, denial, restart and sleep is journaled as a “resources” notice; /status shows the allocation and usage Read more Host · per conversation
Scoped MCP server The guest’s MCP server, named chat: firefly-mcp's tool vocabulary (conversation_info, read_messages, send_message, edit_message, delete_message, react, wait_for_events, search_messages) plus request_approval and list_agents, built on the one HostConversation whose socket the connection arrived on, and five tools for the agent’s own VM: vm_resources, request_resources, restart_vm, sleep_vm and restart_harness. No tool takes a group id, username or scope.
One rmcp session per connection on the VM’s {uds}_1025 socket request_resources takes totals (vcpus, memory_mib, disk_gib) and a reason, not increments list_agents: the other agents in this group (username, roles, bio), at most 50; errors when collaboration is off restart_harness {reason}: restarts the harness in the running VM about a second after answering, keeping the session; refused for exec Read more Host · per conversation
LLM proxy A hyper HTTP/1 proxy per [[llm]] entry on the VM’s vsock port 1100+i. Accepts only origin-form requests, buffers bodies up to 32 MiB, strips every credential header, adds the real key from secret_env, forwards over HTTPS to the fixed upstream, streams the response back, and never follows redirects.
Read more Host
Web server: one HTTP(S) port Everything Gopala serves goes through one HTTP(S) server on [server].bind: the static website at /, the API under /api, the /watch websocket for viewers, which it upgrades and hands to Rooms, and the /monitor websocket for apps (with its HTTP mirror under /api/monitor/). TLS comes from tls_cert / tls_key; plain HTTP off loopback needs allow_plaintext (behind a TLS-terminating proxy).
Public: the static site, GET /api/status (the version only once signed in) and POST /api/session; every other endpoint needs a credential Operator only: the dashboard API, GET and PUT /api/config and the config helpers (schema, defaults, validate, normalize), with Authorization: Bearer <token from admin_token_env> or the session cookie; 403 when no token is configured /monitor and /api/monitor/: the admin token, a watch token or a Lupyd sign-in token; people see only conversations their platform says they are in, as [monitoring] allows Request bodies are capped at 256 KiB; JSON errors as {"error": …} gopala web serves the site and configuration API without signing in to any platform; gopala run adds /watch and answers /monitor Read more Host
Rooms: watch journal and keys What viewers on /watch are served from: the SQLite journal rooms.db, where each SessionEvent gets a per-scope seq, is stored and fanned out to viewers. Issues personal watch tokens, seals events with rotating XChaCha20-Poly1305 room keys, and revokes access when a member leaves. It runs no listener of its own.
Tokens stored as SHA-256 plus the derived key-wrapping key, never the secret The journal is plaintext on the host; sealing is not end-to-end Read more Host
gopala.toml The configuration file Gopala was started with. The admin endpoints read it (GET /api/config) and replace it after validating (PUT /api/config); safe sections apply at once, the rest at the next restart. The validate and normalize helpers (operator only) never touch it.
Validation gives the same messages as gopala check-config Read more Host
VM manager (gopala-vm) VmManager::prepare_with sets up a slot with the conversation’s allocation: its persistent disk (grown offline to disk_gib), a tap device gpl<n> with its own /30 (NAT only), the vsock sockets and the Firecracker config with that vcpu_count and mem_size_mib, optionally inside a jailer chroot as an unprivileged uid/gid with cgroups. It boots firecracker --no-api; stop waits up to 30 s, then removes everything but the disk.
Slot n → guest CID 3+n, tap gpl<n>, host .4n+1 / guest .4n+2 in 172.30.0.0/16 Read more Inside each microVM
gopala-guest run A static musl binary started by systemd (Restart=always) that depends only on gopala-proto. It keeps the control link to the host, provisions the agent user, packages and setup scripts once per input hash, starts the model forwarders, writes the system prompt, and supervises the harness, turning its output into SessionEvents. Before every harness start it writes the MCP config: the host’s servers merged with the ones the agent added to /home/agent/.gopala/mcp.json.
Reconnects with backoff 200 ms → 5 s; queues up to 2000 frames while disconnected The agent’s file: ≤ 64 KiB, ≤ 32 servers, no symlinks, owned by the agent; chat, memory and operator names stay the host’s Read more Inside each microVM
The harness: omp, Claude Code or exec The agent, running as the agent user. agent.harness picks it: omp --mode rpc (the default) or Claude Code (claude -p with stream-json), each one long-lived session per VM with subagents, or exec, any command run once per message. Deliveries arrive as prompts (follow-ups while busy). It replies to people only through the chat MCP tools; everything else streams to viewers. Its system prompt covers talking to people, working autonomously, limited resources, extending itself, memory and other agents, with the operator’s text appended last. After a reboot or restart_harness it continues the same session (-c or --continue).
omp’s default agent.args: --approval-mode yolo; Claude Code runs with bypassPermissions (the VM is the sandbox; approvals go through request_approval) Claude Code reaches Anthropic through an [[llm]] proxy (ANTHROPIC_BASE_URL in guest_env) The agent can add MCP servers to its own mcp.json and call restart_harness to load them Read more Inside each microVM
Resource monitor (inside gopala-guest) Every agent.usage_interval_secs (default 30) the guest samples /proc/meminfo, the root filesystem (space a non-root user can use), /proc/loadavg and the online CPUs, and sends a ResourceUsage frame to the host on the control channel. When disk use reaches agent.disk_alert_percent (85) or memory agent.memory_alert_percent (90), it steers omp once with the numbers and concrete cleanup steps, and journals a notice for viewers.
Cleanup first (cargo clean, node_modules / target / dist, apt-get clean, caches, docker system prune, /tmp); only then request_resources and restart_vm Alerts re-arm after use drops 5 points below the threshold; disk and memory are independent Read more Inside each microVM
MCP bridge: gopala-guest mcp The harness starts gopala-guest mcp --port 1025 as its stdio MCP server named chat. It copies bytes between stdin/stdout and vsock 2:1025, where each connection becomes one ScopedMcp session on the host.
Read more Inside each microVM
Model API forwarder One TCP listener per [[llm]] on 127.0.0.1:<guest_port>, piped byte for byte to vsock 2:(1100+i). The harness finds it through guest_env, e.g. ANTHROPIC_BASE_URL=http://127.0.0.1:8701 with a placeholder key; the real key never enters the VM.
Read more Inside each microVM
Persistent workspace disk The conversation’s root disk, <data_dir>/vms/<scope>/disk.ext4 (0600): a copy of vm.rootfs grown to the conversation’s disk_gib (vm.disk_gib unless a grant raised it; disks only grow). It holds /home/agent/work (the agent’s project directory), the harness’s session files, the agent’s own mcp.json and memory, and the provisioning marker, and survives idle stops, sleeps, restarts and harness restarts.
Read more Internet
Model provider The model API set as each [[llm]] entry’s upstream (for example Anthropic or OpenAI). Only the host proxy talks to it, over HTTPS with the operator’s key.
A guest can call any path on its upstream with that key: use provider-side spend limits Read more Internet
Guest internet access (optional) With vm.network = "nat" each guest gets a tap device and NAT to the internet (packages, git, …). Gopala installs no filtering rules; add nftables rules yourself. With "none" this path doesn’t exist.
Read more Inside each microVM
Firecracker microVM One KVM-isolated microVM per running conversation, at most vm.max_vms at once, booted on demand and stopped when idle. Sized by vm.vcpus and vm.memory_mib, with no network or tap + NAT. Everything inside is untrusted; no secret ever enters it.
firecracker --no-api with a config file, empty environment Optional jailer: chroot, unprivileged uid/gid, cgroups v2 Read more Trust boundary B1
Platforms → host What crosses it: Chat events from any member of any conversation the agent is in, on any enabled platform, delivered by its provider.
Controls: Policy (behavior.*), approver checks, commands handled on the host, content passed to the agent as text only. Other agents’ messages wake it only by mention or reply, capped per hour, and never count as commands or approval answers.
Read more Trust boundary B2
Viewers and apps → web server (/watch, /monitor) What crosses it: Websocket frames and HTTP requests from anyone who can reach [server].bind: viewers on /watch, apps on /monitor and /api/monitor/.
Controls: TLS (tls_cert / tls_key, or a TLS-terminating proxy); a credential first (watch token, verified Lupyd token or admin token); membership asked of the platform and [monitoring] rules for output and metrics, checked again when the cached answer expires; 404 for conversations the caller isn’t in; read-only protocols, deadlines, rate, size and subscription limits.
Read more Trust boundary B3
Guest → host What crosses it: Control frames (including resource usage), MCP calls (including requests for more resources) and HTTP to the model proxy, from a VM that may run arbitrary root code.
Controls: Scope derived from the socket, frame limits, validation, rate limits on chat output, credential stripping; resource requests are decided by the host against its maximums, budget and grant policy.
Read more Trust boundary B4
Guest → hypervisor What crosses it: KVM exits and virtio devices.
Controls: Firecracker’s minimal device model and seccomp, optionally the jailer (chroot, uid/gid, cgroups, namespaces).
Read more Trust boundary B5
Host → model providers What crosses it: Proxied model requests carrying the operator’s API key.
Controls: A fixed upstream per proxy, HTTPS via rustls, no redirects followed.
Read more Trust boundary B6
Guest → internet What crosses it: Arbitrary IP traffic, in NAT mode only.
Controls: vm.network = "none", or host firewall rules you add (Gopala installs none).
Read more Trust boundary B7
Browser → config API What crosses it: HTTP requests from anyone who can reach [server].bind: the static site, GET /api/status and sign-in, and the operator’s endpoints (dashboard API, GET / PUT /api/config and the config helpers).
Controls: Everything but the static site, /api/status and sign-in needs Authorization: Bearer with the token from admin_token_env or the session cookie (401 otherwise; 403 when none is configured; cookie writes need X-Gopala: 1); repeated wrong tokens lock the address out. The helpers never touch the file. Bodies capped at 256 KiB.
Read more