References
Gopala runs autonomous AI agents on your own servers. These are the outside projects, protocols and specifications it builds on, and what each one is used for.
Lupyd and Firefly (the Lupyd provider)
Section titled “Lupyd and Firefly (the Lupyd provider)”- Lupyd: https://lupyd.com. The social platform whose provider ships with Gopala.
- Firefly:
lupyd/firefly. Lupyd’s end-to-end encrypted group chat (server, core, clients). The Lupyd provider usesfirefly-mcp,firefly-clientandfirefly-protosat git revisionf9a0960; nothing else in Gopala links Firefly. - firefly-mcp:
crates/mcpinlupyd/firefly. Reused for Lupyd sign-in (firefly_mcp::auth::Auth), the bot’s device (firefly_mcp::agent::Agent), the event log (firefly_mcp::events), and message encoding and folding (firefly_mcp::content). Its tool set is the model for Gopala’s MCP server. - firefly-client:
crates/clientinlupyd/firefly. The device, message stores and full-text search used by the Lupyd provider. - RFC 9420: The Messaging Layer Security (MLS) Protocol: https://www.rfc-editor.org/rfc/rfc9420. The group key agreement Firefly uses; the reason chat content is end-to-end encrypted and why the rooms may later move onto Firefly.
Sign-in (Auth0)
Section titled “Sign-in (Auth0)”- Resource Owner Password Flow:
https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow,
and calling an API with it (password-realm grant):
https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow.
firefly-mcp signs in once with
grant_type = http://auth0.com/oauth/grant-type/password-realmand scopeopenid profile email offline_access(platforms.lupyd.auth0_realmselects the realm). - Refresh tokens: https://auth0.com/docs/secure/tokens/refresh-tokens. Kept in
<data_dir>/lupyd/session.jsonso the password is needed only once. - JSON Web Key Sets: https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets.
Where
{auth0_domain}/.well-known/jwks.jsoncomes from; Gopala checks Lupyd sign-in tokens on/monitoragainst it. - Validate access tokens: https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens.
The issuer, audience and expiry checks
auth::LupydTokens::verifyapplies.
Slack (the Slack provider)
Section titled “Slack (the Slack provider)”- slack-morphism: https://github.com/abdolence/slack-morphism-rust, https://docs.rs/slack-morphism. The Web API client and the Socket Mode listener in the Slack provider.
- Socket Mode: https://docs.slack.dev/apis/events-api/using-socket-mode. Events over an
outbound WebSocket, so the host needs no public URL; it needs an app-level token with
connections:write. - Tokens: https://docs.slack.dev/authentication/tokens. The bot token (
xoxb-) and the app-level token (xapp-) in[platforms.slack]. - App manifests: https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests and the manifest reference. The format of the Slack app manifest shown on the Create an Agent page.
- chat.postMessage: https://docs.slack.dev/reference/methods/chat.postMessage. Sending
replies,
thread_tsfor threads,markdown_text. - Formatting text: https://docs.slack.dev/messaging/formatting-message-text. mrkdwn escaping
and
<@U…>mentions (the Slack provider’s text formatting). - Rate limits: https://docs.slack.dev/apis/web-api/rate-limits. Retried by slack-morphism’s rate control.
- usergroups.list: https://docs.slack.dev/reference/methods/usergroups.list, scope
usergroups:read. Resolvingrole:<handle>alerts to<!subteam^ID>.
Discord (the Discord provider)
Section titled “Discord (the Discord provider)”- twilight: https://twilight.rs/, API docs https://api.twilight.rs/twilight_gateway/index.html
and https://docs.rs/twilight-gateway.
twilight-gateway,twilight-http,twilight-modelandtwilight-cache-inmemory0.18 in the Discord provider. - Gateway and intents: https://docs.discord.com/developers/events/gateway. The intents Gopala asks for, including the privileged Message Content and (optional) Server Members intents.
- Privileged intents: https://docs.discord.com/developers/gateway/getting-started-with-privileged-intent-review.
- Gateway close codes: https://docs.discord.com/developers/topics/opcodes-and-status-codes.
4004, 4010 to 4014, which
close_reasonturns into a fatal error with instructions. - Permissions: https://docs.discord.com/developers/topics/permissions. The bits behind
PERMISSIONS(274878106688). - OAuth2 bot authorization: https://docs.discord.com/developers/topics/oauth2. The invite
link
invite_urlbuilds. - Messages and allowed mentions: https://docs.discord.com/developers/resources/message.
allowed_mentions, which limits a notifying message’s pings to exactly its audience.
Firecracker
Section titled “Firecracker”- Firecracker: https://firecracker-microvm.github.io/; source and releases https://github.com/firecracker-microvm/firecracker, https://github.com/firecracker-microvm/firecracker/releases.
- Getting started:
https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md. KVM
access, binaries,
--config-fileand--no-apistyle launches as inPreparedVm::boot. - vsock: https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md. The
uds_pathand the{uds_path}_{port}convention for guest-initiated connections that the control, MCP and proxy channels use. - Jailer: https://github.com/firecracker-microvm/firecracker/blob/main/docs/jailer.md.
Chroot layout
<chroot_base>/<exec name>/<id>/root, uid/gid, cgroups (jailer_args,setup_chroot). - Network setup:
https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md. Tap
devices and NAT, as in
setup_tapand the masquerade rule fornetwork = "nat". - Production host setup: https://github.com/firecracker-microvm/firecracker/blob/main/docs/prod-host-setup.md. Host hardening recommendations referenced by the security checklist.
- Rootfs and kernel setup:
https://github.com/firecracker-microvm/firecracker/blob/main/docs/rootfs-and-kernel-setup.md.
Background for the rootfs build in
gopala image build, which uses Firecracker’s CI kernel and Ubuntu image. - debootstrap: https://wiki.debian.org/Debootstrap. Builds the Debian 12 base
(
[image] base = "debian-12"). - vsock(7): https://man7.org/linux/man-pages/man7/vsock.7.html.
AF_VSOCK, CIDs (host = 2). - ip(8) (iproute2): https://man7.org/linux/man-pages/man8/ip.8.html.
ip tuntap,ip addr,ip linkused for tap devices. - capabilities(7): https://man7.org/linux/man-pages/man7/capabilities.7.html.
CAP_NET_ADMINfor taps, ambient capabilities in the systemd unit. - nftables NAT: https://wiki.nftables.org/wiki-nftables/index.php/Performing_Network_Address_Translation_(NAT).
- cgroup v2: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html. Values for
vm.jailer.cgroups. - systemd.exec(5): https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html. Directives in the example units.
- sudoers(5): https://www.sudo.ws/docs/man/sudoers.man/. The rules the guest writes to
/etc/sudoers.d/gopala.
Egress proxy
Section titled “Egress proxy”- RFC 9110: HTTP Semantics: https://www.rfc-editor.org/rfc/rfc9110.
CONNECT(section 9.3.6) for tunnels and absolute-form targets for plain HTTP through a proxy. - IANA special-purpose address registries:
https://www.iana.org/assignments/iana-ipv4-special-registry/ and
https://www.iana.org/assignments/iana-ipv6-special-registry/. The ranges
egress::is_publicrefuses. - RFC 6052 (NAT64 prefix): https://www.rfc-editor.org/rfc/rfc6052 and RFC 3056 (6to4):
https://www.rfc-editor.org/rfc/rfc3056. IPv6 addresses that embed an IPv4 destination, which
is_publicchecks too.
Agent harnesses (omp, Claude Code, exec)
Section titled “Agent harnesses (omp, Claude Code, exec)”- omp: https://omp.sh/. The agent harness run in each VM.
- RPC mode: https://omp.sh/docs/rpc.
--mode rpc,ready,negotiate_protocol,rpc_chunk,prompt/steer/follow_up/abort,agent_end/prompt_result, subagent subscriptions, and theextension_ui_request/extension_ui_responsesub-protocol (the guest agent’s omp harness). - CLI: https://omp.sh/docs/cli.
-c/--continue,--append-system-prompt,--approval-mode,--tools/--no-tools(agent.tools). - MCP configuration: https://omp.sh/docs/mcp.
~/.omp/agent/mcp.jsonand the portable.mcp.jsonthe guest writes, withstdioandhttpservers. - Environment variables: https://omp.sh/docs/env.
ANTHROPIC_BASE_URL,OPENAI_BASE_URL,PI_SMOL_MODELand friends used inguest_env/agent.env. - Claude Code headless mode: https://code.claude.com/docs/en/headless.
claude -p,--input-format/--output-format stream-json,--continue,--append-system-prompt-file,--mcp-config/--strict-mcp-config,--permission-mode bypassPermissions(the guest agent’s Claude Code harness). - Claude Agent SDK message types: https://code.claude.com/docs/en/agent-sdk/typescript.
The
SDKMessageshapes (systemwithinit,api_retry,compact_boundary;assistant,user,result) and the user messagepriority, checked for Claude Code 2.1.319. - Codex CLI non-interactive mode: https://developers.openai.com/codex/noninteractive.
codex exec -,--sandbox,--skip-git-repo-check, for the exec recipe in operations.md.
Model Context Protocol
Section titled “Model Context Protocol”- MCP: https://modelcontextprotocol.io/; specification
https://modelcontextprotocol.io/specification/2025-06-18. Tools, JSON-RPC, the stdio
transport, and the streamable HTTP transport
that
[[agent.mcp]] urlservers speak through the host’s proxy. - rmcp (official Rust SDK): https://github.com/modelcontextprotocol/rust-sdk, docs
https://docs.rs/rmcp.
ScopedMcp’s server (#[tool_router],#[tool]) and the test client. - schemars: https://docs.rs/schemars. JSON Schemas of tool parameters and of
gopala.toml(/api/config/schema).
Wire formats and framing
Section titled “Wire formats and framing”- quick-protobuf: https://github.com/tafia/quick-protobuf, https://docs.rs/quick-protobuf. Encoding and decoding of every protobuf message.
- pb-rs: https://docs.rs/pb-rs. Code generation for the wire schema.
- Protocol Buffers (proto3): https://protobuf.dev/programming-guides/proto3/.
- tokio-util
LengthDelimitedCodec: https://docs.rs/tokio-util/latest/tokio_util/codec/length_delimited/index.html. The control channel framing (gopala_proto::codec). - tokio-util
LinesCodec: https://docs.rs/tokio-util/latest/tokio_util/codec/struct.LinesCodec.html. Bounded line reading of harness output (sys::Lines).
Storage and configuration
Section titled “Storage and configuration”- sqlx: https://github.com/launchbadge/sqlx, https://docs.rs/sqlx. SQLite pool and
migrations for
rooms.db. - SQLite write-ahead logging: https://www.sqlite.org/wal.html. Journal mode of
rooms.dband of each agent’smemory.db. - toml_edit: https://docs.rs/toml_edit. Editing one
[[budget.conversations]]or[[behavior.conversations]]entry ingopala.tomlwhile keeping the operator’s comments and layout (control::edit_conversation_entry).
Agent memory
Section titled “Agent memory”- rusqlite: https://github.com/rusqlite/rusqlite, https://docs.rs/rusqlite. SQLite for
gopala-memory, with thebundledfeature so SQLite (and FTS5) is compiled into the guest. - SQLite FTS5: https://www.sqlite.org/fts5.html. The external-content full-text index and
its
bm25()ranking used byrecalland near-duplicate detection. - Reciprocal rank fusion: Cormack, Clarke and Büttcher, “Reciprocal Rank Fusion outperforms
Condorcet and individual Rank Learning Methods” (SIGIR 2009),
https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf. How
recallmerges BM25, cosine and entity lists (k = 60). - mem0: https://docs.mem0.ai/core-concepts/how-it-works and the paper “Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory”, https://arxiv.org/abs/2504.19413. The reference design: atomic facts, dedupe on write, entity links, hybrid retrieval, and the merge/update/delete vocabulary the compaction prompt borrows. Gopala leaves out mem0’s model call on every write.
- OpenAI embeddings API: https://platform.openai.com/docs/api-reference/embeddings. The
/v1/embeddingsrequest[memory.embeddings]sends through an[[llm]]proxy.
Cryptography
Section titled “Cryptography”- chacha20poly1305 (XChaCha20-Poly1305): https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305, https://docs.rs/chacha20poly1305. Room key wrapping and event sealing.
- XChaCha20 draft: https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha. The 24-byte-nonce construction that makes random nonces safe.
- hkdf: https://github.com/RustCrypto/KDFs/tree/master/hkdf, https://docs.rs/hkdf. Key-wrapping key derivation.
- RFC 5869: HKDF: https://www.rfc-editor.org/rfc/rfc5869.
- subtle: https://docs.rs/subtle. Constant-time token hash comparison.
- zeroize: https://docs.rs/zeroize. Wiping secrets, tokens and keys from memory.
- jsonwebtoken: https://github.com/Keats/jsonwebtoken, https://docs.rs/jsonwebtoken. Decoding and verifying Lupyd’s RS256 tokens and parsing its key set (the web server’s sign-in).
- RFC 7519: JSON Web Token: https://www.rfc-editor.org/rfc/rfc7519; RFC 7517: JSON Web
Key: https://www.rfc-editor.org/rfc/rfc7517; RFC 8725: JWT Best Current Practices:
https://www.rfc-editor.org/rfc/rfc8725. Why only RS256 with a named key is accepted and why
iss,audandexpare required.
Networking and HTTP
Section titled “Networking and HTTP”- rustls: https://github.com/rustls/rustls; tokio-rustls: https://docs.rs/tokio-rustls.
TLS for the web server (site, config API,
/watch), upstream model APIs and MCP servers (through reqwest), Slack and Discord. - tokio-tungstenite: https://github.com/snapview/tokio-tungstenite. The watch websocket server and client.
- RFC 6455: The WebSocket Protocol: https://www.rfc-editor.org/rfc/rfc6455.
- hyper: https://hyper.rs/. HTTP/1 for the web server, the LLM proxy’s server and the egress proxy (server side, and the client side of forwarded plain-HTTP requests).
- axum: https://docs.rs/axum. Routing for the web server.
- tower-http: https://docs.rs/tower-http. Static file serving (
ServeDir) and security headers (SetResponseHeaderLayer). - reqwest: https://docs.rs/reqwest. The upstream client of the LLM proxy and the HTTP MCP proxies.
- tokio: https://github.com/tokio-rs/tokio;
broadcastchannels for live fan-out https://docs.rs/tokio/latest/tokio/sync/broadcast/index.html. - tokio-vsock: https://docs.rs/tokio-vsock. Guest-side vsock connections.
Other crates
Section titled “Other crates”- governor: https://github.com/boinkor-net/governor, https://docs.rs/governor. Outgoing chat rate limit per conversation, the guest’s log-line rate limit, the egress proxy’s notice rate limit, and the admin sign-in lockout.
- arc-swap: https://docs.rs/arc-swap. The hot-reloadable running configuration
(
LiveConfig). - nix: https://docs.rs/nix. Dropping privileges,
chown,rebootand mounting the tools drive in the guest;statvfson host and guest. - which: https://docs.rs/which. Resolving the harness binary on the agent’s
PATH.
Website
Section titled “Website”- Astro: https://docs.astro.build/; Starlight: https://starlight.astro.build/. The static site and the rendered docs.
- Alpine.js: https://alpinejs.dev/. The dashboard’s, templates’ and configuration editor’s
reactivity (
@alpinejs/cspbuild). - Server-sent events: https://html.spec.whatwg.org/multipage/server-sent-events.html. The
dashboard’s live stream (
/api/stream). - Cookies:
HttpOnly,SameSite: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies. The dashboard session cookie.
Model provider usage reports
Section titled “Model provider usage reports”The LLM proxy reads token counts from these response fields:
- Anthropic Messages: https://docs.anthropic.com/en/api/messages (
usage, including streamingmessage_start/message_delta). - OpenAI Chat Completions: https://platform.openai.com/docs/api-reference/chat (
usage; streams report it only withstream_options.include_usage). - OpenAI Responses: https://platform.openai.com/docs/api-reference/responses (
usage). - Gemini: https://ai.google.dev/api/generate-content (
usageMetadata).