socialweb.computer

Request and provide VMs on an atproto compute market.

guest-events: events under a receipt

The Envelope

Who Sends What

payloadoriginatorwritten inconsumerfile of the consumer
vm.onNetworkguest (iroh ticket and https tunnel URL from /usr/local/bin/send-onnetwork.sh of guest-onnetwork.service, webrtc fingerprint from the guest agent) or bidder (sandbox)bidder reporequester: status.contract.vmAddress, status.contract.networksinternal/market/requester/runner.go waitGuest
vm.memoryPressure, vm.oomKilledbidder (the VM unit's cgroup memory.events, polled 15 s, edge-triggered, at most 10 per contract)bidder reporequester: one requester_market_event line eachinternal/market/bidder/memory.go
vm.hostKeysbidder (the host key the guest bound at its workload identity login)bidder reporequester: status.contract.hostKeyssame
vm.sandboxbidder (deno sandbox ended)bidder reporequester: status.contract.sandboxinternal/market/requester/events.go
vm.terminatedbidderbidder reporequester: Releasedinternal/market/requester/market.go FindTermination
vm.deleterequesterrequester repobidder: releaseinternal/market/bidder/adapters.go applyRelease
guest.publicKeyeither sidesender repothe other sideguest: internal/guestagent/subscribe.go; requester: inbound ContractEvent
guest.signalWebRTCeither sidesender repothe other sidesame
guest.secretsrequester onlyrequester repoguestinternal/guestagent/secrets.go
guest.secretsRequestedguest onlybidder reporequester: seals the bundleinternal/market/requester/guestsecrets.go
guest.secretsAppliedguest onlybidder reporequester: condition SecretsAppliedinternal/market/requester/events.go
guest.secretsUpdatedrequester onlyrequester repoguest: fetches the bundle againinternal/guestagent/subscribe.go
guest.agentStartrequester onlyrequester repoguest: systemctl start --no-block atirc-agent.serviceinternal/guestagent/agentstart.go
guest.requesterDidguest onlybidder reporequester: status.contract.guestRequesterinternal/market/requester/association.go
guest.r2Startrequester onlyrequester repoguest: starts socialweb-r2.serviceinternal/guestagent/association.go
guest.r2Releaserequester onlyrequester repoguest: runs socialweb-r2-release.servicesame
guest.r2Releasedguest onlybidder reporequester: status.contract.r2Releaseinternal/market/requester/guestrequester.go
guest.memoryPressure, guest.oomKillguest onlybidder reporequester: one requester_market_event line each (reportMarketEvent), which the test modules read (steps::market_event: an OOM fails the run, pressure goes to readings.memory)internal/guestagent/memory.go; cap memoryEventCapped in internal/market/bidder/guestevents.go
guest.imageguest onlybidder reporequester: requester_guest_image {marker, expected, ok}; a contract with spec.image releases on a mismatchinternal/guestagent/image.go; one per contract (guestEventSent in internal/market/bidder/guestevents.go)

Guest To Requester

diagram
Requesterbidder repoBidderGuestControlPlane (bidder)guestRequesterbidder repoBidderGuestControlPlane (bidder)guestPOST /v1/events acceptUri acceptCid record, Bearer workload token1verify token, accept is this guest's, kind is guest-originated2vm.onNetwork onto ComputeVM status, other kinds PublishGuestEvent3StateSync guest-<hash> or report-<hash>, key per kind4payload + market.event at EventRKeys(key), both signed5submitEvent (accept.submitEvent) or the stream carries it6getRecord payload by strongRef7status.contract or inbound ContractEvent8

Requester To Guest

diagram
guest agentper-ComputeVM queueBidderrequester repoRequesterCLI / browser / requesterguest agentper-ComputeVM queueBidderrequester repoRequesterCLI / browser / requesterContractEvent Outbound (nsid, tag, kind, key or ciphertext)1payload at SessionRKey contract-event + market.event at contract-event-envelope2submitEvent3getRecord payload, verify event + payload signatures4author = accept author, kind is requester-originated5Append uri cid record6WebSocket subscribeEvents cursor7frames seq uri cid record, keepalive every 25 s8act on the kind, save cursor9

compute.guest.subscribeEvents

itemvalue
routeGET /xrpc/com.publicdomainrelay.temp.compute.guest.subscribeEvents on the GuestControlPlane (internal/services/guestcontrolplane/subscribe.go)
authAuthorization: Bearer <workload identity token>; names the ComputeVM (guest.Authenticate)
paramcursor: last seq seen. absent = oldest entry kept
frameJSON text {"$type": "...subscribeEvents#event", seq, uri, cid, record}; record.$type is a compute.events.guest.* NSID
keepalivean empty binary frame every 25 s (SubscribeKeepalive)
errorFutureCursor: the guest agent resets its cursor to 0 and reconnects (internal/guestagent/subscribe.go)
reconnectbackoff 2 s doubling to 30 s

Each Kind

What the code does with each kind; the fields of each are its lexicon's, included below.

NSID tailnotes
vm.onNetworkkind absent: iroh without tag, https with tag (market.OnNetworkKind). webrtc address = the guest agent DTLS fingerprint sha-256 AB:CD:...
vm.hostKeysat most 8 keys, an ed25519 key required (internal/guestidentity/guestrecord.go)
vm.sandboxcompute.vm.kind: deno only (internal/market/bidder/sandbox.go)
vm.deleterequester writes released
vm.terminatedreasons: market.md; request is optional: a deleted_on_request without one is a delete on the bidder
vm.memoryPressurethe VM unit's cgroup memory.events high or max rose
vm.oomKilledits oom_kill rose
guest.publicKeyone per tag per side; anything sealed for a tag goes to the other side's latest key
guest.signalWebRTCplaintext {sdp, replyTo}; non-trickle ICE, one offer, one answer
guest.secretsage armored, at most 65536 bytes (MaxGuestSecretsCiphertext); plaintext = the getSecrets JSON array
guest.secretsRequestedthe requester seals only in comms mode Firehose with secretsFallback: Sealed; otherwise it records it and does nothing
guest.secretsAppliedthe guest agent posts it for the sealed path; the requester refuses any other via, and every one when it has an inbound endpoint; a getSecrets fetch is status.secretsFetchedAt
guest.secretsUpdatedthe bundle changed (atirc mint, association ref)
guest.agentStartneeds spec.agent (contractevents.go)
guest.requesterDiddid:plc only, never the authority's own DID (market.ValidGuestRequesterDID)
guest.r2Startneeds spec.association.fromGuest
guest.r2Release
guest.r2Released
guest.memoryPressureevery VM whose bidder serves the guest agent (memory.json); edge-triggered: PSI some avg10 >= 10.00% or swap >= 10% in use, re-armed after 5 min under half; one per kind per 10 min, ten memory events per contract (agent and bidder)
guest.oomKillone per /proc/vmstat oom_kill rise, same caps
guest.imageonce at agent start, when the file exists; the bidder publishes one per contract

Fields

com.publicdomainrelay.temp.compute.events.vm.onNetwork record key any

The bidder reports a network address of the VM; sent as the payload of a market.event.

record

fieldtypedescription
kindstring
What address is. Absent, it reads as iroh when tag is absent and https when tag is present; the bidder leaves it absent for those two. iroh: address is the VM's iroh ticket. https: tag names the tunnel and address is its https URL. webrtc: tag names the tunnel and address is the guest agent's DTLS certificate fingerprint ("sha-256 AB:CD:..."), which the requester checks against the a=fingerprint of the guest's answer. sandbox: a deno sandbox (compute.vm kind deno) is running, address sandbox://<ComputeVM name>, no tag.
knownValues ["iroh","https","webrtc","sandbox"] maxLength 16
addressstring
The VM's address for kind: the iroh ticket (iroh), the URL of the tagged tunnel (https), the guest agent's DTLS certificate fingerprint "sha-256 AB:CD:..." (webrtc), or sandbox://<ComputeVM name> (sandbox).
tagstring
Names one of the VM's tunnels (spec.tunnels of the contract); absent, address is the VM's iroh ticket.
maxLength 32
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.vm.hostKeys record key any

The bidder reports the VM's SSH host keys; sent as the payload of a market.event.

record

fieldtypedescription
keys *array of #hostKey
observedAt *string datetime
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

also: #hostKey

com.publicdomainrelay.temp.compute.events.vm.sandbox record key any

A deno sandbox reports that its program ended, with its output; sent as the payload of a market.event.

record

fieldtypedescription
exitCode *integer
The program's exit status; -1 when it was stopped at its deadline, killed by a signal, or could not be run.
timedOutboolean
The sandbox was stopped at its deadline rather than ending on its own.
stdoutstring
The program's standard output, cut to its first 65536 bytes.
maxLength 65536
stderrstring
The program's standard error, cut to its last 65536 bytes.
maxLength 65536
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.vm.delete record key any

The requester asks the bidder to delete the VM of a contract; sent as the payload of a market.event.

record

fieldtypedescription
reason *string
Why the requester asks for the stop; the requester writes released.
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.vm.terminated record key any

The bidder reports that the VM stopped; sent as the payload of a market.event.

record

fieldtypedescription
reason *string
Why the VM ended: guest_poweroff, vmm_exited, oom, host_reboot, identity_mismatch or image_refused when the VM was lost; deleted_on_request after a vm.delete or another release; expired when the bidder released it after the requester's contract-scoped association expired; association_ended when that association's contract ended (market.VMTerminatedReasons).
knownValues ["guest_poweroff","vmm_exited","oom","host_reboot","identity_mismatch","deleted_on_request","expired","image_refused","association_ended"]
exitCodeinteger
The VMM's exit status; the bidder does not write it today.
observedAt *string datetime
When the bidder saw the VM gone; createdAt is the same time.
requestcom.atproto.repo.strongRef
The compute.events.vm.delete that asked for the stop.
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.vm.memoryPressure record key any

The bidder reports that the VM's host cgroup crossed a memory threshold (memory.events high or max increased); sent as the payload of a market.event, edge-triggered and capped per contract.

record

fieldtypedescription
kind *string
The cgroup threshold crossed: high (reclaim pressure) or max (the hard limit).
knownValues ["high","max"]
threshold *integer
The cgroup limit crossed, in bytes: memory.high or memory.max of the VM's cgroup (0 when that limit is max).
observed *integer
memory.current in bytes when the crossing was seen.
observedAt *string datetime
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.vm.oomKilled record key any

The bidder reports that the kernel OOM-killed processes in the VM's host cgroup (memory.events oom_kill increased); sent as the payload of a market.event, one per new kill count, capped per contract.

record

fieldtypedescription
kills *integer
OOM kills in the VM's cgroup since the bidder's previous sample (it polls every 15 s); kills while the per-contract cap of 10 reports is reached are not reported later.
total *integer
OOM kills in the cgroup's lifetime.
limit *integer
memory.max in bytes.
observedAt *string datetime
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.publicKey record key any

A party to a contract publishes an encryption public key for one tag; sent as the payload of a market.event. Anything sealed under that tag is sealed to the latest publicKey of the other side. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said.

record

fieldtypedescription
kind *string
The key type. age-x25519: key is an age X25519 recipient (age1...).
knownValues ["age-x25519"] maxLength 32
tag *string
Names the tunnel of the contract (spec.tunnels) or another purpose the key is for.
maxLength 32
key *string
The public key in the text form of kind.
maxLength 256
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.signalWebRTC record key any

A sealed WebRTC session description for one tunnel; sent as the payload of a market.event. Non-trickle ICE: the requester offers once with all candidates, the guest answers once. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said. The bidder never opens the ciphertext.

record

fieldtypedescription
kind *string
The SDP type of the sealed session description.
knownValues ["offer","answer"] maxLength 16
tag *string
Names the webrtc tunnel of the contract (spec.tunnels).
maxLength 32
ciphertext *string
The session description, age armored ciphertext. The plaintext is the JSON object {"sdp": <session description>, "replyTo": <age recipient, offers only>}: an offer is sealed to the guest's latest compute.events.guest.publicKey for the tag and names in replyTo the age recipient the answer must be sealed to; an answer is sealed to that replyTo. No record names the key, so a reader opens every signal for the tag with its identity and keeps the ones that open.
maxLength 16384
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.secrets record key any

The requester's secrets bundle for the guest, sealed to the guest's latest compute.events.guest.publicKey with tag secrets; sent as the payload of a market.event. Requester-authored only: the bidder forwards it to the guest's subscription and never opens the ciphertext. Only when the firehose is the only way: a requester with an inbound endpoint serves the bundle on its getSecrets route alone, after a workload identity exchange. A requester sends one only when its comms mode is Firehose (no inbound endpoint), its spec.secretsFallback is Sealed and the guest posted a compute.events.guest.secretsRequested.

record

fieldtypedescription
ciphertext *string
The bundle, age armored ciphertext. The plaintext is the JSON array the getSecrets route serves: [{"path": <absolute path>, "value": <file content>, "mode": <optional octal file mode, at most 0600>}]. No record names the key it is sealed to; the guest opens every secrets event with its identity and keeps the ones that open.
maxLength 65536
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.secretsRequested record key any

The guest asks the requester for its secrets bundle sealed to its compute.events.guest.publicKey with tag secrets, because the requester has no inbound endpoint (comms mode Firehose); sent as the payload of a market.event. Guest-originated only, and only when the requester enabled the sealed fallback; a requester with an inbound endpoint drops it. It carries no secret.

record

fieldtypedescription
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.secretsApplied record key any

The guest wrote the files of its secrets bundle; sent as the payload of a market.event. Guest-originated only: the guest posts it to its bidder, which signs and publishes it to the requester.

record

fieldtypedescription
via *string
The path that delivered the bundle: sealed (a compute.events.guest.secrets record, for a requester without an inbound endpoint). A requester refuses getSecrets here: its own getSecrets route records that fetch.
knownValues ["getSecrets","sealed"] maxLength 16
countinteger
The number of files written.
minimum 0
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.secretsUpdated record key any

The requester changed the contract's secrets bundle (the association ref of spec.association); the guest fetches it again through getSecrets, or asks for the sealed fallback; sent as the payload of a market.event. Requester-originated only. It carries no secret.

record

fieldtypedescription
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.agentStart record key any

The requester asks the guest agent to start the guest's agent unit (the contract's spec.agent); sent as the payload of a market.event. Requester-originated only. It carries no secret.

record

fieldtypedescription
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.requesterDid record key any

The guest reports the repo DID of the requester it runs, so the contract's requester can associate it (spec.association.fromGuest); sent as the payload of a market.event. Guest-originated only. It carries no secret.

record

fieldtypedescription
did *string did
The did:plc of the requester the guest runs; any other DID method, and the outer requester's own DID, is refused.
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.r2Start record key any

The requester asks the guest agent to start the guest requester (socialweb-r2.service, run request --guest-requester as the r2 user) of a contract with spec.association.fromGuest; sent as the payload of a market.event. Requester-originated only. It carries no secret.

record

fieldtypedescription
name *string
The guest requester's invocation name: a lowercase DNS label of 1 to 63 characters.
maxLength 63
agentboolean
The guest requester asks for an atirc agent on its own guest and starts it once held.
holdboolean
The guest requester keeps its own contract held.
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.r2Release record key any

The requester, releasing its contract, asks the guest agent to release every contract the guest requester holds before the guest goes away; the guest answers with compute.events.guest.r2Released. Sent as the payload of a market.event. Requester-originated only. It carries no secret.

record

fieldtypedescription
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.r2Released record key any

The guest reports that its guest requester released its contracts (or holds none) after a compute.events.guest.r2Release; sent as the payload of a market.event. Guest-originated only. It carries no secret.

record

fieldtypedescription
ok *boolean
Every guest requester contract was released.
messagestring
maxLength 512
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.memoryPressure record key any

The guest crossed a memory threshold (edge-triggered: one record per crossing, re-armed only after the value stayed under half the threshold for 5 min; at most one per kind per 10 min and ten memory events per contract); sent as the payload of a market.event. Guest-originated only. It carries no secret. The host-side counterpart is compute.events.vm.memoryPressure.

record

fieldtypedescription
kind *string
What crossed: psi, /proc/pressure/memory some avg10; swap, the share of the guest's swap in use.
knownValues ["psi","swap"] maxLength 16
threshold *integer
The crossed threshold, in hundredths of a percent (psi: of some avg10; swap: of swapTotal).
minimum 0 maximum 10000
psiSomeAvg10integer
/proc/pressure/memory some avg10, in hundredths of a percent; absent without PSI.
minimum 0 maximum 10000
psiFullAvg10integer
/proc/pressure/memory full avg10, in hundredths of a percent; absent without PSI.
minimum 0 maximum 10000
swapUsed *integer
Swap in use, in bytes.
minimum 0
swapTotal *integer
The guest's swap, in bytes.
minimum 0
observedAt *string datetime
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.oomKill record key any

The guest kernel's OOM killer killed a process (/proc/vmstat oom_kill rose); sent as the payload of a market.event. One record per rise, at most one per 10 min (a later one carries every kill since) and ten memory events per contract. Guest-originated only. It carries no secret.

record

fieldtypedescription
kills *integer
The kills since the last oomKill of this guest.
minimum 1
total *integer
The guest's oom_kill count since boot.
minimum 1
observedAt *string datetime
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

com.publicdomainrelay.temp.compute.events.guest.image record key any

The guest reports the image it booted: the marker in its /etc/swc-image; sent as the payload of a market.event. One per contract, from a guest whose image has the file. Guest-originated only. It carries no secret.

record

fieldtypedescription
marker *string
The first line of the guest's /etc/swc-image, trimmed (no event when it is empty; no cap beyond the 24 KiB bound on a guest-originated event); the requester compares it with the marker of the image.json it asked for.
minLength 1
createdAt *string datetime
signaturesnetwork.attested.signature#signatures

Boot: hostKeys And onNetwork

diagram
Requesterbidder repoGuestControlPlaneguestBidderRequesterbidder repoGuestControlPlaneguestBidderboot user_data (cloudinit modules + setup-guest-binaries)1workload identity login, binds its ssh host key2RecordBoundHostKey onto ComputeVM guest report3iroh.service up, writes /run/guest-fqdn4guest-onnetwork POST /v1/events vm.onNetwork address = iroh ticket5OnNetwork onto ComputeVM status6report: vm.onNetwork (key onNetwork:receipt) + market.event7report: vm.hostKeys (key hostKeys:receipt) + market.event8submitEvent each9guest agent POST vm.onNetwork kind webrtc per tag (DTLS fingerprint)10vm.onNetwork tag (key onNetwork:tag:receipt)11VMAddress + HostKeys, Held after secrets12

Sealed Signaling (webrtc tunnels)

diagram
guest agentBidderRequesterCLI / browserguest agentBidderRequesterCLI / browserPOST guest.publicKey tag t (age1 guest key)1market.event guest.publicKey (bidder repo)2inbound ContractEvent publicKey3ContractEvent publicKey tag t (age1 requester key)4ContractEvent signalWebRTC offer, sealed to guest key, replyTo = requester key5submitEvent publicKey, signalWebRTC offer6subscribeEvents frames7open offer, answer, check nothing else8POST guest.signalWebRTC answer sealed to replyTo9market.event signalWebRTC answer10inbound ContractEvent answer11datachannel tag t, DTLS fingerprint = vm.onNetwork webrtc address12

Secrets: getSecrets Or Sealed Fallback

To send secrets to the VM without putting them in cloud-init (public atproto data), pass a JSON file to run request --secrets: [{path, value, mode?}]. A value that is not a string (an object, array, number) is written as its JSON text, compact. The CLI reads the file once (a <(...) pipe works) and writes it only into the requester's own OpenBao; the guest fetches it at boot. This works by Workload Identity Federation, so nothing sensitive is in the public compute.vm record:

A real bid config (bidder did:plc:2l2wdry77c7jtucbslstagkj):

{"uri": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.config.wif.simple/bid-596cc856db4e8aaf1080-config",
 "value": {"$type": "com.publicdomainrelay.temp.compute.config.wif.simple",
   "issuer_uri": "https://did-key-zq3shm88jyzpmldhqzbifwpqacv3hcp24jfsgb8g9eopcbmjm.xrpc.fedproxy.com/v1/identity/oidc",
   "subject": "actx:{actx}:plc:{did-plc-key}:role:{role}", "actx": "2l2wdry77c7jtucbslstagkj",
   "to_issue": "openbao-identity-oidc", "url_route": "/v1/identity/oidc/token", "createdAt": "2026-11-15T06:10:53Z"}}

The rest of this section is the guest's side.

diagram
BidderRequester ingressGuestControlPlaneguestBidderRequester ingressGuestControlPlaneguestalt[comms XRPC or Both: getSecrets over iroh, WebRTC, then https][comms Firehose and secretsFallback Sealed]GET /v1/identity/oidc/token/role (workload identity)1token2GET getSecrets/contract, Bearer token (requester.sock: iroh, then WebRTC; else https)3[{path, value, mode}]4write files root (mode or 0600), secrets.ready5POST guest.publicKey tag secrets6POST guest.secretsRequested7market.event publicKey, secretsRequested (relay or Jetstream)8seal bundle to that key, guest.secrets record in its repo9submitEvent guest.secrets10subscribeEvents guest.secrets11open, write files root (mode or 0600), secrets.ready12POST guest.secretsApplied via sealed13

Agent Start And atirc Mint

diagram
guestBidderrequester OpenBao bundleatircRequesterguestBidderrequester OpenBao bundleatircRequesterreceipt verified (ReceiptOk)1chat.atirc.mint subhandle from the RFP rkey, lease receipt + vm.terminated at-uri + accept2token with explicit exp3ATIRC_TOKEN into envFile entry, record atircMinted4submitEvent guest.secretsUpdated5subscribeEvents secretsUpdated6getSecrets again (comms Firehose: the sealed bundle again)7envFile sha256 changed, try-restart atirc-agent.service8submitEvent guest.agentStart (run request agent)9subscribeEvents agentStart10systemctl start --no-block atirc-agent.service11atirc agent joins as subhandle12

Guest Requester (R2) Events

Never

See Also