Compute Contract Flow - Complete Architecture Map
Generated 2026-07-12. Maps every layer from spec (lexicons) through ABC interfaces, transport implementations, Hono factories, CLI entrypoints, e2e integration test, guest tunnel-subscriber transport, onNetwork event flow, and ephemeral JSR registry.
Brought into this repo from publicdomainrelay/open-architecture (COMPUTE_CONTRACT_FLOW_MAP.md at d722a0e) and updated for the current lexicons (lexicons/) and the Go code of this repo. The TypeScript repos it was generated from are no longer where the flow runs: every section keeps its heading and says what it is today; a section whose subject has no successor keeps a one-line note.
- this map: the owner's end-to-end map of the layers and the flow
- flow.md: one real contract, step by step, with its records
- every NSID, one line each: glossary.md
TypeScript (this map at d722a0e) | today (Go, this repo) |
|---|---|
ABC layer lib/abc/<concept> | internal/contract/<concept> (small interfaces), api/ (types) |
lib/<concept>-<transport> | internal/<concept>/<impl> |
lib/hono-factory-* | internal/services/<svc> (routes) and internal/app/<root> (composition) |
CLI hono-* | cmd/socialweb-computer (run bidder, run request, run requester, dev up, ...) |
| layer rules | AGENTS.md "Architecture rules", scripts/check-architecture.sh |
Repos Involved
| Repo | Role |
|---|---|
compute-contract | Schema-only: AT Protocol lexicons + example data. Today: lexicons/ of this repo |
atproto-market | Primary: All market ABCs, impls, factories, CLIs (hono-bidder, request-vm-ssh), e2e test (compute-contract-full-flow). Today: internal/market/{requester,bidder,participant}, internal/atproto/market, cmd/socialweb-computer |
hono-compute-provider | Compute provider ABCs, impls (local container/QEMU, DigitalOcean), OIDC issuer, RBAC, Hono factories, CLI. Today: internal/computevm (ComputeVM), the VM runtime (Firecracker, QEMU) and cmd/socialweb-vmexec; the OIDC issuer is the bidder's OpenBao identity engine behind the GuestControlPlane (internal/services/guestcontrolplane, internal/guestidentity) |
did-key-relay | Relay: dispatcher routes WebSocket tunnels by SNI subdomain - requester -> relay -> bidder -> guest. Today: the Go ingress relay at xrpc.fedproxy.com (internal/atproto/ingress) and the IngressProxy component; it carries market XRPC and PDS traffic for parties without a public host, no guest ssh |
typescript-helpers | Cross-repo shared: serve, logger, cli-args-env, compute-spa-keypair-noble, compute-spa-relay-client, firehose-watcher-*. Today: vendored in typescript-helpers/ only for did-key-associator; the Go side has internal/kit/* |
hono-pds | AT Protocol PDS (repo storage, record CRUD). Today: internal/atproto/pds, the Pds component (internal/services/pds, internal/pds/local) |
deno-worker-sandbox | Deno worker compute (separate compute path, not VM). Today: compute kind deno on a bidder (internal/market/bidder/sandbox.go, event vm.sandbox) |
deno-macos-runner-desktop | Desktop bidder: badge blue keys, device keys, OAuth. No successor here (its OAuth scope set DesktopOAuthScope remains in internal/atproto/oauth/scope.go) |
open-architecture | Docs-as-code stubs referencing all production implementations. This map's source |
Spec Layer: Lexicons (compute-contract repo)
All under lexicons/com/publicdomainrelay/temp/ (pre-stable temp namespace), plus the namespaces listed in glossary.md. * = required; every market.* record and event payload also has signatures (network.attested.signature).
| NSID | Record Type | Schema |
|---|---|---|
com.publicdomainrelay.temp.compute.vm | record | { role*, kind, cpus, mem, disk, nestedVirt, image {url, sha256}, network, location, user_data, net, expiresAt, createdAt } |
com.publicdomainrelay.temp.market.rfp | record | { domain, payload*: StrongRef, submitBid, ingress[], policies[]: StrongRef, createdAt } (was policy?: StrongRef) |
com.publicdomainrelay.temp.market.bid | record | { rfp: StrongRef, payload*: StrongRef, config: StrongRef, ingress[], createdAt } (was bidConfig; submitAccept is gone: the requester calls the bidder's offering endpoints[]) |
com.publicdomainrelay.temp.market.bids.x402 | record | { cost, currency, frequency, prepay, url } - X402 pricing payload (defined, not written today) |
com.publicdomainrelay.temp.market.bids.free | record | { reason*, cost } - free pricing payload ({reason: free, cost: 0}) |
com.publicdomainrelay.temp.market.accept | record | { rfp*: StrongRef, bid*: StrongRef, payload, submitEvent, ingress[], createdAt } (no payload today) |
com.publicdomainrelay.temp.market.receipt | record | { rfp*, bid*, accept*: StrongRef, payload: StrongRef (the compute.vm), cid* (binds the accept), submitEvent, ingress[], createdAt } |
com.publicdomainrelay.temp.market.offering | record | { appliesTo*: string[], endpoints[{kind: iroh|webrtc|https, address}], ingress, maxCpus, maxMem, nestedVirt, images, createdAt*, refreshedAt, withdrawnAt } - bidder advertisement, rkey self (was endpointUrl) |
com.publicdomainrelay.temp.market.heartbeat | record | { offering*, createdAt*, version } - liveness, rkey self, fresh for 300 s (new) |
com.publicdomainrelay.temp.market.event | record | { receipt*: StrongRef, payload*: StrongRef, createdAt } - lifecycle events (vm.onNetwork, vm.hostKeys, guest.*, vm.delete, vm.terminated, ...) |
com.publicdomainrelay.temp.market.policies.{builtin,service,denoWorker} | record | Today: computer.socialweb.temp.policy.ghalite { name, workflow, args, requester, perspective, policies[], createdAt }, strongRef'd from market.rfp.policies[]; the engine denies denoWorker and computer.socialweb.temp.policy.typescript; builtin and service have no successor (policy.md) |
com.publicdomainrelay.temp.compute.config.wif.simple | record | { accept_path, issuer_uri, to_issue, token_path, url_path, url_route, subject, actx } - WIF bid config (actx_path -> actx; older records carry both) |
com.publicdomainrelay.temp.agent.class | record | Agent class template: name, description, skills, parent. Not in lexicons/ today; no successor |
com.publicdomainrelay.temp.agent.skill | record | Agent skill: name, description, content, examples. Not in lexicons/ today; no successor |
com.publicdomainrelay.temp.auth.allowlist.rbacDid | record | RBAC allowlist: { protects: { [key]: { service, scope } }, allowed: { [key]: string[] } }. Today an OAuth scope; the test-account manifests seed one per account and nothing reads it |
com.publicdomainrelay.temp.market.relays | record | { relays*: string[], createdAt* } - relay URL advertisement for auto-discovery, rkey self (read in discovery; no Go writer) |
com.publicdomainrelay.temp.market.association, market.associationRequest | record | the grant beside a link.ident.endorsement (rkey = the agent DID), and a guest requester's request for one (rkey = the principal DID) (new: identity.md) |
com.publicdomainrelay.temp.market.submitRfp, submitBid, submitAccept, submitEvent | procedure | the four market XRPC calls (market.md) |
com.fedproxy.rbac | record | Today the requester's workload identity roles for its VMs: { roles: { <vm>: { role_name, definition: { iss, aud, sub, policies } } }, policies, createdAt } at rkey node.<accept rkey>; it lets the guest mint a token for the requester's audience (getSecrets), not an SSH host key registration (was { service, issuer, actx, operations }) |
Record lifecycle chain:
compute.vm (payload) --> market.rfp --> market.bid --> market.accept --> market.receipt
| | |
+-- policies ---+ +-- market.event (vm.hostKeys, vm.onNetwork,
guest.*, vm.delete, vm.terminated)
ABC Layer: Pure Interfaces
Today the abc layer is internal/contract/<concept> (small Go interfaces and pure types; api and stdlib only) and the shared types are api/. The TypeScript interfaces below have no one-to-one Go type; each keeps a one-line note.
market-abc (atproto-market/lib/abc/market/)
Record resolution & graph: RecordResolver, ContractGraph, StrongRef. Today: internal/atproto/market (StrongRef, generated record types, RepoStore.Resolve), the contract graph as the ComputeContract's status.contract (rfp, bid, accept, receipt strongRefs).
Settlement: Settlement, SettlementCtx. No successor: only bids.free is bid; no receipt minting endpoint.
Callbacks (event system): RfpCallbacks, SubmitRfpCallback, SubmitBidCallback, SubmitAcceptCallback, EventCallbacks, EventCallback. Today: the XRPC routes enqueue kcp objects (Bid, StateSync, ContractEvent) and the controllers act on them (internal/services/bidder/routes.go, internal/services/requester/routes.go).
Attestation: AttestationKeypair. Today: internal/atproto/market/keys.go (secp256k1 JWK signer files) and attest.go.
market-bidder-abc (atproto-market/lib/abc/market-bidder/)
ActiveContract, ContractEvent, CallbackSet, CallbackFactoryDeps, MarketBidderProviderRef. Today the active contracts are kcp objects (Bid, ComputeVM, StateSync) of the bidder's kcp, not an in-memory map; the bidder's own ContractEvent type is gone (on the requester side ContractEvent is the kcp kind of one guest event).
requester-abc (atproto-market/lib/abc/requester/)
RequesterPDS, ContractFlowOptions, ContractFlowResult, SshSessionProvider, CollectedBid. Today: the MarketRequester root and its Requester component; the options are the ComputeContract spec (api/v1alpha1/types_computecontract.go), the result is its status (phase, status.contract, status.bids), the ssh session is internal/stack/request/ssh.go.
market-policy-abc (atproto-market/lib/abc/market-policy/)
TrustPolicy-only-me/tangled-vouch/mutuals/open;WorkPolicy-under-4-cpus/bid-payload: today the same names are bundled gha-lite workflows,bidder-*andrequester-*(internal/policyengine/bundled-actions/workflows/)PolicyRegistry,PolicyEvalCtx: todayinternal/policyengine(the PolicyEngine component,runs.Client)
policy-abc (atproto-market/lib/abc/policy/)
PolicyHandler<T>, PolicyRegistry. Today: internal/contract/policy and internal/policyengine/registry.
compute-provider-abc (hono-compute-provider/lib/abc/compute-provider/)
ComputeProvider, ComputeAtproto, VM, RbacProvisioner. Today: the ComputeVM kind and its controller (internal/controllers/computevm, internal/computevm), the FirecrackerVM backend; the RBAC record is the requester's com.fedproxy.rbac, read by the bidder (internal/guestidentity).
compute-contract-gateway-abc (atproto-market/lib/abc/compute-contract-gateway/)
ComputeContractGateway. No successor: the gateway today serves tenant Kubernetes clusters (com.publicdomainrelay.temp.cluster.*, infra.md); a VM is requested with run request, run requester or the ssh gateway.
Implementation Layer: Transport Bindings
requester-xrpc (atproto-market/lib/requester-xrpc/mod.ts - 1064 lines)
The spine. Orchestrates the full contract flow from requester side. Today: internal/market/requester (contractRunner in runner.go), run by the Requester component (internal/services/requester) of a MarketRequester (run request, run requester, pkg/embedded).
Exports: createRequesterPDS, runComputeContract, createSshSessionProvider, ensureWebsocat, discoverBiddersFromRelay(s), autoDiscoverRelayUrls. Today: the MarketRequester composes its identity (a localRepo Pds or an OAuth/password identity) and ingress; contractRunner.Run drives the flow; ssh is internal/stack/request/ssh.go (dumbpipe connect, no websocat); discovery is internal/market/requester/discovery.go and market.go.
runComputeContract - the full 11-step flow: (today contractRunner.Run / requestOnce)
1. ssh-keygen ed25519 -> generate ephemeral keypair for guest
today: the invocation's key (internal/stack/request/ssh.go EnsureKey) goes into spec.sshAuthorizedKeys
2. buildDefaultUserData(ssh public key) -> cloud-init YAML
today: cloudinit.BuildUserData + the module registry, with the iroh module (guestseed.WithIrohTransport)
3. pds.createRepoRecord(compute.vm) -> payload record on requester PDS
today: putRecord at a TID (putSetupRecord), unsigned; first the policy record (computer.socialweb.temp.policy.ghalite)
4. pds.createSignedRepoRecord(market.rfp) -> signed RFP referencing compute.vm
today: putRFP: payload, policies[], submitBid, ingress[]; signed
5. discoverBiddersFromRelays -> query relay index + firehose watcher DIDs
today: relay listReposByCollection + vouched DIDs + endorsed agents, fresh heartbeat, offering capabilities
6. submitRfp XRPC -> POST to each discovered bidder's submitRfp endpoint
today: to the first endpoint of its offering (iroh, webrtc, https); answers may carry declined {kind, reason}
7. await bidWindowSec -> collect bids in pds.pendingBids
today: bidWindowSeconds (30 s), ended early by the first free bid the scope policy allows; one getRecord catch-up per bidder
8. pick lowest-cost bid -> cost from bid payload
today: first allowed free bid, else lowest cost after the window
9. (optional) evaluateRfpPolicy -> whenever the RFP carries a policy strongRef
today: always: the full policy on the winner, with the attached record's body (a deny: policy_rejected)
10. pds.createSignedRepoRecord(market.accept) -> submitAccept XRPC to winner
today: rkey SessionRKey("accept", ...); submitAccept re-sent until the receipt (5 min); 409 CapacityExceeded -> next bid
11. verify receipt -> verifyRecordSignatures + verifyRemoteProof
today: market.VerifyReceipt (signature + the cid binding of the accept); then wait for vm.hostKeys and vm.onNetwork (Held)
12. sshProvider.pollReady -> SSH into guest, exec program
today: ssh -o ProxyCommand='dumbpipe connect <iroh ticket>' with the host keys of vm.hostKeys (StrictHostKeyChecking=yes), every 5 s
13. market.event (vm.delete) -> tear down guest (unless --keep-vm)
today: unless --hold; then the bidder's vm.terminated, and the requester deletes its contract records
Bidder discovery cascade:
relay index (listReposByCollection on offering NSID)
+ vouch graph (sh.tangled.graph.vouch of self, spec.operatorDID and the walk roots)
+ endorsed agents (link.ident.endorsement whose walk reaches the operator)
+ --bidder-dids (requester spec.bidderDids: named, no heartbeat needed)
- --deny-bidder-dids (contract spec.denyBidderDids) and bidders that declined this contract
- no fresh market.heartbeat, or an offering lacking the VM's cpus / nestedVirt / images
(--allow-bidder-dids narrows to that set)
The live firehose offering watcher is gone: the relays list every repo with an offering. Detail: market.md.
market-bidder (atproto-market/lib/market-bidder/mod.ts - 474 lines)
Bidder lifecycle orchestrator. Today: the MarketBidder root (internal/app/marketbidder), its Bidder component (internal/services/bidder, internal/market/bidder), GuestControlPlane, Pds, PolicyEngine, OpenBao and EventStreams.
beginServe() flow: (today: the MarketBidder composition and Bidder.Run)
1. Provider setup (each provider.setup())
today: the VM runtime and the guest image (verified before the offering is written)
2. Build callback deps (did, signer, attestationKp, relay, activeContracts, ...)
today: bus handles of the Bidder component (repo, signer, policy, compute)
3. Merge callbacks from all providers + optional callbackFactory
today: one bidder serves every compute kind it has (--compute-kinds vm,deno)
4. Wire Hono routes via createMarketFactory:
- POST /xrpc/com.publicdomainrelay.temp.market.submitRfp
- POST /xrpc/com.publicdomainrelay.temp.market.submitBid (parsed only)
- POST /xrpc/com.publicdomainrelay.temp.market.submitAccept
- POST /xrpc/com.publicdomainrelay.temp.market.submitEvent
- optional rfpScopeFilter
today: internal/services/bidder/routes.go; the scope lane of the bidder's policy runs on every RFP and accept
5. Start firehose watchers (pull-mode RFP discovery)
today: EventStreams from the relay and the Jetstreams (market.rfp, market.accept, market.event)
6. serve.onConnected:
- ensureOperatorAllowlist (rbacDid allowlist record) today: none (the operator's ident.link pair)
- ensureOffering (advertise bidder on relay index) today: market.offering/self
- startOfferingRefresh (periodic re-commit) today: re-checked every 300 s, rewritten on a change; market.heartbeat/self every 60 s
7. serve.beginServe()
today: every listener binds port 0; the endpoints come from its Exposures (iroh ticket, https) and its webrtc listen record
Accept scope filter chain: (today: the bidder's policy, default bidder-tangled-vouch, scope then full lane, on the RFP and again on the accept)
only-me: todaybidder-only-me: the requester is the bidder, or resolves to the bidder's operator (the identlink walk), not a badgeBlueKeysrequester_associateclaimtangled-vouch/mutuals: todaybidder-tangled-vouch(a vouch between the two sides' walk ancestors) andbidder-mutuals(vouches both ways)- no policy configured: today there is always one (
bidder-tangled-vouch);openonly when named, never prod
Bidder association check (3 paths): today one path, the identlink walk (agent DID document agent-of, the principal's link.ident.endorsement + market.association, up to 100 levels: identity.md). badgeBlueKeys with service: requester_associate survives as the ssh key claim of the ssh gateway; bidder_associate has no successor.
market-bidder-compute (atproto-market/lib/market-bidder-compute/mod.ts - 364 lines)
VM compute bidder callbacks. Handles the compute.vm RFP -> bid -> provision -> destroy lifecycle. Today: internal/market/bidder (bids.go, submit.go, adapters.go, provision.go).
onRfp (submitRfp callback): (today SubmitRFP, then decideBid in bids.go)
1. (optional) evaluateRfpPolicy - if RFP has policy ref
today: always: window, RFP signature, requester DID, payload; scope policy; own workflow + every attached policy (full)
2. computeProvider.createBidConfig(nowIso) -> wif.simple bid config
today: compute.config.wif.simple at <bid rkey>-config
3. createRepoRecord(market.bids.free) -> pricing payload (cost: 0)
today: at <bid rkey>-payload, signed
4. createSignedRepoRecord(market.bid) -> signed bid
today: at market.BidRKey (one bid per RFP)
5. callService(submitBidUrl, submitBid) -> POST bid to requester
today: the same, to the RFP's submitBid
onAccept (submitAccept callback): (today SubmitAccept, then acceptContract and placeAccepted)
1. Resolve RFP -> payload (compute.vm) -> user_data
today: first a capacity check and a 10 min reservation (409 CapacityExceeded); then the accept's signature, policies again, the bid is its own
2. Resolve bid -> bidConfig (wif.simple)
3. Build accept bundle: { accept, rfp, bid, bid_config, vm }
today: InjectAcceptBundle writes /root/secrets/publicdomainrelay.com/market/accept.json
4. computeProvider.injectAcceptBundle(user_data, bundle) -> patched cloud-init
today: plus the network, workload login, guest-onnetwork.service, the guest agent and setup-guest-binaries.service (internal/guestseed)
5. computeProvider.provision(vm_with_bundle, issuerDid) -> run container/VM
today: a ComputeVM owned by the Bid, then a FirecrackerVM (after the receipt)
6. Create receipt: market.receipt with attestation CID binding accept->receipt
today: at market.ReceiptRKey; cid = the accept's attestation CID; payload = the compute.vm
7. Store in activeContracts map
today: kcp objects (Bid Won, ComputeVM)
8. Fire onContractChange({ type: "accepted" })
9. Return { uri: receiptUri, cid: receiptCid, submitEvent: relay.proxyUrl }
today: submitAccept answers 202 {id} at once; the requester finds the receipt by one getRecord
onVmDelete (submitEvent callback): (today applyRelease, verifyInboundDelete)
1. Extract receipt ref from event
2. Verify receipt in activeContracts today: the receipt is in the bidder's repo
3. Verify issuerDid == acceptAuthor today: and both signatures, same receipt uri + cid
4. computeProvider.destroy(providerId) today: the ComputeVM is deleted
5. Fire onContractChange({ type: "terminated" })
today: compute.events.vm.terminated {reason: deleted_on_request} + market.event
6. Delete from activeContracts
cloud-init-common (atproto-market/lib/common/cloud-init-common/mod.ts - 325 lines)
Pure YAML generation. Zero I/O. Today: internal/atproto/cloudinit (BuildUserData, the module registry) and, on the bidder, internal/guestseed.
Exports: flattenLabel, buildDefaultUserData, patchDefaultUserData, buildTunnelUserData, CloudInitContext, TunnelCloudInitContext. Today: BuildUserData(BuildOptions), which keeps the base user_data's entries and adds the modules' (iroh always; tunnels, secrets, agent, association as asked); the fedproxy and tunnel-subscriber variants are gone.
buildDefaultUserData output (fedproxy transport): today the iroh transport:
#cloud-config
write_files:
/root/.ssh/authorized_keys - the contract's spec.sshAuthorizedKeys
/etc/ssh/sshd_config.d/10-iroh.conf - key-only root (PermitRootLogin prohibit-password, no passwords)
setup-iroh.sh, iroh-listener.sh - dumbpipe (baked in the image) listen-tcp 127.0.0.1:22
/run/guest-iroh-ticket, /run/guest-fqdn - iroh://<ticket>
accept.json, guest-login, guest-onnetwork.service, send-onnetwork.sh (the bidder's additions)
setup-guest-binaries.service - guest binaries from the GuestControlPlane, sha256 checked
runcmd:
one systemctl daemon-reload, --no-reload enables, every start last (AGENTS.md "Guest user data")
(was: websocat.conf, setup-websocat.sh/.service/.path, websocat.service, fedproxy-client.service)
Guest transport chain: today iroh:
SSH client (requester)
ProxyCommand dumbpipe connect <iroh ticket from vm.onNetwork>
-> iroh (n0 relay or a direct path), end to end encrypted to the guest's node
-> dumbpipe listen-tcp 127.0.0.1:22 on the guest
-> sshd (key-only root; host key pinned from vm.hostKeys)
Two opt-in transports per tunnel tag: opentunnel https and webrtc (the guest agent). No other (../SYSTEM.md).
compute-provider-local (hono-compute-provider/lib/compute-provider-local/mod.ts)
Local VM/container provisioning. Two modes: container (lightweight, systemctl-shim) or VM (QEMU/KVM). Today: VMs only, Firecracker or QEMU under socialweb-vmexec (with the nf_tables fence swcguest), from the bidder's pinned guest image or a requester image; no container mode.
Exports: createLocalComputeProvider, runContainer, spawnVM, pollSsh, buildContainerImage. Today: the ComputeVM controller and the VM runtime; the guest image is pinned by sha256 in internal/versions/versions.json.
Provisioning chain (container mode): today the VM chain:
placeAccepted(accept)
-> imageRefused, reserve capacity
-> user_data (accept bundle, network, guestseed) and the vault write
-> ComputeVM (owner: the Bid) -> FirecrackerVM (owner: the ComputeVM)
-> socialweb-vmexec loads the fence, tap + pasta, the VMM boots the image
-> GuestIdentityGrant (from the requester's com.fedproxy.rbac roles)
-> the guest logs in, binds its host key, reports vm.onNetwork
compute-provider-digitalocean (hono-compute-provider/lib/compute-provider-digitalocean/mod.ts)
DigitalOcean droplet provisioning. No successor: bidders run VMs on their own hosts. The guest secrets path /root/secrets/digitalocean.com/serviceaccount/ keeps its name (guestseed.SecretsPrefix).
oidc-issuer-hono (hono-compute-provider/lib/oidc-issuer-hono/mod.ts)
Workload identity provisioning. Guest proves possession of SSH host key -> receives OIDC token. Today the bidder's OpenBao (its identity engine and the sshsig auth plugin, cmd/openbao-plugin-auth-sshsig) behind the GuestControlPlane at http://192.0.2.1:<port>.
Routes: today /v1/auth/<mount>/bind, the login, /v1/identity/oidc/token/<role>, the issuer's /.well-known/keys; plus the GuestControlPlane's POST /v1/events, GET /v1/downloads/<sha256>/<name> and compute.guest.subscribeEvents.
Provisioning prove flow: today:
Guest boots -> cloud-init runs guest-login
-> bind {role, bind_secret, host_key, signature} signed with ssh_host_ed25519_key
-> challenge, login -> token in /root/secrets/openbao/token
-> the bidder records the bound host key on the ComputeVM (vm.hostKeys)
-> guest-login token <aud> -> an OIDC token for the requester's audience
(sub actx:<bidder>:plc:<requester>:role:<vm>), sent to the requester's getSecrets
Hono Factory Layer
Today: internal/services/<svc> turns XRPC/HTTP routes into contract calls; internal/app/<root> composes the components.
hono-factory-market-atproto (atproto-market/lib/hono-factory-market-atproto/)
Wires the 4 XRPC endpoints + service auth verification. Today: internal/services/bidder/routes.go (all four; submitBid parsed only) and internal/services/requester/routes.go (submitBid, submitEvent, getSecrets). Service auth: aud <DID>#pdr_temp_market, lxm = the NSID; the token issuer must author the record (market.AuthorizeRecord). Record signatures verify when the key is in the issuer's DID document or bound by a badgeBlueKeys signer key binding.
Routes:
POST /xrpc/com.publicdomainrelay.temp.market.submitRfp- bidderPOST /xrpc/com.publicdomainrelay.temp.market.submitBid- requesterPOST /xrpc/com.publicdomainrelay.temp.market.submitAccept- bidderPOST /xrpc/com.publicdomainrelay.temp.market.submitEvent- bothGET /xrpc/com.publicdomainrelay.network.attested.verify- todaynetwork.attested.verifyis defined inlexicons/network/attested/, neither served nor calledGET /.well-known/did.json- today parties are did:plc; a did:key party (ingress) needs no DID document
hono-factory-market-settlement-free / hono-factory-market-settlement-x402
Routes: GET /free/receipt/*, GET /x402/receipt/*. No successor: the receipt is a record the bidder writes; x402 is not exercised today.
hono-factory-requester-xrpc
Standalone requester - only registers submitBid endpoint. Today the requester ingress serves submitBid, submitEvent and compute.secrets.getSecrets, reached through the did:key ingress when it has no public host.
hono-factory-compute-contract-gateway-xrpc
Gateway for compute contract requests (VM + worker): com.publicdomainrelay.compute.contract.requestComputeVM, requestComputeWorkerEphemeral, requestComputeWorkerPersistent, deleteCompute. No successor: these NSIDs are gone.
hono-factory-policy-builtin
Policy engine - evaluates PolicyHandler[] in order, first deny short-circuits: com.publicdomainrelay.market.evaluatePolicy, com.publicdomainrelay.gate.registry.workerManifestPermissions. Today the PolicyEngine component runs in each application (gha-lite workflows in an embedded deno); no policy XRPC; every workflow must allow.
hono-factory-compute-provider-local / hono-factory-compute-provider-digitalocean
DigitalOcean-compatible API surface (/v2/account, /v2/droplets). No successor.
CLI Layer
hono-bidder (atproto-market/hono-bidder/mod.ts - 368 lines)
Bidder CLI. Today: socialweb-computer run bidder (foreground) and install bidder (a systemd user unit) (../bidder.md).
Startup: today:
- Resolve options:
run bidderoptions and--bidder-spec-file(a MarketBidderSpec) - Create keypair (Secp256k1):
<state>/attestation.jwk - Create AT Protocol agent (remote or local PDS): a
localRepodid:plc on its own Pds (an agent of the operator), or--atproto-oauth-qr(the operator's account) - Register PDS with relay market registries: its PDS requestCrawls our relay
- Create ATProto instance (badgeBlueSigner, PLC directory): the
badgeBlueKeyssigner key binding (service: bidder_attestation) - Build providers list:
--compute-kinds vm,deno - Each provider gets its own relay + serve: one bidder, one market endpoint set (iroh, webrtc, https)
- Create market bidder with providers + firehose watchers: the MarketBidder root
bidder.beginServe(): the offering and the heartbeat- QR association flow (bidder_associate): the operator signs in at the MarketIdentity
operatorURL and writes the ident.link pair
request-vm-ssh (atproto-market/request-vm-ssh/mod.ts - 239 lines)
Requester CLI. Today: socialweb-computer run request (one contract) and run requester (long-lived) (../quickstart-prod.md).
Startup: today:
- Resolve options
ensureWebsocat(): gone; ssh needsdumbpipe(iroh) or the webrtc proxy (run request proxy)createRequesterPDS(): the MarketRequester's identity (OAuth QR, browser, password, orlocalRepowith an association)- Optional firehose offering watch: comms mode
Both(default) orFirehosestreams pds.beginServe(): the requester ingress (did:key ingress by default)- QR association flow (requester_associate):
--atproto-oauth-qrsigns in as the user's own account runComputeContract(pds, opts): the ComputeContract- Result logged, PDS disposed: the invocation is released (
--holdkeeps it)
SSH flow (inside runComputeContract):
ssh-keygen ed25519 -> ephemeral keypair today: the invocation's id_ed25519
buildDefaultUserData(publicKey) -> cloud-init today: BuildUserData, iroh module
... RFP -> bid -> accept -> provision ...
pollReady(privateKeyPath, vmFqdn) -> SSH probe every 5s
today: the iroh ticket, the pinned host keys, every 5 s
runSession(privateKeyPath, vmFqdn, execProgram) -> interactive SSH
today: run request --exec / run request ssh
compute-contract-full-flow (atproto-market/compute-contract-full-flow/run_full_flow.ts - 390 lines)
Single-process e2e integration test. Today: a market network on one machine (socialweb-computer dev up --profile market-network: its own PLC, relay, PDSes and a bidder in one kcp, ../quickstart-local.md) and the Rust system tests (tests/, docs/acceptance/).
Architecture: today:
One kcp (market network), each application a workspace root:<app>:
|-- Plc, Relay, Pds alice/bob, ingress dispatcher (TLS front)
|-- bidder: MarketBidder (Pds, Bidder, GuestControlPlane, PolicyEngine, OpenBao)
|-- requester: run request --network <instance>
|-- every application talks only over the atproto protocol
`-- dev down removes it
Key difference from production: a network-local PLC, relay and PDSes, and *.localhost names, instead of plc.directory, our relay and bsky PDSes; real VMs on the host.
Policy & Settlement Layer
Policy modes
| Mode | Impl | Behavior |
|---|---|---|
only-me | bidder-only-me, requester-only-me | the counterparty is self or resolves to self or self's operator (identlink walk) |
tangled-vouch | bidder-tangled-vouch, requester-tangled-vouch (the defaults) | a DID of self + its walk ancestors vouches (sh.tangled.graph.vouch) a DID of the counterparty + its ancestors, or they share an operator |
mutuals | bidder-mutuals, requester-mutuals | vouches both ways (tangled vouches only) |
| (none) | - | today there is no "none": the default is tangled-vouch; open accepts all, only when named, never prod |
Every name above is a bundled gha-lite workflow (internal/policyengine/bundled-actions/), run by the PolicyEngine in an embedded deno. The requester publishes the workflow it runs as computer.socialweb.temp.policy.ghalite and the RFP strongRefs it (policies[]); the bidder runs its own workflow and every attached one, and allows only if all allow. The trust snapshot (vouches between both sides' walk ancestors, at most 256 pairs) is seeded into each run. policies.builtin, policies.service and policies.denoWorker have no successor (the engine denies denoWorker) (policy.md).
Settlement modes
| Mode | Impl | Behavior |
|---|---|---|
free | market.bids.free | Zero-cost; the receipt is a record, no payment |
x402 | market.bids.x402 (lexicon only) | HTTP 402 Payment Required, receipt after payment. Not exercised today: no Go code writes bids.x402, accepts.* or receipts.* |
Policy evaluation flow (requester side, step 9):
always (no skip), on the winner, before the accept:
q.policy.Evaluate({ workflow: the attached record's body, mode: full,
self: the requester's market DID, subject = counterparty: the winner's DID,
rfp, bid })
-> if !allow: outcome policy_rejected, the contract fails
(each bid first: the scope lane, self = spec.operatorDID or the market DID)
Policy evaluation flow (bidder side, onRfp):
always, before the bid and again on the accept:
scope lane: its own workflow (default bidder-tangled-vouch), self = the bidder, counterparty = the requester
full lane: its own workflow, then every rfp.policies[] record body (perspective bidder)
-> if any deny: no bid (the accept: no receipt)
SSH Tunnel Path (full chain)
Today the path is iroh; fedproxy and websocat are gone from the guest path.
+---------------------------------------------------------------------+
| REQUESTER |
| |
| ssh -o ProxyCommand='dumbpipe connect <iroh ticket>' |
| -o StrictHostKeyChecking=yes -o HostKeyAlias=<receipt alias> |
| -o UserKnownHostsFile=<the keys of vm.hostKeys> |
| root@guest |
+----------------------------+----------------------------------------+
|
v
+---------------------------------------------------------------------+
| iroh (n0 relay or a direct UDP path) |
| |
| the ticket names the guest's node; the stream is end to end |
| encrypted to it. The bidder is not on the path |
+----------------------------+----------------------------------------+
|
v
+---------------------------------------------------------------------+
| GUEST VM |
| |
| dumbpipe listen-tcp 127.0.0.1:22 (iroh-listener.sh) |
| ticket written to /run/guest-iroh-ticket, reported as vm.onNetwork|
| |
| sshd |
| PermitRootLogin prohibit-password |
| authorized_keys: the contract's spec.sshAuthorizedKeys |
+---------------------------------------------------------------------+
The ssh gateway (ssh <handle>@socialweb.computer) runs the same flow as the user and hops to the guest over iroh (../SYSTEM.md). Per tunnel tag: opentunnel https, or webrtc through the guest agent (run request ssh --transport webrtc).
AT Protocol Record Flow
Requester PDS Relay/Network Bidder PDS
------------- ------------- ----------
1. compute.vm
{ role, cpus, mem, disk, user_data, expiresAt }
(first: the policy record computer.socialweb.temp.policy.ghalite)
2. market.rfp (signed)
{ domain: "compute",
payload: StrongRef(compute.vm),
submitBid: <requester ingress URL or did#pdr_temp_market>,
policies: [StrongRef(policy)] }
--> submitRfp / firehose -->
3. compute.config.wif.simple
(bid config)
4. market.bids.free
{ reason: "free", cost: 0 }
5. market.bid (signed)
{ rfp, payload, config }
<-- submitBid XRPC -------
6. collect bids (bidWindowSeconds)
7. pick: first allowed free bid, else lowest cost
8. evaluatePolicy (always, full lane)
9. market.accept (signed)
{ rfp, bid, submitEvent }
--> submitAccept XRPC ---->
10. capacity check + reservation
(409 CapacityExceeded)
11. market.receipt (signed)
{ rfp, bid, accept, payload,
cid: binds the accept }
<-- 202 {id}; the requester getRecords the receipt
12. verify receipt
(signatures + cid binding)
13. provision VM: cloud-init -> sshd + dumbpipe (iroh)
14. vm.hostKeys, vm.onNetwork { address: iroh://<ticket> }
+ market.event { receipt, payload }
<-- submitEvent XRPC ------
15. Held; SSH into guest over iroh ------------------------------------> sshd
16. market.event (vm.delete, signed)
{ receipt, payload }
--> submitEvent XRPC ------>
17. destroy VM
18. vm.terminated { reason } + market.event
19. delete own contract records (rfp, compute.vm, policy, accept, vm.delete, rbac, association)
(was 16: "market.receipt deleted": the bidder keeps its receipt; the requester deletes its own records.)
Key Architectural Decisions
Relay IS the registry. No separate service discovery database. Bidders advertise via
market.offeringrecords; requesters discover via relaylistReposByCollection(plus vouched and endorsed DIDs), and a bidder is a candidate only while itsmarket.heartbeatis fresh.One offering per bidder. Today the offering is always at rkey
self(market.OfferingRKey); a legacy TID rkey named by an old heartbeat is still read.Each provider owns its relay. Today one bidder has one market endpoint set (iroh ticket, webrtc listen record, https) in its offering; its PDS is reached through the did:key ingress when it has no public host.
Cloud-init IS the guest contract. Everything the guest needs is in the user_data the RFP carries plus what the bidder adds (
guestseed: guest binaries from its GuestControlPlane by sha256). No hand-assembled VMs. RFP flow is the only path to a live guest.Content-addressed attestation chain. Every
market.*record and event payload is signed (network.attested.signature). Receipts have an attestation CID binding accept -> receipt. Verification:market.VerifyRecordSignatures+VerifyReceipt(VerifyRemoteProof).OIDC for workload identity. Guest proves possession of SSH host key -> receives a token from the bidder's OpenBao. Today it uses it for the requester's getSecrets (secrets never in user_data), not for a relay.
Firehose as pull-mode RFP discovery. Bidder can watch firehose (subscribeRepos of our relay, or Jetstream v2) for
market.rfprecords instead of waiting for inboundsubmitRfpXRPC calls. Both paths work; todaysubmitRfpis the fast path and the streams the fallback (and the only path in comms modeFirehose).
Firehose & Bidder Discovery
Relay architecture: Today our relay is the Go relay (internal/atproto/relay, relay.mini-cloud-0002.chadig.com): it crawls each PDS that requestCrawls it, serves subscribeRepos (filtered on wantedCollections / wantedDids) and listReposByCollection.
Two watcher transports normalize to same FirehoseRecordEvent:
subscribeRepos- our relay (or a market network's):internal/events/relay,RelayEventSourcejetstream- Bluesky Jetstream v2 (wss://jetstream.us-east.bsky.network,us-west):internal/events/jetstream,JetstreamEventSource- both feed one sink per role, which drops a
uri|cidseen in the last 15 s; payload records are read through the strongRef, never from the stream
Bidder discovery cascade (5 stages in runComputeContract): today candidateSources in internal/market/requester/discovery.go:
autoDiscoverRelayUrls- todaymarket.relays/selfof self andspec.operatorDID, plus the network relay orspec.comms.relayUrlsdiscoverBiddersFromRelays-GET /xrpc/com.atproto.sync.listReposByCollection?collection=com.publicdomainrelay.temp.market.offeringon each relay -> union of DIDs- Vouch graph -
listRecords(<operator>, "sh.tangled.graph.vouch")-> filter kind != denounce -> extract DID from rkey (operators: self,spec.operatorDID, walk roots) - Live firehose offering watcher - gone; today: the agents the operators endorse (
link.ident.endorsement) --bidder-dids/--deny-bidder-dids- CLI overrides (and--allow-bidder-dids)
Offering record is the discovery contract:
- Bidder writes one
market.offeringatselfwith{appliesTo[], endpoints[], maxCpus, maxMem, nestedVirt, images, createdAt, refreshedAt}, and amarket.heartbeatatselfevery 60 s - Relay indexes it via its crawl ->
listReposByCollection - Requester queries relay index -> fetches the offering and the heartbeat from the bidder's PDS -> verifies
appliesToand the capabilities -> takes the first endpoint (iroh, webrtc, https) ->submitRfp
Bidder PDS registration: the bidder's PDS requestCrawls our relay (DefaultMarketRelayURL), or the market network's relay.
Single-process e2e test. Today: a market network in one kcp (
dev up --profile market-network) and the system tests (compute-contract-full-flow).Relay is NOT a database. It's a collection-indexing firehose proxy. Collection -> [DIDs] only. Actual record values fetched from bidder PDS directly. No central registry authority - any relay can index any PDS.
Round 2 Deep-Dive Findings
Handler Error Taxonomy (market-atproto/server.ts)
Today internal/services/bidder/routes.go, internal/services/requester/routes.go, internal/market/participant/comms.go:
| HTTP | error | message | Trigger |
|---|---|---|---|
| 400 | InvalidRequest | the body is not JSON: ... | Body parse failure |
| 400 | InvalidRequest | missing rfpUri or rfpCid | submitRfp missing fields |
| 400 | InvalidRequest | missing uri, cid, or record | submitBid/submitEvent missing fields |
| 400 | InvalidRequest | missing acceptUri or acceptCid | submitAccept missing fields |
| 401 | Unauthorized | (the service auth error) | JWT validation failure |
| 403 | Forbidden | (the authorize error) | the token issuer does not author the referenced record (market.AuthorizeRecord) |
| 403 | Forbidden | not the accept author | submitEvent to a bidder from another DID |
| 409 | RFPClosed | (the window error) | submitRfp after the 10 min bid window |
| 409 | CapacityExceeded | (the capacity refusal) | submitAccept that would overcommit the host |
| 500 | InternalError | the provisioning intent could not be recorded: ... | submitAccept could not record its StateSync |
| 503 | Unavailable | the bidder is not ready to authorize requests / the requester is starting | the component is not up |
| 503 | Suspended | the bidder's participation is suspended | spec.suspendParticipation |
The old rows expected com.publicdomainrelay.temp.market.event, record is missing a valid badge.blue signature, missing uri (verify), RecordNotFound, scope filter declined and ContractGraphError have no route answer today: signatures, the contract graph and the policy are checked after the route answers, on the bidder's Bid and StateSync objects (a refused one is logged and dropped, or the Bid fails).
Auth flow per handler (authorize()):
the bearer -> service auth (indigo ServiceAuthValidator: sig + lxm + aud + exp)
-> market.AuthorizeRecord(issuer, recordURI): the issuer authors the record
-> return the issuer DID
Attestation verification (verifyAuthored()):
market.VerifyRecordSignatures(record, repositoryDID)
-> for each signatures[] entry: VerifyInlineAttestation
-> CreateAttestationCID(record, entry metadata, repositoryDID)
-> secp256k1 low-S ECDSA over the CID bytes
-> the entry's key (did:key) is in the DID document of entry.issuer or the repo DID,
or bound by a badgeBlueKeys signer key binding in that repo
Attestation CID formula: DAG-CBOR + SHA-256 of { record (sans signatures), entry metadata (sans cid+sig), repository } -> CIDv1 (internal/atproto/market/attest.go).
Provisioning Internals (hono-compute-provider)
systemctl-shim.ts, Container image build, Container run args: no successor (no containers; guests are VMs with their own systemd).
SSH readiness: today the requester waits for vm.onNetwork and vm.hostKeys events, then probes ssh over iroh every 5 s.
QEMU (qemu-standalone/mod.ts): today the bidder's VMM is Firecracker or QEMU under socialweb-vmexec, booting the pinned guest image (firecracker-x86_64, firecracker-aarch64) or a requester image; the image is built by scripts/build-guest-image.sh and published content-addressed.
OIDC provisioning prove flow: today: see oidc-issuer-hono above (bind with the ssh host key, OpenBao token, then the audience token for getSecrets).
Relay Tunnel Internals (did-key-relay)
Today the Go ingress relay (internal/atproto/ingress, socialweb-computer internal ingress-relay at xrpc.fedproxy.com) and the IngressProxy component:
Nonce challenge/response registration: a subscriber registers {key, nonce, signatures} (internal/atproto/ingress/protocol.go), signed by its did:key; a did:key service auth issuer is verified without a DID document.
WebSocket frame format - JSON frames with $type; a response frame may carry headers. Detail: internal/atproto/ingress.
Tunnel byte bridging (startTunnel): no successor on the guest path (the guest uses iroh).
Reconnection: the IngressProxy reconnects with a backoff (ingress-relay-keepalive, ingress-relay-keepalive-timeout options).
Two transport variants: both gone from guests: fedproxy (buildDefaultUserData, fedproxy-client + websocat) and tunnel-subscriber (buildTunnelUserData). Today the ingress carries market XRPC (submitBid, submitEvent, getSecrets) to requesters and bidders, and the bidder's PDS.
Test Harness Patterns
No successor in TypeScript. Today the tests are Rust system integration tests (tests/system, harness tests/testkit) and compositions (tests/compositions/), one per acceptance runbook (docs/acceptance/); AGENTS.md "Tests".
Worker Compute Path (separate from VM)
Diff from VM: no tunnel, no ssh. Today the compute kind deno (compute.vm.kind: deno) on a bidder with --compute-kinds vm,deno: the bidder runs the program in a deno sandbox and reports compute.events.vm.sandbox {exitCode, timedOut, stdout, stderr} (internal/market/bidder/sandbox.go).
Manifest lifecycle, Permission model: no successor (no worker manifests).
ATProto Agent + Serve + Relay Wiring
Canonical bidder construction: today the MarketBidder composition (internal/app/marketbidder): the Pds (a localRepo did:plc with agent-of the operator, on plc.directory or the network's PLC), the attestation key (attestation.jwk), the IngressProxy (did:key ingress), the Bidder, the GuestControlPlane, the PolicyEngine and OpenBao, each a component in the core, linked on the bus (internal/component).
createServe lifecycle: today every listener binds port 0 and reports its address into its kcp object's status; peers find it by name (AGENTS.md "The kcp paradigm, port 0").
createXrpcRelay: today the IngressProxy: the subscriber's did:key gives it https://did-key-<did:key>.xrpc.fedproxy.com (a bidder's PDS endpoint and a requester's submitBid are such URLs).
PDS Internals (hono-pds)
Repo storage, applyWrites flow, List records: today internal/atproto/pds (MST, CAR, signed commits, subscribeRepos), in process for localRepo identities (internal/pds/local).
Service auth: today the in-repo PDS serves getServiceAuth (internal/atproto/pds/service_auth.go); a localRepo requester self-signs with its repo-key.json.
did:web document: today parties are did:plc (a localRepo account's DID document names its PDS endpoint and agent-of).
Compute Contract Gateway (separate API surface)
No successor (see hono-factory-compute-contract-gateway-xrpc).
Cross-Cutting Concerns
Config priority: today socialweb-computer options: flag, env, config.json (CONFIG_PATH_SOCIALWEB_COMPUTER), default (internal/clicfg/options.json); run request options after -- map to the MarketRequester and ComputeContract spec (deploy/apps/option-map.yaml).
CONFIG_PATH_*: today CONFIG_PATH_SOCIALWEB_COMPUTER (an installed bidder's config.json).
Logger, Error middleware: today internal/kit/logx (structured JSON lines).
Shutdown cascade (hono-bidder): today state is kcp objects: a stop keeps the state dir; the next start adopts the running units (HostProcesses, VMs) by unit name.
Partial failures: today:
- Bidder dies mid-provision: the Bid, ComputeVM and StateSync objects survive; the restarted core continues; an accept it cannot act on is given up (
bidder_accept_abandoned) - Requester dies mid-accept: the accept is at a deterministic rkey; a restarted runner reuses it and resumes from the recorded stage
- Relay disconnects: streams reconnect with a backoff from their cursor; submitRfp, submitAccept and submitEvent are retried
- Retries and timeouts exist at app level: the submitAccept re-sends, the receipt wait (5 min), the capacity wait rounds (30 s to 2 min, until the contract's deadline), the release retries
Files Referenced
Today (Go, this repo):
| File | Role |
|---|---|
internal/market/requester/runner.go, accept.go, market.go, discovery.go | Full requester-side flow, discovery, selection |
internal/market/requester/association.go, renterkey.go, secrets.go | Associations, guest DID tombstones, secrets and the rbac record |
internal/market/bidder/submit.go, bids.go, adapters.go, provision.go, vmsize.go | Bidder: submitRfp, bids, accepts, placement, capacity |
internal/market/bidder/offering.go, report.go, guestevents.go | Offering, heartbeat, vm and guest events |
internal/services/bidder/routes.go, internal/services/requester/routes.go | XRPC handlers + answers |
internal/atproto/market/attest.go, contract.go, records.go, nsid.go | Attestation, receipt verification, records, rkeys, NSIDs |
internal/atproto/cloudinit/ | Guest cloud-init (BuildUserData, modules) |
internal/guestseed/ | The bidder's user_data additions, guest binaries |
internal/services/guestcontrolplane/, internal/guestidentity/ | Guest events, downloads, workload identity |
internal/computevm/ | ComputeVM, termination reasons |
internal/guestagent/, cmd/socialweb-guest-agent | The guest agent: events, secrets, webrtc |
internal/policyengine/ | Policy engine + bundled workflows |
internal/identlink/, internal/policyengine/trust/ | The ident.link walk, the trust snapshot |
internal/atproto/ingress/, internal/services/ingressproxy/ | did:key ingress relay and client |
internal/atproto/relay/ | Our atproto relay |
internal/atproto/pds/, internal/pds/local/ | PDS |
lexicons/ | AT Protocol lexicon schemas |
The TypeScript files this table listed at d722a0e (atproto-market/, hono-compute-provider/, did-key-relay/, hono-pds/, typescript-helpers/, deno-worker-sandbox/, compute-contract/, open-architecture/) are in those repos.
Operational Supplement - Running the Flow
Repo Map
Today this one repo (socialweb-computer-kcp) holds the Go code, the lexicons, the guest agent, the policy actions and socialweb-meshd; did-key-associator/ (qr.fedfork.com) and typescript-helpers/ are vendored here. The other repos of this table (atproto-market, hono-compute-provider, did-key-relay, hono-pds, deno-worker-sandbox, deno-macos-runner-desktop, atproto-relay, hono-jsr, compute-contract, compute-spa, atproto-reverse-proxy) are not part of the flow today; open-architecture holds this map's source. The other repos the system uses: ../SYSTEM.md.
Production Startup Order
Today:
1. our relay and the did:key ingress relay (prod services; plc.directory)
2. bidders: install bidder (each signed in once by its operator); they follow the release channel
3. requesters: run request / run requester / the ssh gateway / the gateway, whenever
A requester needs a bidder with a fresh heartbeat; nothing else is ordered.
Single-Process E2E
Today, one machine, one kcp (../quickstart-local.md):
S=~/.swc/demo
socialweb-computer dev up --instance demo --profile market-network --host-backend proc --state-dir $S
socialweb-computer run request --network demo --state-dir $S --name vm1 --exec -- id
socialweb-computer dev down --instance demo --state-dir $S
E2E Trace (from actual run)
Today: the step order of a request on a local market, from its requester's lines: flow.md. The old trace's SSH failure (setup-websocat.path waiting for a DigitalOcean token) has no successor.
Test Commands
Today: the Rust system tests (from tests/; AGENTS.md "Tests: Rust system integration tests"); the docs checker scripts/check-docs.sh; deploy/check.sh --fast.
Deno Tasks
No successor (the TypeScript repos' tasks).
CLI Entrypoints (17 total)
Today one binary, socialweb-computer, with run bidder, install bidder, run request, run requester, install requester, run gateway ssh, serve gateway, install gateway, dev up, upgrade, rollback, check-host, ... (socialweb-computer -h).
| CLI | Config Path Env | Key Flags |
|---|---|---|
run request (was request-vm-ssh) | CONFIG_PATH_SOCIALWEB_COMPUTER | --name, --exec, --hold, --cpus, --mem, --secrets, --tunnel, --expires-in; after --: --policy, --policy-args, --bidder-dids, --allow-bidder-dids, --deny-bidder-dids, --atproto-oauth-qr |
run bidder / install bidder (was hono-bidder) | same | --handle, --compute-kinds, --bidder-policy, --bidder-spec-file, --bidder-operator-signin |
hono-compute-contract-gateway, hono-compute-provider, hono-policy | - | no successor |
Complete Env Var Reference (compute contract flow subset)
Today the options are internal/clicfg/options.json (each with its env name) and deploy/apps/option-map.yaml; secrets are never env of a unit (OpenBao, 0600 files). The old request-vm-ssh and hono-bidder env lists have no successor one by one.
Codegraph Cheatsheet
No successor here (the org-root codegraph index of the TypeScript repos).
Scripts
Today scripts/ of this repo (e.g. scripts/install.sh, scripts/oauth-signin.ts, scripts/associate-bidder.ts, scripts/deploy.sh); the polyrepo scripts of this table have no successor.
Package Coverage: 137 packages across 13 repos
No successor (a coverage count of the TypeScript repos).
Two Relay Systems (architecture clarification)
| System | Repo | Role |
|---|---|---|
did-key-relay | today internal/atproto/ingress (xrpc.fedproxy.com) | Ingress - did:key subscribers, subdomain routing; carries market XRPC and PDS traffic, no guest ssh |
atproto-relay | today internal/atproto/relay (relay.mini-cloud-0002.chadig.com) | Collection index proxy - crawls PDSes, serves subscribeRepos and listReposByCollection |
Still two distinct systems.
Quick Reference: Exact Commands to Run
Today the commands are the user pages': ../../README.md, ../quickstart-prod.md, ../quickstart-local.md, ../bidder.md, ../gateway.md. Each subsection below keeps its heading.
Prerequisites
Today: Linux with /dev/kvm for a bidder; socialweb-computer check-host -role bidder|requester names what is missing. No container runtime.
Bidder (start first, needs container runtime)
Today: install bidder (../bidder.md); no container runtime.
Requester (start after bidder)
Today: run request (../quickstart-prod.md); --policy only-me and --policy-args exist after --; the bid window is bidWindowSeconds of the requester, not a policy arg.
Desktop Bidder (macOS tray app)
No successor.
Container Management
No successor (no containers). A bidder's VMs: kubectl get computevms against its kcp (../bidder.md).
E2E Test (single process)
Today: Single-Process E2E above.
Integration Tests
Today: the Rust system tests (Test Commands).
Type Checking & Package Discovery
Today: go build ./..., deploy/check.sh --fast.
Codegraph Exploration
No successor here.
Key File Paths (relative to org root)
Today, per instance state dir: attestation.jwk (bidder), attestation-key.json and repo-key.json (requester), plc-rotation.key, the Pds repo-keys/, OpenBao; an installed bidder's state is /var/lib/socialweb-computer/swc-bidder (protocol/identity.md).
PDS (Personal Data Server)
Today the Pds component runs inside the application (localRepo); no separate PDS command.
JSR Package Registry
No successor (guest binaries come from the bidder's GuestControlPlane, see Ephemeral JSR Registry).
Market Relay (AT Protocol Firehose Relay)
Today the Go relay socialweb-computer internal atproto-relay (deployed with scripts/deploy-atproto-relay.sh); a market network runs its own Relay component.
Full Local Dev Stack (all three + dispatcher)
Today one command: Single-Process E2E (dev up --profile market-network brings up the PLC, relay, PDSes, ingress dispatcher and a bidder). Deploys: scripts/deploy.sh (gateway), scripts/deploy-xrpc-relay.sh (ingress relay), scripts/deploy-atproto-relay.sh (relay), infra/did-key-associator (qr.fedfork.com); releases reach prod through CI (../deploy.md).
Guest Tunnel Transport (did-key-ingress-proxy)
Replaced again: today the guest's ssh is iroh (SSH Tunnel Path). The did:key ingress (xrpc.fedproxy.com) still exists for market XRPC and PDS traffic, not for guests.
Files
| File | Role |
|---|---|
internal/atproto/cloudinit/modules.go | the iroh module: setup-iroh.sh, iroh-listener.sh |
internal/guestseed/userdata.go | guest-onnetwork.service, send-onnetwork.sh, accept.json |
internal/services/guestcontrolplane/, internal/guestidentity/ | POST /v1/events (was /v1/on-network) |
internal/market/bidder/report.go, syncs.go | vm.onNetwork and vm.hostKeys records |
internal/market/requester/runner.go (waitGuest), internal/stack/request/ssh.go | the requester's wait and ssh |
Flow
Guest boots (cloud-init)
-> iroh-listener.sh starts
-> dumbpipe listen-tcp 127.0.0.1:22 (the guest's own iroh node key)
-> writes iroh://<ticket> to /run/guest-iroh-ticket and /run/guest-fqdn
-> guest-login -> workload identity token
-> guest-onnetwork.service -> POST /v1/events {acceptUri, acceptCid, record: vm.onNetwork {address: iroh://<ticket>}}
Requester SSH:
ssh -o ProxyCommand='dumbpipe connect <ticket>' root@guest
-> iroh -> dumbpipe on the guest -> sshd
SSH ProxyCommand
dumbpipe connect <iroh ticket>
(webrtc: socialweb-computer run request proxy <name> --tag <tag>, used by run request ssh --transport webrtc)
onNetwork Event Flow
Guest POST -> Provider -> Bidder PDS -> Firehose -> Requester
- Guest cloud-init
guest-onnetwork.service(oneshot) waits for/run/guest-fqdnwritten byiroh-listener.sh - Reads
accept.jsonforacceptUri/acceptCid - Reads the workload token (
/root/secrets/openbao/token) - POSTs to the GuestControlPlane
POST /v1/eventswith{ acceptUri, acceptCid, record }(was/v1/on-networkwith{ address }) - The GuestControlPlane checks the bearer (the
Authorizationheader) and the accept - The bidder creates
compute.events.vm.onNetworkin its repo atEventRKeys(onNetwork:<receipt>), signed, besidevm.hostKeys - It wraps it in
market.eventwith the receipt strongRef (from the ComputeVM'sspec.contract) - It sends
market.submitEventto the receipt'ssubmitEvent; the relay and the Jetstreams carry it too - The requester reads the payload by its strongRef ->
status.contract.vmAddress(the iroh ticket) andhostKeys - Requester SSHes over iroh
acceptToContract Map
Today the ComputeVM's spec.contract {receipt, accept, submitEventUrl, acceptedAt} (ApplyComputeVMContract), a kcp object, not an in-memory map.
Ephemeral JSR Registry
No successor: guests no longer pull packages at boot. The bidder serves the guest binaries (opentunnel, wootty, atirc, socialweb-guest-agent; socialweb-computer with --guest-tools) from its GuestControlPlane at http://192.0.2.1:<port>/v1/downloads/<sha256>/<name>, and setup-guest-binaries.service checks each sha256 (flow.md).