0
0
# Bidder architecture
Host readings on 2026-10-22 from the installed bidder on this host, hat-9 and hat-7 (release binary
sha256 `30ab2e465a080bbe47ea16e085cdd99d10c640f4c90d438484363a443b31bd92`); the source claims were
rechecked against commit `1cad64b0` on 2026-10-26.
## Shape
A bidder is one installed application. It has one `socialweb-computer` core process, one kcp
logical cluster, one OpenBao server and its own PDS. It does not join a market network and it does
not run a separate application per component.
```
systemd --user (account swc-bidder, uid 947 / 988 / 964)
socialweb.slice
├─ socialweb-computer-bidder@<handle>.service core: appctl, componentcore, HostProcess supervisor
├─ socialweb-kcp-<instance>-kine@a.service kine on sqlite
├─ socialweb-kcp-<instance>-front.service L4 front for kcp
├─ socialweb-kcp-<instance>@a.service kcp API server slot a
└─ socialweb-hp-<instance>-bao-bidder.service OpenBao HostProcess
core (one process)
├─ devcore: lock, kcp slot lifecycle, bootstrap, members
├─ appctl: MarketBidder root, child objects, status, reconcile loop
├─ componentcore: Bidder, GuestControlPlane, Pds, PolicyEngine, Service/Exposure/ComponentLink
├─ hostprocess supervisor: bao-bidder and ComputeVM units
└─ PolicyEngine runner + StateSync workers
```
The installed state root is `/var/lib/socialweb-computer/swc-bidder` (or the path passed to
`install bidder`). Its kcp handle is under `handles/<hash>/kcp`; the current bidder uses
`handles/53eff7074d/`.
## kcp layout
Observed root workspaces:
| workspace | type | role | phase |
| --- | --- | --- | --- |
| `socialweb-provider` | `universal` | API schemas, exports and provider service accounts | Ready |
| `app` | `socialweb-application` | the bidder's application objects and components | Ready |
The `root` workspace also holds the kcp bootstrap objects and the `MarketBidder` root. Namespaces in
the root and `app` workspaces are `default` and `kcp-system` (the latter from kcp itself).
The `socialweb-application` type binds `applications`, `policy`, `computevms`, `hostprocesses`,
`clusters`, `atprotoidentities`, `marketidentities`, `computecontracts`, `exposures`, `pds` and
`events`. The bidder set additionally installs the `computevms` schema/export and the root binding,
because the bidder owns ComputeVM objects.
Observed root objects on this host:
| kind/name | phase | note |
| --- | --- | --- |
| `MarketBidder/app` | Ready | profile `prod-qr`, DID `did:plc:vxd7pmlhw6bnpyu6wngewthn` |
| `MarketIdentity/bidder` | Ready | localRepo, association `RequireApproval`, approved operator DID |
| `OpenBaoServer/bidder` | Ready | `https://127.0.0.1:45457`, one node, initialized and unsealed |
| `Pds/pds` | Ready | app-owned PDS, endpoint `http://pds.pds` |
| `Bidder/bidder` | Ready | market loop and guest launch |
| `GuestControlPlane/guest-kcp` | Ready | relay, OIDC, sshsig, on-network and host keys |
| `PolicyEngine/policy-engine` | Running | in-process policy engine |
| `AtprotoRecord/association` | Pending | association record declaration |
| `AtprotoRecordWatch/association` | — | watches the operator repo |
| `EventStream/watch-association` | Running | feeds the watch |
| `HostProcess/bao-bidder` | Running | OpenBao |
| `HostProcess/bootstrap-kcp-a`, `bootstrap-kine-a`, `bootstrap-front` | Running | kcp bootstrap units |
Every component has a `Service` and an `Exposure`:
| Service | target | Exposure |
| --- | --- | --- |
| `svc-bidder-bidder` | `Bidder/bidder` | ingress `bobvmbuilder.bsky.social` through `IngressProxy/ingress` |
| `svc-guestcontrolplane-guest-kcp` | `GuestControlPlane/guest-kcp` | ingress through `IngressProxy/ingress` |
| `svc-pds-pds` | `Pds/pds` | local `http://127.0.0.1:20000`; ingress through `IngressProxy/ingress` |
Application components do not bind their own public sockets. The component runtime registers
handlers in-process; the local Exposure controller leases a loopback port from the port registry
(`pds` is 20000 here). The `prod-qr` and `market-network` profiles default `spec.ingress` to
`xrpc-subscription` with `ingressProxyHost: xrpc.fedproxy.com` and `IngressProxy/ingress`; the PDS
ingress Exposure is fail-closed until that provider is Ready. A bidder joined to a market network
inherits `MarketNetworkValue.ingress` and its `dispatcher` instead.
## Identity and association
`install bidder` creates the PDS account and writes the DID into `MarketIdentity/bidder`, the
session into the bidder's OpenBao at `bidder/data/identity/bidder/pds-session`, and the PDS repo key
at `bidder/data/identity/bidder/keys`. The bidder's own repo is the PDS, not the operator's repo.
Association is the ident.link pair + grant
([docs/design/ident-link-associations.md](docs/design/ident-link-associations.md)): the bidder adds
`https://ident.link/agent-of/<operator DID>` to its DID's `alsoKnownAs` (its PDS `plc-rotation.key`;
a borrowed `at://<operator handle>` entry is dropped), and the operator's repo holds, at rkey = the
bidder DID:
```json
{"$type": "com.publicdomainrelay.temp.market.association", "agent": "did:plc:<bidder>", "createdAt": "2026-11-11T00:00:00Z"}
{"$type": "link.ident.endorsement", "agent": "did:plc:<bidder>"}
```
The bidder writes both (grant first) when it holds the operator's session (`operator-signin`, or a
market network's operator account); otherwise `scripts/associate-bidder.ts --agent-did <bidder DID>`
writes them from a mode-0600 credentials file without printing the handle or password. The identity
controller walks the bidder DID (`internal/identlink`, records by `com.atproto.sync.getRecord`) and
writes the roots into `status.associations`, setting `Associated=True` with reason `Associated`.
Deleting the bidder removes its agent-of entry. With `spec.association: Skip` it sets
`Associated=True` and reason `AssociationSkipped`. A manual patch of `spec.approvedAssociations` is a
declarative workaround, not the accepted path:
```bash
sudo kubectl --kubeconfig "$K" patch marketidentity bidder --type=merge \
-p "{\"spec\":{\"approvedAssociations\":[\"$OPERATOR_DID\"]}}"
```
## Live bidder instances
| host | state root | uid | bidder DID | association | mode |
| --- | --- | --- | --- | --- | --- |
| this host | `/var/lib/socialweb-computer/swc-bidder` | 947 | `did:plc:vxd7pmlhw6bnpyu6wngewthn` | `Associated`, operator `did:plc:ocnuqjlzgohypj3zoznermms` | `RequireApproval` |
| hat-9 | `/var/lib/socialweb-computer/swc-bidder` | 988 | `did:plc:cjuftobfmmmdkmblcl4h54eb` | `Associated`, same operator | `RequireApproval` |
| hat-7 | `/var/lib/socialweb-computer/swc-bidder` | 964 | `did:plc:exjutifioeu2p7oorbdrex2o` | `AssociationSkipped` | `Skip` |
All three run the release binary at
`bin/30ab2e465a080bbe47ea16e085cdd99d10c640f4c90d438484363a443b31bd92` and report
`MarketBidder/app` Ready. Each has its own PDS, OpenBao, DID and host guest image
`bddc484c610e956fb7e198281cf4a19dc8c95fc441c0575f49d2a33de0c74021`.
Association-record state (old `badgeBlueKeys/association` mirrors, superseded by the ident.link cut-over and deleted):
- this host: `at://did:plc:vxd7pmlhw6bnpyu6wngewthn/com.publicdomainrelay.temp.badgeBlueKeys/association`,
cid `bafyreiapgmzf3cgdmpxefzonba52xk5lo6kojkd2eijyiq2yg6jtmirjpm`
- hat-9: `at://did:plc:cjuftobfmmmdkmblcl4h54eb/com.publicdomainrelay.temp.badgeBlueKeys/association`,
cid `bafyreiebup7ijio2u73l2sgz4bfpginggbqdjxiqxfspjg5tzcw2da5czm`
## Install, upgrade, delete
`install bidder` is an account install. It creates the `swc-bidder` account, subordinate ID
ranges, state dir, binary slot, config, guest image, systemd user units, linger and kcp bootstrap.
`upgrade --binary --sha256` switches `bin/current`, restarts the core and keeps `bin/previous`.
`install bidder` again reconciles the unit files and host contract. `uninstall bidder --purge`
stops the app units, removes the state dir (including the PDS repo and OpenBao) and deletes the
account; `--force` is only for live VM units.
The `prod-qr` profile uses a local repo and an app-owned PDS. A fresh install therefore creates a
new DID and needs the one association claim; an upgrade keeps the state, DID, repo and association.
## Known gaps
- Ingress Exposures are Pending on a standalone bidder with no `IngressProxy`.
- `AtprotoRecordWatch/association` can report `invalid repo op` while the PDS stream is consumed;
the association state above does not depend on that watch.
## Inspect
```bash
K=$(sudo sh -c 'ls /var/lib/socialweb-computer/swc-bidder/handles/*/kcp/admin.kubeconfig' | head -1)
sudo kubectl --kubeconfig "$K" get workspaces,marketbidder,marketidentity,openbaoserver
sudo kubectl --kubeconfig "$K" get bidder,guestcontrolplane,pds,policyengine,service,exposure -o wide
sudo kubectl --kubeconfig "$K" get hostprocess,atprotorecord,atprotorecordwatch,eventstream -o wide
sudo kubectl --kubeconfig "$K" get marketidentity bidder -o jsonpath='{.spec}{"\n"}{.status}{"\n"}'
```
The kcp kubeconfig is readable only by root on an installed host; the core's health and unit state
are under `systemctl --user` for the `swc-bidder` account.