lexicons and xrpc
- controlPlaneDown
- controlPlaneUp
- createCluster
- deleteCluster
- getKubeconfig
- listClusters
- listKubeconfigs
- revokeIdentity
- revokeKubeconfig
- subscribeClusters
- agentStart
- image
- memoryPressure
- oomKill
- publicKey
- r2Release
- r2Released
- r2Start
- requesterDid
- secrets
- secretsApplied
- secretsRequested
- secretsUpdated
- signalWebRTC
lexicon
computer.socialweb.infra
A long-lived deployment: a set of compute contracts, each declared with the state its author wants. Any client of the account may change the declaration; the socialweb-computer requester that runs the deployment writes the status. When the deployment ends its record is kept with status.endedAt.
definitions: #contract #image #tunnel #shell #agent #association #status #index #indexEntry #indexEnded #contractStatus
record
| field | type | description |
|---|---|---|
description | string | maxLength 1024 |
contracts | array of #contract | The declared contracts. Names are unique within the record. maxLength 64 |
status | #status | |
index | #index | Only at rkey self: the account's index of live deployments. A record with index is not a deployment. |
createdAt * | string datetime |
#contract object
| field | type | description |
|---|---|---|
name * | string | A DNS-1123 label, unique within the deployment. maxLength 63 |
state * | string | staged: declared, no RFP is sent. requested: the requester runs the RFP flow and holds the guest. released: the guest is released. knownValues ["staged","requested","released"] |
releaseRequestedAt | string datetime | With state released: the time of the newest release request; a newer one asks a failed release again. |
vmName | string | maxLength 253 |
bidderDids | array of string did | items.format did |
denyBidderDids | array of string did | items.format did |
sshAuthorizedKeys | array of string | |
userData | string | cloud-init user_data; never a secret, it is public here. maxLength 65536 |
computeKind | string | What the bidder runs: a firecracker virtual machine (the default when absent), or a deno sandbox that runs spec.userData as its program. knownValues ["vm","deno"] |
net | boolean | computeKind deno: the program reaches the public internet; a bidder runs it only for its owner. |
policy | string | |
policyArgs | string | |
vmReadyTimeoutSec | integer | minimum 0 |
cpus | integer | vCPUs of the VM (unset: the requester's default, 2). minimum 0 |
mem | string | Memory of the VM, such as 8G (unset: the requester's default, 4G). |
nestedVirt | boolean | The VM must run VMs of its own; only a bidder whose offering sets nestedVirt is asked. |
image | #image | |
tunnels | array of #tunnel | Guest ports the requester reaches over a tunnel transport. Tags are unique within the contract. |
agent | #agent | |
association | #association | |
guestTools | array of string | Tools the bidder installs on the guest from its own downloads. socialweb-computer is the bidder's own running binary, linux/amd64 bidders only, installed as /usr/local/bin/socialweb-computer. items.knownValues ["socialweb-computer"] |
#image object
| field | type | description |
|---|---|---|
url * | string uri | An https base URL of a directory holding image.json, the kernel and the rootfs it names. maxLength 2048 |
sha256 * | string | The hex sha256 of that image.json. minLength 64 maxLength 64 |
#tunnel object
| field | type | description |
|---|---|---|
tag * | string | A DNS-1123 label naming the tunnel. maxLength 32 |
port * | integer | The guest port, on 127.0.0.1. minimum 1 maximum 65535 |
server | string uri | The opentunnel server; absent means the requester's default. |
shell | #shell | |
transport | string | opentunnel (the default) gives an https URL; webrtc gives a datachannel to the guest agent. knownValues ["opentunnel","webrtc"] |
#shell object
A web shell served on the tunnel's port; its token arrives through the contract's secrets bundle, never here.
| field | type | description |
|---|---|---|
envFile | string | The guest path of the shell's env file; absent means /etc/wootty/wootty.env. maxLength 256 |
#agent object
An atirc agent on the guest, started on demand; its token arrives through the contract's secrets bundle, never here.
| field | type | description |
|---|---|---|
envFile | string | The guest path of the agent's env file; absent means /etc/atirc/atirc.env. maxLength 256 |
#association object
A requester the guest runs: after the accept the requester writes a contract-scoped com.publicdomainrelay.temp.market.association naming subject and puts its at-uri#cid into the secrets bundle at refFile.
| field | type | description |
|---|---|---|
subject | string did | The repo DID of the requester the guest runs, when it is known before the RFP. |
fromGuest | boolean | The subject is the DID the guest reports in a compute.events.guest.requesterDid event; set instead of subject. |
refFile | string | The guest path of the ref file, under /etc/socialweb-computer/; absent means /etc/socialweb-computer/association-ref. maxLength 256 |
#status object
| field | type | description |
|---|---|---|
phase * | string | knownValues ["pending","staged","deploying","deployed","releasing","released","degraded","ending","deleting","ended"] |
contracts | array of #contractStatus | |
endedAt | string datetime | Set once, when the deployment ends; the record is kept and an ended record is never live again. |
endReason | string | knownValues ["deleted"] |
#index object
| field | type | description |
|---|---|---|
live | array of #indexEntry | Absent means no live deployment. maxLength 256 |
recentEnded | array of #indexEnded | Newest first; the oldest drops off. The records themselves are kept. maxLength 32 |
updatedAt * | string datetime |
#indexEntry object
| field | type | description |
|---|---|---|
collection * | string nsid | knownValues ["computer.socialweb.infra","computer.socialweb.ephemeralInfra"] |
rkey * | string record-key | |
createdAt * | string datetime | |
expiresAt | string datetime | EphemeralInfra only: createdAt plus ttlSeconds. |
addedAt * | string datetime | |
writer | string | A public label of the kcp that runs it: page:<origin host>, ios, gateway:<host>, cli. maxLength 64 |
#indexEnded object
| field | type | description |
|---|---|---|
collection * | string nsid | |
rkey * | string record-key | |
endedAt * | string datetime | |
endReason | string |
#contractStatus object
| field | type | description |
|---|---|---|
name * | string | |
phase * | string | knownValues ["staged","requesting","deployed","releasing","released","failed"] |
winner | string did | |
receipt | string at-uri | |
message | string | maxLength 1024 |
used in
flow: one compute contract, end to end, protocol: the atproto protocol of socialweb-computer
raw schema: lexicons/computer/socialweb/infra.json
{
"lexicon": 1,
"id": "computer.socialweb.infra",
"description": "A long-lived deployment: a set of compute contracts, each declared with the state its author wants. Any client of the account may change the declaration; the socialweb-computer requester that runs the deployment writes the status. When the deployment ends its record is kept with status.endedAt.",
"defs": {
"main": {
"type": "record",
"key": "any",
"record": {
"type": "object",
"required": [
"createdAt"
],
"properties": {
"description": {
"type": "string",
"maxLength": 1024
},
"contracts": {
"type": "array",
"maxLength": 64,
"items": {
"type": "ref",
"ref": "#contract"
},
"description": "The declared contracts. Names are unique within the record."
},
"status": {
"type": "ref",
"ref": "#status"
},
"index": {
"type": "ref",
"ref": "#index",
"description": "Only at rkey self: the account's index of live deployments. A record with index is not a deployment."
},
"createdAt": {
"type": "string",
"format": "datetime"
}
}
}
},
"contract": {
"type": "object",
"required": [
"name",
"state"
],
"properties": {
"name": {
"type": "string",
"maxLength": 63,
"description": "A DNS-1123 label, unique within the deployment."
},
"state": {
"type": "string",
"knownValues": [
"staged",
"requested",
"released"
],
"description": "staged: declared, no RFP is sent. requested: the requester runs the RFP flow and holds the guest. released: the guest is released."
},
"releaseRequestedAt": {
"type": "string",
"format": "datetime",
"description": "With state released: the time of the newest release request; a newer one asks a failed release again."
},
"vmName": {
"type": "string",
"maxLength": 253
},
"bidderDids": {
"type": "array",
"items": {
"type": "string",
"format": "did"
}
},
"denyBidderDids": {
"type": "array",
"items": {
"type": "string",
"format": "did"
}
},
"sshAuthorizedKeys": {
"type": "array",
"items": {
"type": "string"
}
},
"userData": {
"type": "string",
"maxLength": 65536,
"description": "cloud-init user_data; never a secret, it is public here."
},
"computeKind": {
"type": "string",
"knownValues": [
"vm",
"deno"
],
"description": "What the bidder runs: a firecracker virtual machine (the default when absent), or a deno sandbox that runs spec.userData as its program."
},
"net": {
"type": "boolean",
"description": "computeKind deno: the program reaches the public internet; a bidder runs it only for its owner."
},
"policy": {
"type": "string"
},
"policyArgs": {
"type": "string"
},
"vmReadyTimeoutSec": {
"type": "integer",
"minimum": 0
},
"cpus": {
"type": "integer",
"minimum": 0,
"description": "vCPUs of the VM (unset: the requester's default, 2)."
},
"mem": {
"type": "string",
"description": "Memory of the VM, such as 8G (unset: the requester's default, 4G)."
},
"nestedVirt": {
"type": "boolean",
"description": "The VM must run VMs of its own; only a bidder whose offering sets nestedVirt is asked."
},
"image": {
"type": "ref",
"ref": "#image"
},
"tunnels": {
"type": "array",
"items": {
"type": "ref",
"ref": "#tunnel"
},
"description": "Guest ports the requester reaches over a tunnel transport. Tags are unique within the contract."
},
"agent": {
"type": "ref",
"ref": "#agent"
},
"association": {
"type": "ref",
"ref": "#association"
},
"guestTools": {
"type": "array",
"items": {
"type": "string",
"knownValues": [
"socialweb-computer"
]
},
"description": "Tools the bidder installs on the guest from its own downloads. socialweb-computer is the bidder's own running binary, linux/amd64 bidders only, installed as /usr/local/bin/socialweb-computer."
}
}
},
"image": {
"type": "object",
"required": [
"url",
"sha256"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "An https base URL of a directory holding image.json, the kernel and the rootfs it names."
},
"sha256": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "The hex sha256 of that image.json."
}
}
},
"tunnel": {
"type": "object",
"required": [
"tag",
"port"
],
"properties": {
"tag": {
"type": "string",
"maxLength": 32,
"description": "A DNS-1123 label naming the tunnel."
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535,
"description": "The guest port, on 127.0.0.1."
},
"server": {
"type": "string",
"format": "uri",
"description": "The opentunnel server; absent means the requester's default."
},
"shell": {
"type": "ref",
"ref": "#shell"
},
"transport": {
"type": "string",
"knownValues": [
"opentunnel",
"webrtc"
],
"description": "opentunnel (the default) gives an https URL; webrtc gives a datachannel to the guest agent."
}
}
},
"shell": {
"type": "object",
"description": "A web shell served on the tunnel's port; its token arrives through the contract's secrets bundle, never here.",
"properties": {
"envFile": {
"type": "string",
"maxLength": 256,
"description": "The guest path of the shell's env file; absent means /etc/wootty/wootty.env."
}
}
},
"agent": {
"type": "object",
"description": "An atirc agent on the guest, started on demand; its token arrives through the contract's secrets bundle, never here.",
"properties": {
"envFile": {
"type": "string",
"maxLength": 256,
"description": "The guest path of the agent's env file; absent means /etc/atirc/atirc.env."
}
}
},
"association": {
"type": "object",
"description": "A requester the guest runs: after the accept the requester writes a contract-scoped com.publicdomainrelay.temp.market.association naming subject and puts its at-uri#cid into the secrets bundle at refFile.",
"properties": {
"subject": {
"type": "string",
"format": "did",
"description": "The repo DID of the requester the guest runs, when it is known before the RFP."
},
"fromGuest": {
"type": "boolean",
"description": "The subject is the DID the guest reports in a compute.events.guest.requesterDid event; set instead of subject."
},
"refFile": {
"type": "string",
"maxLength": 256,
"description": "The guest path of the ref file, under /etc/socialweb-computer/; absent means /etc/socialweb-computer/association-ref."
}
}
},
"status": {
"type": "object",
"required": [
"phase"
],
"properties": {
"phase": {
"type": "string",
"knownValues": [
"pending",
"staged",
"deploying",
"deployed",
"releasing",
"released",
"degraded",
"ending",
"deleting",
"ended"
]
},
"contracts": {
"type": "array",
"items": {
"type": "ref",
"ref": "#contractStatus"
}
},
"endedAt": {
"type": "string",
"format": "datetime",
"description": "Set once, when the deployment ends; the record is kept and an ended record is never live again."
},
"endReason": {
"type": "string",
"knownValues": [
"deleted"
]
}
}
},
"index": {
"type": "object",
"required": [
"updatedAt"
],
"properties": {
"live": {
"type": "array",
"maxLength": 256,
"items": {
"type": "ref",
"ref": "#indexEntry"
},
"description": "Absent means no live deployment."
},
"recentEnded": {
"type": "array",
"maxLength": 32,
"items": {
"type": "ref",
"ref": "#indexEnded"
},
"description": "Newest first; the oldest drops off. The records themselves are kept."
},
"updatedAt": {
"type": "string",
"format": "datetime"
}
}
},
"indexEntry": {
"type": "object",
"required": [
"collection",
"rkey",
"createdAt",
"addedAt"
],
"properties": {
"collection": {
"type": "string",
"format": "nsid",
"knownValues": [
"computer.socialweb.infra",
"computer.socialweb.ephemeralInfra"
]
},
"rkey": {
"type": "string",
"format": "record-key"
},
"createdAt": {
"type": "string",
"format": "datetime"
},
"expiresAt": {
"type": "string",
"format": "datetime",
"description": "EphemeralInfra only: createdAt plus ttlSeconds."
},
"addedAt": {
"type": "string",
"format": "datetime"
},
"writer": {
"type": "string",
"maxLength": 64,
"description": "A public label of the kcp that runs it: page:<origin host>, ios, gateway:<host>, cli."
}
}
},
"indexEnded": {
"type": "object",
"required": [
"collection",
"rkey",
"endedAt"
],
"properties": {
"collection": {
"type": "string",
"format": "nsid"
},
"rkey": {
"type": "string",
"format": "record-key"
},
"endedAt": {
"type": "string",
"format": "datetime"
},
"endReason": {
"type": "string"
}
}
},
"contractStatus": {
"type": "object",
"required": [
"name",
"phase"
],
"properties": {
"name": {
"type": "string"
},
"phase": {
"type": "string",
"knownValues": [
"staged",
"requesting",
"deployed",
"releasing",
"released",
"failed"
]
},
"winner": {
"type": "string",
"format": "did"
},
"receipt": {
"type": "string",
"format": "at-uri"
},
"message": {
"type": "string",
"maxLength": 1024
}
}
}
}
}