Skip to content
Gopala
Create an Agent

Sandboxed AI agent architecture

One host process, gopala run, talks to chat platforms through providers (Lupyd, Slack and Discord) and gives every conversation the agent is in its own set of components on the host. While a conversation is active it also gets a Firecracker microVM running the agent. Guests are untrusted: each reaches exactly one conversation, and no credential ever enters one. The same process serves this site, its API and the /watch websocket. Pick a component or a flow below to see what it does.

Follow a flow
gopala system architectureChat platforms reach Gopala through providers behind one Platform trait: Lupyd (its Firefly server, Auth0 and members' apps) is implemented; Slack and Discord are possible. On the host, the Lupyd provider feeds platform-neutral events to the router, which drives approvals and one set of per-conversation components (HostConversation, session supervisor, VmControl, scoped MCP server, LLM proxy) and one Firecracker microVM per conversation over vsock ports 1024, 1025 and 1100+i. Inside the VM, gopala-guest supervises the omp harness and reports memory and disk use; VmControl decides the agent's requests for more resources. One web server serves the static site, the configuration API (admin token for reading and saving gopala.toml) and the /watch websocket, behind which Rooms journals sessions for read-only viewers. Model calls leave through the host proxy over HTTPS.Sign-in over HTTPS: Auth0 password-realm grant once, then the refresh tokenFirefly: MLS-encrypted messages over WebTransport or WebSocket (firefly-mcp, inside the Lupyd provider)Members' apps talk to Firefly with MLS end-to-end encryptionThe member gets a personal watch link <public_url>/watch#<token> (as ws/wss) in an end-to-end encrypted DM and gives it to gopala watchPlatform-neutral events (messages, reactions, invites, membership changes) from every provider, merged by daemon::runReplies and reactions from approvers (Approvals::on_reply / on_reaction)HostConversation::request_approval opens a request; Approvals resolves it with the answerRouter::conversation finds or creates the scope, records every message, and answers commands/watch issues a personal token; a member leaving revokes theirs and rotates the room keyMessages, edits, reactions and reads go through the conversation’s provider via the Platform trait (rate-limited, split to max_message_chars)session::Command: Deliver, Abort (/stop) or Close (the agent left), over an mpsc channelVmManager::prepare, PreparedVm::boot, RunningVm::stopfirecracker --no-api --config-file, optionally under the jailer, with the per-scope disk, tap and vsock socketsSessionEvents to journal, and guest approval requestsMCP tool calls run against the conversation’s HostConversationRooms::publish: assign seq, store in rooms.db, fan out to viewersThe session boots with VmControl’s allocation and hands it the guest’s usage; VmControl sends Command::Restart or Command::Sleepvm_resources, request_resources, restart_vm and sleep_vm call the Machine trait, implemented by VmControlWith vm.grants = "approval", growth is asked through HostConversation::request_approval; every decision is journaled as a “resources” noticeGuestFrame.usage on the control channel every agent.usage_interval_secs: memory, disk, load and vCPUs; the session records it in VmControlAbove agent.disk_alert_percent or memory_alert_percent: one urgent steer with the numbers and cleanup stepsws/wss to <public_url>/watch: protobuf frames, events sealed with rotating room keys; viewers may only pingThe static site at / and the configuration API under /api; GET and PUT /api/config need the admin bearer tokenThe server upgrades /watch to a websocket and hands it to Rooms, which serves that viewerGET /api/config reads and PUT /api/config replaces gopala.toml, both only with the admin bearer token; restart to applyControl channel: vsock port 1024, protobuf GuestFrame / HostFrame with a 4-byte length prefix, ≤ 1 MiBMCP: vsock port 1025, newline-delimited JSON-RPC (rmcp), one session per connectionModel API: vsock port 1100+i for the i-th [[llm]] entry, plain HTTP/1.1HTTPS (rustls) to the configured upstream with the real API key added by the hostomp RPC: newline-delimited JSON on omp’s stdin / stdoutomp runs the chat MCP server over stdioModel API calls to http://127.0.0.1:<guest_port> with a placeholder keyThe agent’s persistent workspace and omp’s session filesOnly with vm.network = "nat": tap device and NAT; add your own egress filteringApps such as the Lupyd app on /monitor: protobuf requests and subscriptions, authenticated with the person’s Lupyd token (or a watch or admin token) and checked against their membership; the same answers over HTTP under /api/monitor/

Hover or focus a component to trace its connections and see what it does; click it (or press Enter) to keep the card open. Pick a flow to step through a scenario with the arrow keys.

The components

Gopala ships as one executable, gopala, built from the parts below. gopala-guest, the program inside each VM, is small and static, with no TLS, platform or configuration code. Chat platforms plug in as providers: the host knows only gopala-platform's Platform interface, and Lupyd, Slack and Discord each implement it. Details in Architecture.

ComponentWhat it does
gopalaThe agent manager and its commands (run, web, watch, check-config, image build): routing and policy, approvals, sessions, the LLM proxy, authentication and monitoring, and the web server (site, API, /watch, /monitor).
gopala-platformThe Platform interface every chat provider implements, and the platform-neutral event and message types the host works with.
gopala-lupydThe Lupyd provider: Auth0 sign-in and the Firefly (MLS) device through firefly-mcp.
gopala-slackThe Slack provider: the agent’s Slack app (its bot user) over Socket Mode, so no public URL is needed.
gopala-discordThe Discord provider: a Discord application on the gateway.
gopala-guestRuns in each VM: control link, provisioning, harness supervision, the resource monitor, the MCP bridge and model forwarders.
gopala-memoryThe agent’s persistent memory: one SQLite file per VM on its disk, deduplicated facts recalled by full-text and optional embedding search.
gopala-mcpThe MCP server a guest talks to: firefly-mcp-like tools confined to one conversation, request_approval, and the four VM tools.
gopala-roomsWatching behind /watch: SQLite journal, personal tokens, sealed room keys, the per-viewer handler and the viewer client.
gopala-vmFirecracker launcher: persistent disk, tap device, vsock sockets, optional jailer chroot, console log.
gopala-protoEvery wire format (protobuf) and the vsock framing and port constants.
gopala-configThe TOML configuration, its defaults, JSON Schema and cross-field validation.

Ports and channels

Gopala listens on exactly one TCP port, [server].bind (default 127.0.0.1:60901, reached as public_url): one HTTP(S) server for the static site, the configuration API and the/watch websocket. gopala web --config gopala.toml serves the site and API without signing in to any platform, to configure Gopala before its first run; gopala run serves the same plus /watch. Every vsock connection is opened by the guest to the host (CID 2); Firecracker maps guest port P to the host socket {uds}_P that the conversation's session bound before boot, so the socket a connection arrives on is its scope. The guest's CID is 3 + slot.

Port / transportBetweenEncoding
vsock 1024gopala-guest → sessionprotobuf GuestFrame / HostFrame (incl. ResourceUsage every usage_interval_secs), 4-byte length prefix, ≤ 1 MiB
vsock 1025gopala-guest mcp → ScopedMcpMCP JSON-RPC (rmcp), one session per connection: chat tools plus vm_resources, request_resources, restart_vm, sleep_vm
vsock 1100 + iforwarder → LLM proxy iHTTP/1.1 (the i-th [[llm]] entry)
127.0.0.1:guest_portomp → forwarder (inside the VM)HTTP/1.1, placeholder key
[server].bind · /browser → web serverHTTP(S): the static site (site_dir)
[server].bind · /api/…browser → APIHTTP(S), JSON and TOML: status (public), sign-in, the dashboard API, the config helpers and GET / PUT /api/config, with the session cookie or the admin bearer token
[server].bind · /monitorapps → web serverws / wss, one protobuf MonitorClientMessage / MonitorServerMessage per binary message; authenticate first
[server].bind · /api/monitor/…apps, scripts → web serverHTTP(S), JSON (or protobuf with Accept: application/x-protobuf), Bearer admin, watch or Lupyd token
[server].bind · /watchgopala watch → web server → Roomsws / wss, one protobuf frame per binary message
FireflyLupyd provider ⇄ Firefly serverMLS over WebTransport or WebSocket (firefly-mcp)
HTTPSLLM proxy → model providerthe request, with the real key added

A conversation's lifecycle

The session supervisor's states. A VM exists only while Booting or Working; the disk outlives it. See the step-by-step walkthrough.

stateDiagram-v2
    [*] --> Asleep: first event for the scope
    Asleep --> WaitingSlot: Command.Deliver queued
    WaitingSlot --> Booting: Slots.acquire
    WaitingSlot --> Asleep: /stop clears the queue
    Booting --> Working: guest hello + HostInit
    Booting --> Backoff: prepare/boot error,<br/>boot timeout, VM exited
    Working --> Working: deliveries, events,<br/>approvals, reconnects
    Working --> Asleep: idle_shutdown_secs without activity<br/>(Shutdown, VM stops, disk kept)
    Working --> Backoff: VM exited unexpectedly,<br/>control write failed
    Backoff --> WaitingSlot: 5 s · 2^(failures-1), at most 160 s
    Asleep --> [*]: Command.Close (agent left)
    Working --> [*]: Command.Close

Where to read more