Security
How Gopala contains autonomous agents on your own servers: the threat model, trust boundaries, built-in mitigations and what to harden before production.
Protocol details are in protocols.md; deployment steps in operations.md.
Nothing here has been validated against a real Firecracker boot or a live Lupyd, Slack or Discord account; the mitigations are implemented and unit/integration tested with fakes. Statements marked [inference] follow from reading the code but are not tested.
Assets
Section titled “Assets”| Asset | Where | Why it matters |
|---|---|---|
| Platform credentials | Lupyd: the variables named by platforms.lupyd.email_env / password_env (startup only), refresh token in <data_dir>/lupyd/session.json; Slack: the bot (xoxb-) and app-level (xapp-) tokens; Discord: the bot token (environment at startup, then host memory) |
Full control of the bot’s identity on the platform |
| The bot’s device state and message store | Lupyd: <data_dir>/lupyd/firefly.db (MLS state). Slack and Discord keep nothing on disk |
Decrypts and impersonates the bot in every conversation it is in |
| Conversation contents | the platform (end-to-end encrypted on Lupyd; readable by Slack and Discord themselves), the provider’s local store or cache, each VM via MCP | Private group and DM content |
| Model API keys | Host environment ([[llm]].secret_env), host memory |
Money and quota; access to the provider account |
| Code hosting tokens | Host environment ([[git]].token_env), host memory |
Reads and writes every repository the token reaches on GitHub, GitLab or Gitea |
| HTTP MCP server credentials | Host environment (agent.mcp secret_env), host memory |
Access to whatever those servers front (issue trackers, internal tools) |
| The admin token and dashboard sessions | Host environment (server.admin_token_env, default GOPALA_ADMIN_TOKEN), host memory; session ids in browsers’ HttpOnly cookies and the server’s memory |
Reads and replaces gopala.toml (part of it applied at once), controls every conversation (abort, sleep, restart, leave, allocations), reads every journal and the usage ledger |
| The configuration file | the --config path (and <path>.bak) |
Controls binaries run, upstreams keys are sent to, policies |
| Agent session telemetry | <data_dir>/rooms/rooms.db (plaintext), live websocket, the dashboard’s activity stream |
Contains what the agent read, thought and ran, including conversation content |
| The agent’s memory | /home/agent/.gopala/memory.db inside each VM’s disk (owned by the agent) |
Facts the agent kept about the conversation and its people; only that conversation’s agent reads it |
| Usage records and budgets | <data_dir>/usage.db, [budget] |
Who used how much, and when model calls stop: the basis for budgets and billing, so it must not come from the agent |
| The harness and tools | vm.tools_image on the host |
What drives every agent and what it trusts (git) |
| Watch tokens and room keys | Viewers’ direct chats; rooms.db stores hash + derived wrapping key; room keys in host memory |
Read access to telemetry |
| People’s Lupyd sign-in tokens | Held by the Lupyd app, sent to /monitor; the host keeps only the username and expiry of a verified token |
Reads the agents of every Lupyd conversation that person is in, as far as [monitoring] allows |
| Each conversation’s workspace | <data_dir>/vms/<key>/disk.ext4 |
Code, data and tool state the agent produced |
| Host capacity | CPU, memory, the filesystem holding data_dir |
Shared by every VM; exhaustion affects all conversations |
| The host | Root (with the jailer) or a user with CAP_NET_ADMIN and KVM |
Compromise exposes everything above |
Adversaries
Section titled “Adversaries”| Adversary | Capabilities assumed | Goals |
|---|---|---|
| Malicious group member | Can post, edit, react, reply, invite the bot, leave and rejoin; may be an approver under approvers = "members" |
Make the agent do something harmful (prompt injection), approve critical actions or resource grants, read other conversations, flood the bot, keep watching after leaving |
| Another agent in the group | A bot account or a holder of collaboration.agent_role, possibly compromised or prompt-injected itself; can mention the bot, reply to it and post like a member |
Steer this agent through a “request”, borrow its authority (commands, approvals), keep it busy in a loop, burn its token budget |
| Compromised guest / agent | Arbitrary root code inside one VM (prompt injection, malicious package, harness bug); can speak any bytes on its vsock ports; with network = "nat" reaches the internet, with "proxy" the allowed hosts |
Escape the VM, reach other conversations or the host’s network, steal keys, impersonate the bot elsewhere, exhaust host resources (memory, disk, slots, tokens), spam the chat |
| Network attacker | Can observe and modify traffic between browsers/viewers and the web server, or between the host and upstreams | Read telemetry, steal watch or admin tokens, tamper with events or the config |
| Malicious viewer | Holds or guesses a watch token, sends arbitrary websocket frames | Read other rooms, keep access after revocation, exhaust the server |
| Outsider with an app | Can reach /monitor and /api/monitor/, may hold a valid Lupyd account or a forged or stolen token |
Read the agent output or metrics of conversations they aren’t in, learn which conversations exist, keep reading after being removed, exhaust the server |
| Web client without the admin token | Can reach the web server, possibly from another site in a signed-in admin’s browser | Read or change the configuration, act on conversations, guess the token, exhaust the server |
| Operator mistakes | Misconfiguration | Plaintext server on a public address, permissive data_dir, secrets in agent.env or a stdio MCP server’s args/env, a weak or leaked admin token, generous resource maximums or budgets, broad allowed_hosts, nat without egress filtering, running without the jailer |
Out of scope: a malicious chat platform itself (on Lupyd, covered by Firefly’s MLS design; Slack and Discord see every message by design), and a malicious host operator (they hold all keys by design).
Trust boundaries
Section titled “Trust boundaries”flowchart LR
subgraph Internet
P[platform users<br/>incl. malicious members]
V[viewers]
M[apps on /monitor]
A[admin browser / curl]
UP[model providers]
NET[(arbitrary hosts)]
AH[(allowed hosts)]
MS[(HTTP MCP servers)]
end
subgraph Host["host (trusted)"]
D[gopala daemon<br/>credentials, device state,<br/>API keys, MCP secrets, admin token, rooms.db]
CFG[(gopala.toml)]
FC[firecracker / jailer<br/>per VM]
end
subgraph G1["VM: lupyd-g-42 (untrusted)"]
A1[agent + harness, root inside]
end
subgraph G2["VM: lupyd-d-… (untrusted)"]
A2[agent + harness]
end
P -- "B1: platform provider<br/>(content is untrusted input)" --> D
V -- "B2: /watch ws(s) + token<br/>(read-only)" --> D
A -- "B7: /api over HTTP(S)<br/>Bearer admin token" --> D
M -- "B10: /monitor, /api/monitor<br/>token + membership" --> D
D -- "PUT /api/config" --> CFG
A1 -- "B3: vsock 1024/1025/1090/1100+i/1200+i/1300+i<br/>scope = socket" --> D
A2 -- "B3" --> D
FC -. "B4: KVM, jailer" .- A1
FC -. "B4" .- A2
D -- "B5: HTTPS, key added" --> UP
D -- "B8: egress proxy<br/>(network = proxy)" --> AH
D -- "B9: MCP proxy,<br/>secret added" --> MS
A1 -- "B6: tap + NAT<br/>(network = nat)" --> NET
| Boundary | Crossing | Controls |
|---|---|---|
| B1 platform → host | Chat events from any member | Provider-computed mentions_bot/addressed_text/from_agent, 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 as commands or approval answers |
| B2 viewer → host | Websocket frames at /watch |
TLS, token verification, membership and [monitoring] output checked at hello and on cache expiry, read-only protocol, size and time limits |
| B3 guest → host | Control frames, MCP calls (chat and VM tools), HTTP to the model, egress and MCP proxies | Socket-derived scope, frame limits, validation, rate limits on chat output, resource decisions and token budgets on the host, credential stripping |
| B4 guest → hypervisor | KVM exits, virtio devices | Firecracker’s minimal device model and seccomp, optional jailer (chroot, uid/gid, cgroups, namespaces) |
| B5 host → providers | Proxied model requests | Fixed upstream per proxy, HTTPS via rustls, no redirects |
| B6 guest → internet | Arbitrary IP traffic (network = "nat" only) |
network = "proxy" or "none", or host firewall rules you add |
| B7 admin → host | Dashboard and config API requests | TLS/loopback rule, admin token from the environment (Bearer or an HttpOnly, SameSite=Strict session cookie plus X-Gopala: 1 on writes), constant-time compare, lockout after repeated failures, header and TLS timeouts, validation before writing, body limit |
| B8 guest → allowed hosts | CONNECT tunnels and plain-HTTP requests through the egress proxy (network = "proxy") |
vm.allowed_hosts, host-side DNS, public addresses only, connect to the vetted address, connection and time limits, journaled and rate-limited notices |
| B9 guest → HTTP MCP servers | MCP requests to an operator-configured URL | Fixed origin per server, guest credential headers dropped, secret added on the host, no redirects, body and connection limits |
| B10 app → host | Protobuf requests on /monitor, HTTP on /api/monitor/ |
TLS, authentication before anything (admin token, watch token or a verified Lupyd JWT), membership asked of the platform, [monitoring] rules per capability, 404 for conversations the caller isn’t in, rate limit, frame and subscription limits, re-checks while subscribed |
Mitigations
Section titled “Mitigations”Isolation of conversations
Section titled “Isolation of conversations”- One VM per conversation, keyed by
ConversationId::key, each with its own disk (<data_dir>/vms/<key>/disk.ext4), allocation, vsock CID and host sockets, plus, withnetwork = "nat", a tap device and /30 subnet (the VM launcher’snat_addrs,tap_name,firecracker_config). - Scope from the socket. Each VM gets its own host sockets
{uds}_{port}, bound by the session that owns that conversation (session::run_vm).ScopedMcpis built with that oneHostConversationand itsVmControl(session::serve_mcp); no tool takes a platform, conversation id, username or scope (the chat tools’ parameter structs). Message and channel ids are resolved inside the conversation by its provider (HostConversation::channel,check_own). - Guest-initiated vsock only. The host never connects into a guest; Firecracker maps guest connections only to sockets the host bound (control, MCP, configured proxies, the egress proxy in proxy mode).
- Keys are validated as
[a-z0-9-]{1,48}before they become paths (validate_id,valid_scope); direct-chat keys (and non-trivial group ids) are hashes, so usernames and platform ids never become paths.
Hypervisor hardening
Section titled “Hypervisor hardening”- Firecracker runs with
--no-apiand a config file, so there is no API socket to abuse (PreparedVm::boot). - The VMM’s environment is cleared except
PATH(cmd.env_clear()); stdin is/dev/null. - With
[vm.jailer]: the jailer runs firecracker in a chroot underchroot_baseas a non-root uid/gid (Config::validaterejects 0), optionally in cgroup v2 limits (jailer_args). The chroot holds only hard links to the kernel and disk plus the config and sockets (setup_chroot); disk, config and sockets are chowned to the jailer uid/gid; the chroot is removed when the VM stops. - Files are private:
data_dir0700 (warned about otherwise,daemon::create_private_dir),vms/<key>0700, disk,allocation.json,vm.json,console.logand sockets 0600. - Every host resource a VM uses is cleaned up on stop or on drop (
Resources), including after failed prepares. - Console output is capped (
vm.console_log_max_kib) while both pipes keep draining (drain_console).
Resource limits
Section titled “Resource limits”- Agents can’t exceed the per-VM maximums.
machine::decidedenies any request abovevm.max_vcpus,vm.max_memory_miborvm.max_disk_gib, below 1 vCPU / 128 MiB, or with more memory than the host’s whole memory budget. A savedallocation.jsonis clamped to the current maximums and budget when loaded (VmControl::new), so lowering a maximum takes effect at the next boot even for earlier grants.VmManager::prepare_withrejects zero sizes again. - A shared memory budget. Every running VM holds its memory in
Shared::memory(session::Permitsovermemory_budget_mib, default 80% of host RAM), so all running VMs together never get more than the budget; others wait to boot (“waiting for host memory”), higher budget priority first.vm.max_vmsstill caps slots, handed out the same way. - Token budgets.
[budget]limits model tokens per conversation and for the host, per UTC day and month. The LLM proxy asks before forwarding each call; a refused call gets429 budget_exceededand never leaves the host. Usage comes from the host’s ledger, so a guest can’t reset or misreport it. Low- and normal-priority conversations stop at a share of the host budget (70% and 90% by default), which keeps the rest for high-priority ones. - Host disk reserve. Disk growth is denied when it would leave less than
vm.min_free_disk_gibfree on the filesystem holdingdata_dir. - Disks only grow (
decidedenies smaller disks;ensure_disknever shrinks), so a request can never truncate a workspace. - Who decides growth.
vm.grants:auto(within the limits above),approval(the conversation’s approvers answer a yes/no question through the normal approval flow, subject toapprovals.approvers, the open-approval cap and the rate limit; no answer means no), ornever. Giving resources back is always granted without approval. - Audit trail. Every grant, denial, restart and sleep request is journaled as
EVENT_NOTICE "resources"with the agent’s reason, visible to watchers. - Requests are validated before deciding (
ScopedMcp::request_resources: at least one value, a non-empty reason);restart_vmandsleep_vmonly affect the caller’s own VM.
Secrets stay on the host
Section titled “Secrets stay on the host”- Platform credentials (Lupyd: the variables named by
email_env/password_env; Slack:bot_token_env,app_token_env; Discord:token_env), every[[llm]].secret_env, everyagent.mcpsecret_env, every[[git]].token_env, the admin token andGOPALA_WATCH_LINKare read once and removed from the process environment (take_env,PlatformCredentials::take,egress::mcp_secrets), held inZeroizingbuffers. Lupyd’s credentials are dropped after sign-in; after the first Lupyd sign-in only the refresh token insession.json(0600, firefly-mcpAuth) is needed. slack-morphism and twilight keep their own plainStringcopies of the Slack and Discord tokens for as long as the provider runs (Slack::connect,Discord::connect). - Model keys are added by the host proxy (
llm_proxy::forwarded_headers); guests get placeholder keys and a127.0.0.1base URL. The proxy strips every credential header the guest sends (dropped) and the configured header, marks the injected value sensitive, accepts only origin-form targets (so a guest can’t point it at another host), forwards only to the configuredupstream, and never follows redirects (reqwest::redirect::Policy::none()). - HTTP MCP servers get their credential the same way: the host’s proxy for each server
(
egress::McpUpstream) drops every header a guest could carry a credential in (authorization,cookie,x-api-key,api-key,proxy-authorization, …), addsauth_header: auth_prefix + secretmarked sensitive, sends requests only to the configured origin and never follows redirects (one could carry the credential elsewhere). The guest seeshttp://127.0.0.1:3200+i/…. - Code hosting tokens never enter the VM: the host’s git proxy adds them to each request it forwards to the configured code host (see Code hosting).
- Stdio MCP servers (
[[agent.mcp]] command) run inside the VM, so theirargsandenvare visible to the agent;gopala.example.tomlsays to keep secrets out of them, and the config refusessecret_envon them. - The config file holds no secrets by design (only the names of environment variables);
agent.envis documented as “never secrets” (Agent::envin the config schema) and is copied into every VM. - Firecracker gets no host environment, so nothing secret reaches the VMM process either.
Untrusted guest input (control channel, MCP)
Section titled “Untrusted guest input (control channel, MCP)”- Frames are capped at 1 MiB (
gopala_proto::codec); a frame that doesn’t decode closes the connection (session::spawn_reader). The generated decoders are patched at build time (bound_nested_reads) so every nested message is read from its own sub-slice (gopala_proto::read_nested): stock quick-protobuf lets a nested reader see the whole buffer, and a field overrunning the nested message could panic or loop forever. Decoding is tested against such hostile bytes (protocol tests). The same decoders parse viewer frames. - The hello must come within 10 s and carry the expected
CONTROL_PROTOCOLon the first connection (session::handshake); the whole boot is bounded byvm.boot_timeout_secs. - Guest-supplied
seqis overwritten by the journal, which assigns sequence numbers per scope (run_vm,Rooms::publish); oversized events are truncated before storage. ResourceUsagereports are only stored as the latest sample (VmControl::record_usage); they inform the agent and/statusbut never drive a grant (decisions use the host’s ownstatvfsand budget). Percentages are computed with saturating arithmetic (usage_view).- Approval requests from a guest are cut to 10 options and their timeout is capped at
approvals.timeout_secs(run_vm); the MCP tool validates options and question (ScopedMcp::request_approval). At most 3 questions per conversation are open at once and each counts against the chat rate limit (HostConversation::request_approval,OpenSlot). - Outgoing chat from the agent is rate-limited per conversation
(
behavior.max_messages_per_minute, governor,HostConversation::send) and split tobehavior.max_message_chars; refusals are returned to the agent as tool errors. - Notifications are the operator’s call. The agent can only mark a message
warningorcritical; who that notifies comes from[alerts]on the host (HostConversation::audience), never from the agent. At mostalerts.max_per_hournotifying messages go out per conversation (default 4, host events included); past that, messages still go out but notify nobody, and the tool result tells the agent so. Direct chats never notify. Ordinary messages can’t ping everyone or roles on Discord (allowed_mentionsallows users only); on Slack the agent’s text goes out asmarkdown_text, which [inference] doesn’t trigger<!channel>the way mrkdwn does. On Lupyd an agent can still write@usernamelike any member. - The agent can edit and delete only its own messages (
HostConversation::check_own). - MCP list sizes are clamped (
read_messages≤ 100,wait_for_events≤ 500 events and ≤ 600 s,search_messages≤ 100). - Proxy request bodies are limited to 32 MiB (
MAX_REQUEST_BODY), buffered before forwarding; HTTP MCP request bodies to 16 MiB. Egress proxy request heads are limited to 16 KiB and 64 headers, 30 s to arrive.
Inside the VM: files root writes for the agent
Section titled “Inside the VM: files root writes for the agent”gopala-guest runs as root, and some of the paths it writes sit in the agent’s home, which the
agent controls: the harness’s MCP configs (/home/agent/.omp/agent/mcp.json,
/home/agent/work/.mcp.json, /home/agent/.gopala/claude-mcp.json), the empty
/home/agent/.gopala/mcp.json and the harness markers. restart_harness lets the agent trigger
those writes whenever it likes, so a planted symlink would turn them into root writes anywhere in
the VM, including the provisioning marker or the guest’s own files.
- No symlinks on the way.
sys::write_ownedopens every directory and the file withopenat2andRESOLVE_NO_SYMLINKS, creates missing directories, hands each to the agent and sets the file’s mode explicitly (O_CREAT’s mode only applies to a new file). A symlink anywhere in the path fails the write; the harness still starts, and the failure is logged. - Reads are checked too.
sys::read_ownedreads the agent’s own MCP file without following symlinks, only if it is a regular file owned by the agent’s account, and at most 64 KiB; anything else is left out whole and reported to the agent. - The merge can’t take over host servers. Names
chatandmemoryand every[[agent.mcp]]name are reserved, invalid entries are skipped, and at most 32 servers are taken (agent_config::merge).
This is a boundary inside the VM, between the agent’s account and root; the VM itself stays the
boundary to the host. Tested by users_and_owned_writes and
owned_reads_are_bounded_and_refuse_symlinks_and_strangers in the guest agent.
Servers the agent adds. They run inside the VM as the agent user, with exactly the rights the
agent already has; they add no host exposure. An HTTP server the agent adds is not proxied or
credentialed by the host: the harness connects to it directly, so it reaches only what
vm.network allows (anything with nat, the allowed hosts with proxy, nothing with none).
Only [[agent.mcp]] servers go through the host’s MCP proxy (B9). The system prompt tells the
agent secrets don’t belong in its file; it has none to put there anyway.
Claude Code without permission prompts. The Claude Code harness runs with
--permission-mode bypassPermissions. The VM is the sandbox, so asking before every shell
command would add friction without protecting the host; critical steps go through the
request_approval chat tool, which the host enforces (approvers, timeout, rate limit), and the
system prompt tells the agent to use it. Claude Code refuses this mode as root, and the harness
runs as the unprivileged agent account. Its only MCP config is the generated one
(--strict-mcp-config). Like omp, it comes from the read-only tools image when one is set, and
reaches the model only through the host’s LLM proxy.
Chat-side controls (malicious members)
Section titled “Chat-side controls (malicious members)”- Who can reach the bot:
behavior.direct_messagesdeclines direct messages (Router::admit_direct→Platform::admit_direct);behavior.invitesmakes the bot leave groups whose owner isn’t allowed, including groups joined while the policy was looser (Router::check_invite,check_joined_groups). - Who wakes it:
behavior.respond_to(policy::triggers); the provider decides what a mention is (Lupyd: whole usernames,gopala_lupyd::mentions). - Who answers approvals (including resource grants) and may
/stop:approvals.approvers(Router::is_approver). An answer must be a reply to the question or a reaction on it, or a bare reply while it is the only open request (Approvals::on_reply,on_reaction); no answer within the timeout is “no”. - Commands are handled by the host, not the agent, so
/watch,/stop,/statusand/listencan’t be forged by the agent or suppressed by prompt injection./listen(listening mode) takes an approver, like/stop; it changes how much of the group’s chat reaches the agent, soapprovers = "members"lets any member turn it on. - The system prompt tells the agent that only MCP-sent messages are visible, to ask approval
only for critical steps, and to be frugal with resources (
policy::system_prompt); this is guidance, not enforcement.
Other agents in a group
Section titled “Other agents in a group”Agents in one group can ping each other (see architecture.md). Another agent’s message is untrusted input, with less power than a person’s:
- A ping isn’t authority. It never runs
/watch,/stop,/status,/listenor/help, never answers an approval (neither a reply nor a reaction), and listening mode never lets one through (Router::on_message). The system prompt tells the agent a mention is a request it may decline, and that the agent the person asked owns the answer. - Only direct pings wake it. Providers drop agents’ messages that neither mention the bot
nor reply to it; the router checks again and ignores agents in direct chats, and every agent
message when
collaboration.enabled = false. - Rate-limited. At most
collaboration.max_agent_messages_per_hourwake-ups per conversation (default 30); the rest are dropped and logged. Two agents can’t keep each other busy, or burn each other’s token budget, beyond that. - Marked. Deliveries say
name (agent), so the agent knows who’s asking. - What
list_agentsexposes. Usernames, role names and bios of members the platform already shows to everyone in the group; at most 50, each bio at most 2000 characters. A bio is self-description and can carry a prompt injection like any message. - Who counts is the platform’s call. Anyone who can hand out the agent role (Lupyd group admins, Discord role managers, Slack user group admins) can mark an account as an agent. That only lowers what the account’s messages can do; it never raises it.
On Lupyd the bios come from GET {platforms.lupyd.profile_api_url}/user with the bot’s own Lupyd
access token, so that URL must be the Lupyd API (the default https://api.lupyd.com): whoever
serves it receives a token for the bot’s account. Config::validate only checks that it’s an
http(s) URL.
Watching (malicious viewers, network attackers)
Section titled “Watching (malicious viewers, network attackers)”- TLS:
server.tls_cert/tls_key(rustls).Config::validaterefuses a non-loopbackserver.bindwithout TLS unlessserver.allow_plaintextis set (for a TLS-terminating proxy on a private network).rooms.enabledrequiresserver.enabled. - Personal tokens: 256-bit random secret, 96-bit id (
token::issue); stored only as SHA-256 plus the derived wrapping key; compared in constant time (token::verify); expire afterrooms.token_ttl_secs; one per (conversation, user); delivered in a direct chat on the same platform (end-to-end encrypted on Lupyd); carried in the link fragment and the hello frame, never in a request URL.gopala watchprefersGOPALA_WATCH_LINKor stdin over a command-line argument (visible to other local users). - Read-only protocol: after hello a viewer can only send
ping; anything else closes the connection. Client frames are ≤ 4096 bytes (gopala_rooms::websocket_config, applied byweb::watch); the hello must arrive within 10 s of the upgrade; viewers per room are capped; a slow viewer is disconnected instead of buffering without bound (Rooms::viewer)./watchis served only ingopala runwith rooms enabled. - Sealed mode (
rooms.encryption = "sealed"): events are XChaCha20-Poly1305 sealed with a room key that each viewer receives wrapped under a key derived from their own token, with scope and epoch bound into the AAD. Keys rotate everykey_rotation_secsand on every revocation. - Revocation: when a member leaves a group, their tokens for it are deleted, their viewers are
disconnected (“access revoked”) and the room key rotates (
Rooms::revoke, called fromRouter::handleonEvent::MembersChanged). When the bot leaves, every token of the conversation is revoked (Rooms::revoke_scope). rooms.dband its directory are created 0600 / 0700 (db::open,Rooms::open).- A token isn’t the whole check. Under
gopala runthe holder must still be in the conversation and match[monitoring] output, asked when the viewer says hello and again whenever the membership answer expires (Rooms::viewer_authorized,web::watch_authorization).
Monitoring and endpoint authentication
Section titled “Monitoring and endpoint authentication”Every endpoint needs a credential except the static site, GET /api/status (which no longer
shows the version until signed in) and POST /api/session. That includes the configuration
helpers (schema, defaults, validate, normalize) and both monitoring channels.
- Three identities. The operator (admin token, or the dashboard’s session cookie); a watch token’s holder, limited to that one conversation; a person signed in to Lupyd, proven by Lupyd’s own Auth0 token. There is no account database on the host to steal.
- Lupyd tokens are verified, not trusted. RS256 only (no
none, no HMAC with a public key as secret), thekidmust name one of Lupyd’s published RSA signing keys, andiss,audandexpare required and checked,nbfwhen present, with 30 s of leeway; at most 8 KiB. The key set comes from{auth0_domain}/.well-known/jwks.jsonover HTTPS without redirects, capped at 64 KiB and 16 keys; an unknownkidcan cause at most one fetch a minute, so forged tokens can’t make the host hammer Auth0.monitoring.lupyd_tokens = falseturns this path off. - Membership is the authorization. A person reaches a conversation only if its platform says
they are in it now (
Platform::member), and only on that conversation’s platform.[monitoring]rules then grantoutputandmetricsseparately, by membership, approver status, ownership, role, platform permission or username; an empty list leaves it to the operator. A provider error counts as “not a member”. A provider that doesn’t implementmemberlets only the operator in. - Existence stays hidden. A conversation the caller isn’t in answers
404, exactly as one that doesn’t exist; only members the rules refuse get403.listreturns only conversations the caller may read. - Access ends when membership does. Answers are cached for
membership_cache_secs(default 60, at most 3600), but membership events drop them at once, and live subscriptions and/watchviewers check again then and whenever the cache expires. Expired Lupyd tokens and revoked watch tokens stop working on the next request. - Same lockout as the dashboard. Failed admin and watch tokens on
/monitorand/api/monitor/count towards the per-address lockout (more than 10 a minute →429for 60 s). Bad Lupyd tokens don’t count: they carry no secret of Gopala’s to guess. - Cross-site use of the cookie is refused. The session cookie works on the HTTP endpoints
(
SameSite=Strict) and opens/monitoronly when the upgrade has noOriginor one matchingHost. - Bounded. Client messages ≤ 16 KiB, authentication within 10 s, 20 requests a second (bursts
of 40) per connection, 16 subscriptions, a 256-message outbox per connection,
events≤ 500 per page.
The admin API and the dashboard
Section titled “The admin API and the dashboard”Implemented in the host’s web server.
- Token from the environment only. The admin token is read from the variable named by
server.admin_token_envand removed from the environment (take_env). Unset or empty disables every admin endpoint (403 admin API disabled);/api/statusreports only whether it is set and whether the request is signed in. - Constant-time comparison.
web::authorizeandPOST /api/sessioncompare the token withsubtle::ConstantTimeEq(a length mismatch fails without comparing contents); failures are401withWWW-Authenticate: Bearer. - Lockout. Wrong tokens count per client IP (
web::Guard, governor): more than 10 within a minute lock the address out for 60 s, during which sign-in and every admin request answer429withRetry-After, even with the right token. - Sessions instead of a stored token. Signing in exchanges the token for a random 256-bit
session id in an
HttpOnly,SameSite=Strict,Path=/cookie (Securewith TLS or anhttpspublic_url), valid 12 hours, kept only in server memory (at most 256). Page scripts can’t read it, andDELETE /api/sessionends it. Requests authenticated by the cookie that change something (notGET/HEAD) must carryX-Gopala: 1, which a cross-site form or a simple cross-origin request can’t add;SameSite=Strictkeeps the cookie off cross-site requests in the first place. - Slow clients. Request headers must arrive within 15 s (also ending idle keep-alive connections) and TLS handshakes finish within 10 s; request bodies are limited to 256 KiB.
- Only the admin sees state or acts.
/api/state,/api/stream, journals, usage, actions,GET/PUT /api/configand the configuration helpers (schema, defaults, validate, normalize) need the token or a session. Monitoring is the only way for anyone else, under the rules above. - Nothing invalid is written or applied.
PUT /api/configvalidates with the daemon’s ownConfig::parse, writes atomically (0600 temp file in the same directory, fsync,.bakcopy 0600, rename), then hot-applies onlybehavior,approvals,agent,budget,alerts,monitoring,collaborationand the VM limits, and only if the merged configuration validates (Control::apply); everything else waits for a restart.PUT …/budget,PUT …/behaviorand/listenedit one[[…conversations]]entry the same way (toml_edit, validated, atomic,.bak), all through one locked writer (control::ConfigFile), so concurrent saves can’t interleave. - Operator overrides stay within host limits.
PUT …/allocationskips the grants policy and approvals but not the per-VM maximums, the memory budget, the disk reserve or “disks only grow” (VmControl::operator_set). Every action is journaled as anoperatornotice. - Transport. The server-wide rule applies: TLS, loopback, or an explicit
allow_plaintextbehind a TLS proxy. State and configuration responses areCache-Control: no-store. - Browser hardening. Every response sets
X-Content-Type-Options: nosniff,Referrer-Policy: no-referrer,X-Frame-Options: DENYand aContent-Security-Policywithdefault-src 'self',connect-src 'self',font-src 'self',frame-ancestors 'none',form-action 'self'(scripts and styles from the site itself, inline allowed). - Stateless frontend. The site is static files from
server.site_dir(fonts self-hosted). The dashboard and configurator keep drafts and view state in the page; the server trusts nothing the page stores, and the token is only sent once, at sign-in (or as a Bearer header by scripts).
Metering and host-provided tools
Section titled “Metering and host-provided tools”- Usage is measured on the host. Token counts come from the provider’s own usage report in
the response the LLM proxy relays, which a guest can’t edit:
it never sees the upstream connection, and the proxy forces
accept-encoding: identityso the report can be read. CPU time and memory come from the firecracker process in/proc, disk from the image’s allocated blocks, network from the tap counters (RunningVm::sample). Tool calls, messages and boots are counted by the host code that performs them. The guest’s ownResourceUsageis shown only as “reported”, labelled unverified, and the dashboard flags large disagreements; it never feeds grants, budgets or the ledger. - The ledger is host-only.
usage.db(0600) is written by the host; no guest-facing interface reads or writes it. - Read-only, host-provided tools. With
vm.tools_image, the harness and git come from an image the host checks againstvm.tools_sha256atrunandcheck-config(gopala_vm::verify_tools: a regular file, readable by the jailer uid, matching hash), attaches withis_read_only: true, and the guest mounts read-only,nosuid,nodevat/opt/gopala. The guest refuses to start a harness the agent user could change (tools::writable_by), so a prompt-injected agent can’t swap the program that drives it. The harness still reaches models only through the host proxy (it gets placeholder keys). - Memory traffic is metered too. The memory server’s embeddings and the maintenance pass’s
compaction calls go through the same
[[llm]]proxies, so the host adds the key, counts the tokens and applies the conversation’s budget; the guest never holds a key for them.
The agent’s memory
Section titled “The agent’s memory”The memory store lives in the VM, on the conversation’s own disk, as
/home/agent/.gopala/memory.db (0600, directory 0700). The agent user owns it: its MCP servers
and the maintenance pass run as the agent (memory::spawn_maintenance starts a child process with
the agent’s uid, so root in the guest never opens files in the agent’s home). Treat it as the
agent’s notebook:
- The agent can change it at will, with the tools or with its shell. Nothing in it is evidence of what happened; the journal on the host is.
- It stays in its conversation. No other VM can reach the file, the host never reads it, and no tool takes a conversation; scope is the disk itself.
- Prompt injection can persist. Someone who steers the agent can make it remember something
false, and recall brings it back in later sessions.
updateandforgetremove it; deleting the conversation’s disk resets everything. - Bounded. Text ≤ 2 KiB, names ≤ 128 B, ≤ 16 entities and relations per memory, recall ≤ 50
results; the store archives and deletes by score under
max_memoriesandmax_db_mib, and a maintenance pass is killed after 30 minutes. - Compaction answers are untrusted. The model’s operations are validated strictly (ids from the cluster only, pinned memories kept, text within limits) and applied in one transaction, or not at all.
The server’s instructions tell the agent not to store secrets; that is guidance, not enforcement.
Network modes and the egress proxy
Section titled “Network modes and the egress proxy”vm.network (Network in the config schema) decides what a compromised guest can reach
besides the host’s vsock services:
| Mode | Reachable from the VM | Enforced by |
|---|---|---|
none |
nothing; no network device | Firecracker config without network-interfaces |
proxy |
host:port pairs in vm.allowed_hosts that resolve only to public addresses, over HTTP(S) |
the host’s egress proxy |
nat |
anything the host can route to | only firewall rules you add |
In proxy mode (egress::Egress):
- No device, no bypass. The VM has no network interface. Its only way out is the vsock port
1090 the host bound for it, so a program that ignores
HTTP_PROXYgets nowhere rather than around the filter. - Allowlist first.
Allowlist::allowsmatcheshostexactly or*.domainon subdomains, with the listed port, or 80/443 when none is given. Anything else is403and arefusednotice. - SSRF guard. The host resolves the name itself, and if any address is not public
(
egress::is_public: private, loopback, link-local, CGNAT, multicast, broadcast, reserved, documentation and benchmarking ranges, IPv6 ULA, site-local, Teredo, discard-only, and IPv4 addresses embedded in mapped, NAT64 or 6to4 IPv6 addresses), the whole name is refused. So an allowed name that points at127.0.0.1,169.254.169.254or the LAN is refused, and an IP literal in the list gets no exception. - DNS rebinding. The host connects to an address it just vetted, never resolving the name a second time, and every new connection is vetted again. A name that flips to a private address between connections is caught. What remains is a public address changing hands: an allowed name keeps working if its owner moves it to another public server.
- TLS stays end to end.
CONNECTtunnels carry bytes without inspecting them; the host sees only the target and the byte counts. - Bounded. At most 64 connections per VM (more are refused and journaled), 30 s for a request
head, heads ≤ 16 KiB, 10 s to connect, 300 s idle before a tunnel closes (
egress::Limits). - Visible. Every allowed and refused destination becomes a
networknotice in the journal, at most 30 a minute (bursts of 10), repeated refusals of the same target once a minute, with a count of what was held back; tunnel bytes go to the ledger asegress_bytes_up/down.
HTTP MCP servers are reached through the host in every mode (B9). Their URLs come from the
operator, so they are not checked against is_public: a URL on the host’s LAN works on purpose.
Code hosting ([[git]])
Section titled “Code hosting ([[git]])”Each [[git]] entry gives the VMs one GitHub, GitLab or Gitea account through the host’s git
proxy (vsock 1300+i on the host, 127.0.0.1:3300+i in the guest), in every vm.network mode.
- The token never enters the VM. It is read from
token_envat startup, removed from the environment and zeroized. The host adds it to each forwarded request; the guest’s git config only rewrites the code host’s URLs to the local forwarder, with an empty credential helper. - Header allowlist. Only
accept,accept-encoding,accept-language,content-type,content-encoding,git-protocol,user-agent,if-none-match,if-modified-sinceandx-github-api-versionare passed on, so a guest’sAuthorizationorCookieis dropped. - Response stripping.
set-cookie,www-authenticateand any header containing the token are removed from responses; the token is redacted from logs; redirects are not followed. - Path checks. Empty,
.or..segments (also as%2e) and backslashes are refused. Only git smart HTTP and the provider’s REST API base path are forwarded; everything else is404. - Repository allowlist. With
reposset, every git and API path must name an allowed repository. Numeric ids (GitLab/projects/<id>, GitHub/repositories/<id>) are refused with a hint to use the path, and API calls that name no repository areGET/HEADonly. - Protected branches on push. The host reads the push’s command list (at most 64 KiB) before
forwarding. Any create, update or delete of
refs/heads/<protected>refuses the whole push: git prints! [remote rejected] main -> main (protected by the Gopala host). Signed pushes (push-cert) and compressed push bodies are refused, since the host couldn’t check them. - Protected branches on the API. Deleting, force-updating or renaming a protected branch is refused. Endpoints that commit to a named branch (GitHub contents, merges, merge-upstream; GitLab files, commits, cherry_pick, revert; Gitea contents, diffpatch, merge-upstream) must name it in the body or query; leaving it out (the default branch) is refused.
- No merging. Merging a pull or merge request is always refused (GitHub
PUT pulls/{n}/merge, GitLabPUT merge_requests/{iid}/merge, GiteaPOST pulls/{n}/merge), as are GitHub GraphQL, GitLab’s delete-merged-branches and Rails_methodoverrides. A person reviews and merges. - Bounded. API bodies ≤ 10 MiB, pack uploads ≤ 2 GiB, 64 connections per account, 16 requests in flight per VM; 30 s for headers and to connect, 300 s read idle, 120 s per API call.
- Visible. Pushes, opened pull requests and refusals become
gitnotices in the journal (rate-limited); requests and bytes go to the ledger asgit_requests,git_bytes_up/down.
Residual risks
Section titled “Residual risks”| Risk | Detail | Mitigation available |
|---|---|---|
| The admin token is root-equivalent | Whoever holds it (or a signed-in browser session) can rewrite gopala.toml: vm.firecracker, vm.jailer.binary, vm.tools_image, agent.setup, [[llm]].upstream (where API keys are sent), policies. Policy, agent and VM limits apply at once; the rest when Gopala restarts, possibly as root with the jailer. It can also make the bot leave conversations and read every journal. |
Leave admin_token_env unset unless you need the dashboard or browser configuration; use a long random token; serve the API only over TLS or loopback; sign out of shared browsers; protect the config directory. |
| Token guessing | Mitigated: more than 10 wrong tokens per minute lock the client’s address out for 60 s. Behind a reverse proxy every client shares the proxy’s address, so an attacker can lock legitimate admins out for a minute at a time; an attacker with many addresses gets 10 guesses per minute per address. | A long random token (e.g. openssl rand -hex 32) makes guessing hopeless; rate-limit at the proxy as well. |
| Slow or idle HTTP clients | Mitigated: 15 s for request headers (and idle keep-alive), 10 s for TLS handshakes. Long-lived /api/stream and /watch connections are admin- or token-gated but not capped in number [inference]. |
A reverse proxy with connection limits for public deployments. |
| Metering gaps | Only traffic through the host is metered: with network = "nat" a guest can call other services directly (only tap bytes show it) until per-tap egress filtering exists (issue #6). A provider response without a usage report counts as a call with zero tokens, which budgets can’t see. |
network = "proxy" or "none"; provider-side spend limits; watch llm_requests against tokens. |
| Tools image integrity | The tools image is hashed when Gopala starts, not while VMs read it; someone who can write the file on the host between checks changes what every VM runs (no verity yet, issue #7). Without an image, the harness is whatever the VM installs and the agent can replace it. | Keep the image root-owned and read-only; use vm.tools_image in production. |
| Prompt injection by members | Anyone who can wake the agent can steer it; with approvers = "members" anyone can also approve, including resource grants under grants = "approval". The agent decides itself what is “critical”. |
Restrict respond_to, direct_messages, invites; approvers = "owner" or "allowlist"; keep sudo = false; an omp approval mode stricter than yolo in agent.args ([inference] omp’s confirm/select prompts then arrive as extension_ui_requests, which become chat approvals). Claude Code has no such setting here: it always runs with bypassPermissions. |
| Prompt injection by other agents | A compromised or misled agent can ask this one to do something harmful, and a bio in list_agents can carry instructions. It can’t run commands or answer approvals, and it gets at most max_agent_messages_per_hour wake-ups per conversation, but what the agent does with a request is its own decision. |
collaboration.enabled = false where agents shouldn’t talk; a low max_agent_messages_per_hour; give the agent role only to bots you trust; budgets per conversation. |
| Agent-added MCP servers | The agent can install and load any MCP server, which then runs with its rights, and any HTTP server it can reach. That is no more than the agent could already run, but a malicious server can feed it injected tool results. | vm.network = "none" or "proxy" with a short list; watch harness notices and the restart notes in the journal. |
| Resource grants within limits | In auto mode any agent can grow to the per-VM maximums at will; several agents together can hold the whole memory budget, making others wait to boot. |
Moderate max_*; grants = "approval" or "never"; a memory_budget_mib that leaves room for the host. |
| Host disk filling up | Disk images are sparse: min_free_disk_gib is checked when growth is granted, but guests consume host space as they write, up to their allocated size, without further checks (issue #14). Base-size disks are never checked. |
Size max_disk_gib × expected conversations against the filesystem; disk quotas; monitor free space under data_dir (the dashboard shows it and each disk image’s real size). |
| Memory budget vs. real usage | The budget counts configured mem_size_mib, not Firecracker’s overhead or page cache on the host (issue #13); 80% of MemTotal may be too much on small hosts. |
Set memory_budget_mib explicitly; cgroups via the jailer; compare with the dashboard’s measured RSS. |
| Resource alerts are advisory | The guest’s alerts only ask the agent to clean up; nothing enforces it inside the VM. | The VM’s own limits are the enforcement; disks don’t grow without a grant. |
| Conversation data leaves via the internet | With network = "nat" the agent can send anything it can read (the conversation via MCP, its workspace) anywhere. With "proxy", to any allowed host that accepts uploads (a git host, a package index, an API). With [[git]], to any repository the token can write. |
network = "none", or "proxy" with a short list of read-only mirrors; host egress filtering for nat (issue #6); [[git]] repos. |
| Code hosting token scopes | The git proxy protects branches and refuses merges, but other repository-level writes (settings, changing the default branch, deleting a repository) are bounded only by what the token may do. | Fine-grained tokens with only Contents and Pull requests (GitHub), or read_api + write_repository (GitLab); repos allowlist. |
| Git LFS unsupported | LFS requests answer 404, so repositories that need LFS objects don’t fully work. |
— |
| Branch names are case-sensitive | protected_branches matches exactly: main doesn’t protect Main. |
List every spelling the code host might accept. |
| Guest git config location | The URL rewrites are included from /etc/gitconfig; a git that reads another system config, or an agent that overrides insteadOf, talks to the code host directly (without a token, and only if vm.network allows it). |
vm.network = "none" or "proxy" without the code host in allowed_hosts. |
| Allowed hosts are broad | *.domain allows every subdomain, including ones the domain’s owner hands to customers; an allowed name stays allowed if it moves to another public server. |
List exact hosts; avoid wildcards on shared hosting domains. |
| Stdio MCP servers see their own configuration | Their args and env are written into the VM’s mcp.json, readable by the agent. |
Use an HTTP server with secret_env for anything that needs a credential. |
| The Lupyd profile URL receives the bot’s token | platforms.lupyd.profile_api_url is sent the bot’s Lupyd access token with every bio lookup. |
Leave it at the default; protect the config file like a credential. |
| Guest-to-host and guest-to-guest IP traffic | With NAT and ip_forward=1, a guest can reach services listening on the host’s tap address (including the web server if bound to all addresses) or other guests’ 172.30.x.x addresses unless the host firewall blocks it. Gopala installs no filtering rules. |
nftables rules: drop tap → host input except what you need, drop 172.30.0.0/16 → 172.30.0.0/16 forwarding (see the checklist). |
| Root inside the VM | install_packages = true grants sudo for the package manager, which is effectively root inside the VM (package managers run maintainer scripts); sudo = true grants it outright. |
Acceptable by design (the VM is the boundary); disable both and pre-bake tools for tighter agents. |
| Chat flooding via approvals | Each question counts against behavior.max_messages_per_minute and at most 3 are open per conversation; the outcome message and seeded reactions are not counted. |
Mitigated; /stop and removing the bot remain the escape hatches. |
| Notification abuse | A prompt-injected agent can mark messages critical and page the configured audience, up to alerts.max_per_hour times an hour per conversation. With the default critical = ["everyone"], that is everyone in every group the bot is in. |
A low max_per_hour; a narrow critical audience (role:on-call); per-conversation [[alerts.conversations]]. |
| Poisoned memory | Whatever the agent was talked into remembering comes back in later sessions of that conversation. | Review with the agent (entity, recall); forget; delete the disk to start over. |
| Journal growth | The host doesn’t rate-limit guest events (issue #17); a compromised guest can write ~1 MiB events quickly. The per-scope cap (journal_max_mib) is checked every 1000 inserts, so a scope can exceed it by up to ~1000 events before trimming (issue #16). |
Disk quotas on data_dir; monitor rooms.db size. |
| Model key abuse | A guest can call any path on its configured upstream with the operator’s key (e.g. other endpoints of the same API). Token budgets cap what responses report as tokens; calls whose responses carry no usage report, and calls already in flight when a limit is reached, aren’t stopped [inference]. | Budgets; provider-side spend limits and scoped keys; one key per bot; watch usage on the dashboard. |
| Sealed rooms are not end-to-end | The host generates room keys, stores each token’s wrapping key and keeps the journal in plaintext in rooms.db. Sealing protects against TLS-terminating intermediaries and plaintext transport segments, and makes revocation effective via rotation, but not against host compromise. A viewer keeps whatever it already received. |
Protect the host; future: Firefly/MLS for rooms (issue #22). |
Approver identity for owner |
Owner comes from the provider’s Meta.owner (Lupyd: the device’s local group info); an unknown owner means nobody qualifies. |
— |
| Watch links can be forwarded | A token is a bearer credential: whoever holds it reads as the person it was sent to, for as long as that person stays a member and the token hasn’t expired or been reissued. | Short token_ttl_secs; ask members not to share links. |
| The membership cache window | A person removed without a membership event (missed event, platform hiccup, Discord without the Server Members intent) keeps reading for up to membership_cache_secs; a subscription re-checks only when the answer expires. |
A short membership_cache_secs; [monitoring] rules narrower than members for sensitive conversations. |
| Platform answers decide access | Membership, roles and permissions come from each provider: Lupyd from the bot’s copy of the group, Slack from a member list cached 30 s and user groups cached 5 min, Discord from its cache or a member search. Whoever can change those (group admins, server admins, workspace admins) can grant access. | Prefer owner, approvers or user: rules over roles you don’t control. |
| Lupyd tokens are account-wide | A stolen Lupyd access token reads every Lupyd conversation of that person that [monitoring] allows, until it expires. Gopala can’t revoke it. |
monitoring.lupyd_tokens = false if you don’t need the Lupyd app; narrow rules. |
| Output is the agent’s whole working record | output grants every task, tool call, subagent and notice, which may include data from people’s messages and files. |
Keep output for people who could see that conversation anyway (the default members); narrower for groups with outside guests. |
allow_plaintext misuse |
Disables the loopback rule for the whole server; watch tokens, the admin token and (in none mode) events then cross the network in clear. |
Use only behind a TLS proxy on a private network. |
| Unjailed firecracker runs as the Gopala user | Without [vm.jailer], a VMM escape lands in the daemon’s user, which can read all keys. |
Use the jailer in production. |
| Slack and Discord tokens in plain memory | The client libraries hold the tokens as ordinary Strings for the life of the process, so they aren’t zeroized. |
Protect the host; rotate tokens if it may be compromised. |
| Shutdown cuts VMs short | [inference] On SIGTERM the daemon waits only 2 s for sessions; VMs still running are killed with the process (issue #21). | Rare data loss in the guest; the disk persists. |
| Lost deliveries | A message delivered just as a guest exits (idle shutdown, sleep, restart) can be lost (issue #25). | Repeat the message; watch the journal. |
Production hardening checklist
Section titled “Production hardening checklist”- Jailer: configure
[vm.jailer]with a dedicated unprivileged uid/gid (not shared with any other service),chroot_baseon the same filesystem asdata_dirandvm.kernel(hard links), and run Gopala as root as the jailer requires. Follow Firecracker’s production host setup and jailer guides. - cgroups: set
vm.jailer.cgroups(cgroup v2), e.g.cpu.max,memory.max,pids.max, so a VM can’t starve the host beyond its allocation. - Resources: per-VM maximums you can afford for every conversation at once or a
memory_budget_mibthat leaves the host headroom;min_free_disk_gibwith margin; considergrants = "approval"for shared or public bots. - Tools: build the tools image (
gopala image build), setvm.tools_imageandvm.tools_sha256, keep the file root-owned and read-only, and drop omp’s installer fromagent.user_setup. - Network: prefer
vm.network = "none"with packages and tools baked into the image (gopala image build), or"proxy"with a shortallowed_hostslist of exact mirror hostnames. Otherwise, with NAT:- masquerade only
172.30.0.0/16out of the uplink interface; - drop forwarding between
172.30.0.0/16addresses (guest-to-guest); - drop or restrict input from
gpl*taps to the host (other than DNS if you run a resolver); - block cloud metadata endpoints (e.g.
169.254.169.254) and internal networks; - optionally allowlist egress destinations.
- masquerade only
- Budgets: set
[budget]host limits below your provider spend limit, a[budget.default]per conversation, andpriority = "high"for the conversations that must keep working. - TLS for the server:
server.tls_cert/tls_key, or bind to loopback behind a TLS reverse proxy; setserver.public_urlto thehttps://address; leaveallow_plaintext = falseunless the proxy hop is private. Or setserver.enabled = false(androoms.enabled = false) if nobody needs to watch or configure. - Admin API: set
GOPALA_ADMIN_TOKENonly if you use the dashboard or browser configuration; a long random token over TLS only; sign out of shared browsers; keepgopala.tomland its.bakowned by the service user, 0600. - data_dir: owned by the service user, mode 0700, on an encrypted disk if possible; back it up as a secret (it contains device state and refresh tokens).
- Secrets: provide platform credentials, API keys, MCP secrets,
[[git]]tokens and the admin token through a root-onlyEnvironmentFileor a secret manager; remove the Lupyd password after the first sign-in; never put secrets inagent.env,guest_env(beyond placeholders),setup,image.setup(it ends up in every VM’s disk),system_promptor a stdio MCP server’sargs/env. - Code hosting: give each
[[git]]entry a token scoped to the repositories it needs (GitHub fine-grained: Contents and Pull requests), setrepos, and list every branch that must only change through review inprotected_branches. - Collaboration: turn
[collaboration]off where agents shouldn’t talk to each other; otherwise keepmax_agent_messages_per_hourmodest, give the agent role only to bots you run or trust, and leaveplatforms.lupyd.profile_api_urlat the Lupyd API. - Policies: choose
respond_to,direct_messages,invitesandapproversfor your audience; preferallowlistfor team bots; keepsudo = false. - Alerts: replace the default
critical = ["everyone"]with the people who should be paged (role:on-call,user:…), keepmax_per_hourlow, and leavewarningempty unless someone acts on warnings. - Provider keys: one dedicated key per bot with provider-side spend limits.
- Monitoring: decide who sees agent output and metrics (
[monitoring] outputandmetrics, per conversation where needed), keepmembership_cache_secsshort, and setlupyd_tokens = falseunless people use the Lupyd app to follow their agents. - Rooms: short
token_ttl_secs;encryption = "sealed"; a modestmax_viewers_per_roomandjournal_max_mib. - Host: keep firecracker, jailer and the guest kernel up to date; restrict
/dev/kvmto the service user; apply Firecracker’s recommended host mitigations. - Monitoring: watch the dashboard (measured vs reported usage, token use,
failedconversations) and the daemon log forcrashed,guest reports failure, rate-limit refusals,resourcesnotices,too many failed sign-insand device-limit errors; watch free space underdata_dir,rooms.db,usage.dbandvms/usage.