guest-events: events under a receipt
- after the receipt (market.md), the bidder, the requester and the guest talk only through
market.eventrecords and two guest HTTP paths - steps: S7 boot and vm events, S8 guest events and atirc, S9 release
- one row per lexicon: lexicons-market.md
- constants:
internal/atproto/market/nsid.go,internal/atproto/market/guest.go; guest side:internal/guestagent(binarycmd/socialweb-guest-agent); guest HTTP plane:internal/services/guestcontrolplane,internal/guestidentity - names drop the prefix
com.publicdomainrelay.temp.(guest.publicKey=com.publicdomainrelay.temp.compute.events.guest.publicKey)
The Envelope
- every event is two signed records in the sender's repo: the payload (
compute.events.vm.*orcompute.events.guest.*) andmarket.event {receipt, payload, createdAt, signatures} receipt= strongRef to the bidder'smarket.receipt;payload= strongRef to the payload record in the same repo as the event- the receiver reads the payload through the strongRef, checks its CID, its author and both signatures (
applyGuestEventininternal/market/bidder/guestevents.go) - delivery:
market.submitEventto the other party, and the relay / Jetstream streams as fallback (market.md) - the guest holds no repo key. the bidder signs and writes every guest-originated event in its own repo
Who Sends What
| payload | originator | written in | consumer | file of the consumer |
|---|---|---|---|---|
vm.onNetwork | guest (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 repo | requester: status.contract.vmAddress, status.contract.networks | internal/market/requester/runner.go waitGuest |
vm.memoryPressure, vm.oomKilled | bidder (the VM unit's cgroup memory.events, polled 15 s, edge-triggered, at most 10 per contract) | bidder repo | requester: one requester_market_event line each | internal/market/bidder/memory.go |
vm.hostKeys | bidder (the host key the guest bound at its workload identity login) | bidder repo | requester: status.contract.hostKeys | same |
vm.sandbox | bidder (deno sandbox ended) | bidder repo | requester: status.contract.sandbox | internal/market/requester/events.go |
vm.terminated | bidder | bidder repo | requester: Released | internal/market/requester/market.go FindTermination |
vm.delete | requester | requester repo | bidder: release | internal/market/bidder/adapters.go applyRelease |
guest.publicKey | either side | sender repo | the other side | guest: internal/guestagent/subscribe.go; requester: inbound ContractEvent |
guest.signalWebRTC | either side | sender repo | the other side | same |
guest.secrets | requester only | requester repo | guest | internal/guestagent/secrets.go |
guest.secretsRequested | guest only | bidder repo | requester: seals the bundle | internal/market/requester/guestsecrets.go |
guest.secretsApplied | guest only | bidder repo | requester: condition SecretsApplied | internal/market/requester/events.go |
guest.secretsUpdated | requester only | requester repo | guest: fetches the bundle again | internal/guestagent/subscribe.go |
guest.agentStart | requester only | requester repo | guest: systemctl start --no-block atirc-agent.service | internal/guestagent/agentstart.go |
guest.requesterDid | guest only | bidder repo | requester: status.contract.guestRequester | internal/market/requester/association.go |
guest.r2Start | requester only | requester repo | guest: starts socialweb-r2.service | internal/guestagent/association.go |
guest.r2Release | requester only | requester repo | guest: runs socialweb-r2-release.service | same |
guest.r2Released | guest only | bidder repo | requester: status.contract.r2Release | internal/market/requester/guestrequester.go |
guest.memoryPressure, guest.oomKill | guest only | bidder repo | requester: 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.image | guest only | bidder repo | requester: requester_guest_image {marker, expected, ok}; a contract with spec.image releases on a mismatch | internal/guestagent/image.go; one per contract (guestEventSent in internal/market/bidder/guestevents.go) |
- guest-originated set:
market.IsGuestOriginatedEventNSID(publicKey, signalWebRTC, secretsApplied, secretsRequested, requesterDid, r2Released, memoryPressure, oomKill, image). the guest control plane refuses any other kind (guestEventininternal/guestidentity/service.go) - requester-originated set:
market.IsRequesterGuestEventNSID(publicKey, signalWebRTC, secrets, agentStart, secretsUpdated, r2Start, r2Release). the bidder refuses any other kind from a requester (applyGuestEvent) - kinds the requester's submitEvent takes:
isGuestEventNSIDininternal/market/requester/events.go - direction of
publicKeyandsignalWebRTCcomes from the author: requester-authored ones go to the guest, bidder-authored ones carry what the guest said
Guest To Requester
sequenceDiagram
autonumber
participant G as guest
participant CP as GuestControlPlane (bidder)
participant B as Bidder
participant BP as bidder repo
participant R as Requester
G->>CP: POST /v1/events acceptUri acceptCid record, Bearer workload token
CP->>CP: verify token, accept is this guest's, kind is guest-originated
CP->>B: vm.onNetwork onto ComputeVM status, other kinds PublishGuestEvent
B->>B: StateSync guest-<hash> or report-<hash>, key per kind
B->>BP: payload + market.event at EventRKeys(key), both signed
B->>R: submitEvent (accept.submitEvent) or the stream carries it
R->>BP: getRecord payload by strongRef
R->>R: status.contract or inbound ContractEvent
- the POST body:
{acceptUri, acceptCid, record}; the record has$type= the payload NSID and no signature (internal/guestagent/events.go) - the bearer is the
Authorizationheader only (Guest.Eventsininternal/guestidentity/service.go) - answers: 200
{ok, name, guestLogin}; 401AuthenticationRequired/InvalidToken; 400InvalidRequest; 404UnknownGuest/UnknownAccept; 503Unavailable vm.onNetworkis checked against the contract's accept only once the ComputeVM holds it (guestrecord.go); every other kind needs the exact accept and a receipt- the bidder keys:
reportSyncKeyandguestEventSyncKeyininternal/market/bidder/syncs.go; the rkeys: market.md - the bidder never opens a sealed body; it routes by NSID prefix
Requester To Guest
sequenceDiagram
autonumber
participant C as CLI / browser / requester
participant R as Requester
participant RP as requester repo
participant B as Bidder
participant Q as per-ComputeVM queue
participant G as guest agent
C->>R: ContractEvent Outbound (nsid, tag, kind, key or ciphertext)
R->>RP: payload at SessionRKey contract-event + market.event at contract-event-envelope
R->>B: submitEvent
B->>RP: getRecord payload, verify event + payload signatures
B->>B: author = accept author, kind is requester-originated
B->>Q: Append uri cid record
G->>B: WebSocket subscribeEvents cursor
B-->>G: frames seq uri cid record, keepalive every 25 s
G->>G: act on the kind, save cursor
- outbound ContractEvents (
socialweb.computer/v1alpha1, cluster scoped, owned by the ComputeContract): made by the CLI (internal/stack/request/webrtc.go), the browser page, or the requester itself (secrets-<contract>,secrets-updated-<hash>) - published by
publishContractEventininternal/market/requester/contractevents.go; field rules invalidateGuestFieldsthere - inbound ContractEvents (guest
publicKey,signalWebRTC) are namedInboundContractEventName(eventURI)
compute.guest.subscribeEvents
| item | value |
|---|---|
| route | GET /xrpc/com.publicdomainrelay.temp.compute.guest.subscribeEvents on the GuestControlPlane (internal/services/guestcontrolplane/subscribe.go) |
| auth | Authorization: Bearer <workload identity token>; names the ComputeVM (guest.Authenticate) |
| param | cursor: last seq seen. absent = oldest entry kept |
| frame | JSON text {"$type": "...subscribeEvents#event", seq, uri, cid, record}; record.$type is a compute.events.guest.* NSID |
| keepalive | an empty binary frame every 25 s (SubscribeKeepalive) |
| error | FutureCursor: the guest agent resets its cursor to 0 and reconnects (internal/guestagent/subscribe.go) |
| reconnect | backoff 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 tail | notes |
|---|---|
vm.onNetwork | kind absent: iroh without tag, https with tag (market.OnNetworkKind). webrtc address = the guest agent DTLS fingerprint sha-256 AB:CD:... |
vm.hostKeys | at most 8 keys, an ed25519 key required (internal/guestidentity/guestrecord.go) |
vm.sandbox | compute.vm.kind: deno only (internal/market/bidder/sandbox.go) |
vm.delete | requester writes released |
vm.terminated | reasons: market.md; request is optional: a deleted_on_request without one is a delete on the bidder |
vm.memoryPressure | the VM unit's cgroup memory.events high or max rose |
vm.oomKilled | its oom_kill rose |
guest.publicKey | one per tag per side; anything sealed for a tag goes to the other side's latest key |
guest.signalWebRTC | plaintext {sdp, replyTo}; non-trickle ICE, one offer, one answer |
guest.secrets | age armored, at most 65536 bytes (MaxGuestSecretsCiphertext); plaintext = the getSecrets JSON array |
guest.secretsRequested | the requester seals only in comms mode Firehose with secretsFallback: Sealed; otherwise it records it and does nothing |
guest.secretsApplied | the 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.secretsUpdated | the bundle changed (atirc mint, association ref) |
guest.agentStart | needs spec.agent (contractevents.go) |
guest.requesterDid | did:plc only, never the authority's own DID (market.ValidGuestRequesterDID) |
guest.r2Start | needs spec.association.fromGuest |
guest.r2Release | |
guest.r2Released | |
guest.memoryPressure | every 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.oomKill | one per /proc/vmstat oom_kill rise, same caps |
guest.image | once at agent start, when the file exists; the bidder publishes one per contract |
Fields
lexicon: com.publicdomainrelay.temp.compute.events.vm.onNetwork
lexicon: com.publicdomainrelay.temp.compute.events.vm.hostKeys
lexicon: com.publicdomainrelay.temp.compute.events.vm.sandbox
lexicon: com.publicdomainrelay.temp.compute.events.vm.delete
lexicon: com.publicdomainrelay.temp.compute.events.vm.terminated
lexicon: com.publicdomainrelay.temp.compute.events.vm.memoryPressure
lexicon: com.publicdomainrelay.temp.compute.events.vm.oomKilled
lexicon: com.publicdomainrelay.temp.compute.events.guest.publicKey
lexicon: com.publicdomainrelay.temp.compute.events.guest.signalWebRTC
lexicon: com.publicdomainrelay.temp.compute.events.guest.secrets
lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsRequested
lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsApplied
lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsUpdated
lexicon: com.publicdomainrelay.temp.compute.events.guest.agentStart
lexicon: com.publicdomainrelay.temp.compute.events.guest.requesterDid
lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Start
lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Release
lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Released
lexicon: com.publicdomainrelay.temp.compute.events.guest.memoryPressure
lexicon: com.publicdomainrelay.temp.compute.events.guest.oomKill
lexicon: com.publicdomainrelay.temp.compute.events.guest.image
Boot: hostKeys And onNetwork
sequenceDiagram
autonumber
participant B as Bidder
participant G as guest
participant CP as GuestControlPlane
participant BP as bidder repo
participant R as Requester
B->>G: boot user_data (cloudinit modules + setup-guest-binaries)
G->>CP: workload identity login, binds its ssh host key
CP->>B: RecordBoundHostKey onto ComputeVM guest report
G->>G: iroh.service up, writes /run/guest-fqdn
G->>CP: guest-onnetwork POST /v1/events vm.onNetwork address = iroh ticket
CP->>B: OnNetwork onto ComputeVM status
B->>BP: report: vm.onNetwork (key onNetwork:receipt) + market.event
B->>BP: report: vm.hostKeys (key hostKeys:receipt) + market.event
B->>R: submitEvent each
G->>CP: guest agent POST vm.onNetwork kind webrtc per tag (DTLS fingerprint)
B->>BP: vm.onNetwork tag (key onNetwork:tag:receipt)
R->>R: VMAddress + HostKeys, Held after secrets
- the iroh report unit and its script:
internal/guestseed/userdata.go("Report the guest iroh ticket to the market") - one report per kind and tag:
reportininternal/market/bidder/report.gopublishes only whatComputeVMPublisheddoes not hold yet - Held: iroh address + host keys; with a secretsRef and an inbound endpoint, also the getSecrets fetch (market.md)
Sealed Signaling (webrtc tunnels)
- each side publishes a
guest.publicKey(kindage-x25519) per tag - the offer is sealed to the guest's latest key for the tag, plaintext
{sdp, replyTo}; the answer is sealed toreplyTo - no record names its recipient: a reader trial-opens every signal for its tag and keeps the ones that open
- no private key, SDP, ICE candidate or IP address is ever in a record, a ContractEvent, a StateSync, kcp or a log
- CLI side:
run request proxy <name> --tag <tag>(internal/webrtcproxy); STUNstun:stun.cloudflare.com:3478only, no TURN
sequenceDiagram
autonumber
participant C as CLI / browser
participant R as Requester
participant B as Bidder
participant G as guest agent
G->>B: POST guest.publicKey tag t (age1 guest key)
B->>R: market.event guest.publicKey (bidder repo)
R->>C: inbound ContractEvent publicKey
C->>R: ContractEvent publicKey tag t (age1 requester key)
C->>R: ContractEvent signalWebRTC offer, sealed to guest key, replyTo = requester key
R->>B: submitEvent publicKey, signalWebRTC offer
B->>G: subscribeEvents frames
G->>G: open offer, answer, check nothing else
G->>B: POST guest.signalWebRTC answer sealed to replyTo
B->>R: market.event signalWebRTC answer
R->>C: inbound ContractEvent answer
C->>G: datachannel tag t, DTLS fingerprint = vm.onNetwork webrtc address
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:
- each bid's
configis acom.publicdomainrelay.temp.compute.config.wif.simplerecord: it tells the requester, before it accepts, what the OIDC issuer of the VM will be and how itssubclaim is formed. If the VM goes away the requester can accept another bidder's bid; the WIF configuration is loosely coupled to the bidder (in-depth: droplet-oidc-poc) - the requester writes a
com.fedproxy.rbacrecord in its repo atnode.<accept rkey>: one role per VM{role_name, definition: {iss, aud: api://ATProto?actx=<requester DID>, sub, policies}}(prepareWorkloadGrantininternal/market/requester/secrets.go); the bidder reads it (internal/guestidentity/rbac_reader.go), turns the roles whoseissandsubare its own intoGuestIdentityGrants, and its OpenBao identity engine then lets that guest mint a token for that audience - the user_data (
cloudinitmodule setup-secrets) logs the guest in at the bidder (guest-login token <aud>) and sends that token to the requester's getSecrets route; the requester checks the audience against the bidder issuer's keys and thewid_subclaim against the subjectactx:<bidder>:plc:<requester>:role:<vm>(secretsState.fetch), then answers the bundle - who can read the bundle: the requester (its OpenBao) and the guest that holds the token. The bidder relays no secret on the getSecrets path and on the sealed path carries ciphertext it cannot open; it does run the token issuer, so a requester trusts the bidder it accepts
- release deletes the rbac record (
deleteRBAC)
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.
spec.secretsRefnames a bundle[{path, value, mode?}]in the requester's OpenBao. One rule, checked by the requester (CheckSecretEntry:ParseSecretsBundle, the CLI's--secrets) and again by both guest writers (setup-secrets, the guest agent's sealed writer):pathis absolute, not/, has no control character (no byte below 0x20, no 0x7f; NUL and newline included) and equals its cleaned form (no.,..or empty component, no trailing slash);modeis an octal string of at most0777(the whole string:^0?[0-7]{1,3}$, in jq\A0?[0-7]{1,3}\z; no setuid, setgid or sticky), default0600; avaluethat is not a string is written as its compact JSON text. One bad entry refuses the whole bundle and nothing is written; the error names the entry index and the reason, never a value. A writer makes only the missing directories (root 0700) and never changes an existing one; each file is written root-owned to a temp file in its directory and renamed, so a symlink at the path is replaced, never followed. setup-secrets reads each path and mode as exact bytes (jq -jplus a sentinel), never through$(...)trimming- the channel, in order (owner, decisions 64 and 2026-11-19): a peer transport, then https to the requester ingress, then, only in comms mode Firehose with
spec.secretsFallback: Sealed, the sealed record. getSecrets is one XRPC service with one check (the token audienceapi://ATProto?actx=<requester DID>and the subject claim,secretsState.fetch); the transports only carry its requests - peer transports: with an inbound endpoint the requester writes
/etc/socialweb-guest-agent/requester.json{iroh, webrtc}into user_data.irohis theiroh://<ticket>of the requester's Servicesvc-requester-<name>-iroh(named handleriroh) behind IngressProxyrequester-iroh;webrtcis the id of the requester's guest WebRTC ingress (tunnel.ID(requester DID)). The file makes the bidder install the guest agent (and lease its WebRTC UDP port), which serves/run/socialweb-guest-agent/requester.sock(root 0600, unix only) and forwards each request over iroh (dumbpipe connect), then WebRTC, eachSecretsPeerChannelTimeoutSec(20 s). The socket forwards every method and path to the requester (owner, decision 72) as a transparent proxy: it follows no redirect (a 3xx goes back to the caller), drops hop-by-hop headers both ways, adds no size limit of its own (the requester's handlers keep theirs) and logs the method, the path without its query, the channel, the status and the transport's inner error, never a URL, a header value or a body. It reads the request body whole (it may send it again on the next channel); it tries the next channel after any failure for GET and HEAD, and for other methods only when the request was never written (a dial or connect failure): a POST that failed after it was sent is answered 502, never sent twice.SecretsPeerChannelTimeoutSec(20 s) bounds one channel's whole exchange, a streamed answer included. A resumed contract that already fetched and whose getSecrets registration gives up (requester_guest_secrets_resume_unready, afterTransientResumeGiveUp) stays Held with no route: a later refetch gets 404 for the contract's life. A bidder that installs the agent forrequester.jsonsays so in/etc/socialweb-guest-agent/bidder.json("requester": true). The requester composes the Service, IngressProxyrequester-irohand its Exposure only while one of its ComputeContracts with asecretsRefis not Released or Failed (compose.SecretsContracts, watched bycompose.SecretsContractWatch); the last one's release removes them, and dumbpipe stops. iroh first: every guest has dumbpipe and iroh relays cross NAT; WebRTC is STUN only - WebRTC: the requester OFFERS with the same
ingress/webrtcService a bidder answers, through the sealed guest signalling: the agent publishesguest.publicKeytagrequester; the requester seals{sdp, replyTo, id, session, peer}to it asguest.signalWebRTCkind offer (ContractEventrequester-webrtc-<contract>); the agent answers withingress/webrtc.Peeron its own API and DTLS certificate, sealed toreplyTo, and opens the datachannels that carry the HTTP - https: setup-secrets waits up to 60 s for the socket only when
requester.jsonis there ANDbidder.jsonsays"requester": true(an older bidder's agent never serves it: no wait), tries it (curl --unix-socket, 45 s), then GETs/xrpc/com.publicdomainrelay.temp.compute.secrets.getSecrets/<contract>fromstatus.secretsUrl(prod: the did:key ingress relaydid-key-<key>.xrpc.fedproxy.com, whose TLS ends at the relay host), 10 rounds - the requester records the time and channel of the FIRST fetch in status (
status.secretsFetchedAt,status.secretsFetchedVia); every fetch, a refetch too, logs its own channel (requester_guest_secrets_fetchedchannel), each listener labelled by its transport: the named iroh handleriroh, the guest WebRTC ingress and the bidder WebRTC ingresswebrtc, the https ingresshttps.status.secretsFetchedVia(iroh,webrtc,https), conditionSecretsAppliedreasonGetSecretsIroh,GetSecretsWebRTCorGetSecretsHTTPS, logrequester_guest_secrets_fetchedchannel - with an inbound endpoint the requester never seals: a
guest.secretsRequestedfrom the guest or the bidder is recorded instatus.contract.secretsRequestedand never acted on (requester_guest_secrets_not_sealed), an outboundguest.secretsContractEvent not yet published fails, and aguest.secretsAppliedis refused (a guest reports only the sealed path, to a Firehose requester). published ciphertext stays on the protocol and can be broken later - the guest agent asks for a sealed bundle only when
/etc/socialweb-guest-agent/secrets.jsonholds the JSON object with exactly the keyfallback="sealed"and at mostgetSecrets=false(an older Firehose requester's marker), nothing after it;"getSecrets": true(an older requester with an inbound endpoint), any other key or value turns the sealed path off (guest_secrets_sealed_refused) - a failure: setup-secrets exits 1; independently, the requester fails the contract when no fetch came within
DefaultVMReadyTimeout(2 min) afterwaitGuestreturned (address, host keys, image marker), even while the guest still retries; setup-secrets' loops use the named constants ofinternal/atproto/cloudinit/guestsecrets.go(the numbers they had), and nothing derives the requester's deadline from them; a resumed contract whosestatus.contract.secretsAppliedis recorded is not failed by it;run requestreleases the VM and exits non-zero,--holdor not, and also when a Firehose contract's sealed secrets never arrive within its contract timeout - in comms mode Firehose user_data has no setup-secrets and no
requester.json: the agent asks at once - version skew of the rule: setup-secrets comes with the requester's user_data, the sealed writer with the bidder's guest agent. An older bidder's agent refuses a mode above
0600: in comms mode Firehose a bundle with such a mode writes nothing on it (the guest logs the refusal), noguest.secretsAppliedcomes, andrun requestlogs "the guest did not write its secrets" after its contract timeout, releases the VM and exits 1 - both paths end in
/run/socialweb-guest-agent/secrets.ready; consumers orderAfter=cloudinit.SecretsReadyUnits - status:
status.secretsFetchedAtandstatus.secretsFetchedVia(getSecrets),status.contract.secretsRequested,status.contract.secretsApplied(sealed), conditionSecretsApplied
sequenceDiagram
autonumber
participant G as guest
participant CP as GuestControlPlane
participant R as Requester ingress
participant B as Bidder
alt comms XRPC or Both: getSecrets over iroh, WebRTC, then https
G->>CP: GET /v1/identity/oidc/token/role (workload identity)
CP-->>G: token
G->>R: GET getSecrets/contract, Bearer token (requester.sock: iroh, then WebRTC; else https)
R-->>G: [{path, value, mode}]
G->>G: write files root (mode or 0600), secrets.ready
else comms Firehose and secretsFallback Sealed
G->>B: POST guest.publicKey tag secrets
G->>B: POST guest.secretsRequested
B->>R: market.event publicKey, secretsRequested (relay or Jetstream)
R->>R: seal bundle to that key, guest.secrets record in its repo
R->>B: submitEvent guest.secrets
B->>G: subscribeEvents guest.secrets
G->>G: open, write files root (mode or 0600), secrets.ready
G->>B: POST guest.secretsApplied via sealed
end
- the requester reseals for a newer key while the request is unanswered (
sealGuestSecretsininternal/market/requester/guestsecrets.go) - a Firehose requester with
Noneand a secretsRef fails the contract - a bundle change (
guest.secretsUpdated) makes the guest fetch again (SECRETS_REFETCH=1 setup-secrets.sh), or in Firehose mode ask for the sealed bundle again
Agent Start And atirc Mint
spec.agent {envFile}(default/etc/atirc/atirc.env) needsspec.secretsRef- after
VerifyReceipt,ensureAtircToken(internal/market/requester/atirc.go) mints withchat.atirc.mint(outside.md), lease ={receipt, termination: at-uri of the bidder's vm.terminated payload at EventRKeys(TerminationKey(receipt)), contract: accept uri}(contractLease) - the token goes into the bundle entry at envFile as
ATIRC_TOKEN; getSecrets and the sealed fallback serve the bundle without that entry until it is minted - every fresh mint publishes
guest.secretsUpdated; the guest fetches again;atirc-agent-env.pathrunssystemctl try-restart --no-block atirc-agent.servicewhen the envFile changed (never a start) run request agent <name>makes an outboundguest.agentStart; the guest agent runssystemctl start --no-block atirc-agent.service- every mint is recorded under
atircMintedin the bundle secret; statusstatus.atircRevokes(Done, Pending, Abandoned)
sequenceDiagram
autonumber
participant R as Requester
participant A as atirc
participant V as requester OpenBao bundle
participant B as Bidder
participant G as guest
R->>R: receipt verified (ReceiptOk)
R->>A: chat.atirc.mint subhandle from the RFP rkey, lease receipt + vm.terminated at-uri + accept
A-->>R: token with explicit exp
R->>V: ATIRC_TOKEN into envFile entry, record atircMinted
R->>B: submitEvent guest.secretsUpdated
B->>G: subscribeEvents secretsUpdated
G->>R: getSecrets again (comms Firehose: the sealed bundle again)
G->>G: envFile sha256 changed, try-restart atirc-agent.service
R->>B: submitEvent guest.agentStart (run request agent)
B->>G: subscribeEvents agentStart
G->>G: systemctl start --no-block atirc-agent.service
G->>A: atirc agent joins as subhandle
- release: the leased token is revoked before
vm.deletewhile its lease is alive; the rest in the background from a release marker (market.md) - when the VM ends without a release, atirc ends the token through its
vm.terminatedlease
Guest Requester (R2) Events
- a contract with
spec.association.fromGuestruns a requester inside the guest; full flow: identity.md guest.requesterDid: the guest reports the DID of its requester; the requester then readsmarket.associationRequestby onegetRecordand writes the contract-scopedmarket.association(lexicons-market.md)guest.r2Startstartssocialweb-r2.serviceas userr2(run request r2 <name>)- release of the parent:
guest.r2Releasefirst, then wait forguest.r2Released(GuestRequesterReleaseTimeout), then atirc revokes, thenvm.delete
Never
- a guest never holds a repo key; a guest never posts
guest.secrets,guest.agentStart,guest.secretsUpdated,guest.r2Startorguest.r2Release - the bidder never opens a sealed body
- no private key, SDP, ICE candidate or IP address in any record, object or log
- no sealed bundle unasked
- no fourth guest transport (iroh, opentunnel https, webrtc only; ../SYSTEM.md)
See Also
- ../SYSTEM.md, market.md, lexicons-market.md, identity.md, outside.md
- plans:
docs/plans/0034-webrtc-guest-transport.yaml,docs/plans/0035-atirc-agent.yaml,docs/plans/0036-record-association.yaml