Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

Types

View Markdown
FieldTypeWhat it is
idstring
namestring
prefixstringFirst 8 chars for identification
scopeslist of string
createdAtTimestamp
expiresAtTimestamp
lastUsedAtTimestamp
parentIdstringThe key it was delegated from, and how far down the chain (0: made by its person).
depthinteger (int32)
teamIdstringThe one team it reaches; empty for every team its person is in. Of that team, the projects it reaches; empty for any.
projectIdslist of string
maxWorkspacesinteger or null (int32)How many of the workspaces its tree made - this key and every key delegated from it - may be on a runner at once, and how many cores those may hold: bounds on what runs, unset for none past its person’s. A workspace counts while it is being made or started, runs, is stopping or waits for a runner. One that is stopped, suspended or in the trash counts for nothing, whatever disk it keeps, and is counted again when it is started: a start past the bound is refused as a create is, naming the workspaces that hold it.
maxCoresinteger or null (int32)
FieldTypeWhat it is
idstring
namestring
stateWorkspaceState

AgentThread is one of the agent’s threads as T3 Code names it: what a person is shown of a chat without opening it.

FieldTypeWhat it is
idstring
titlestring
projectstringproject is the directory the thread works in.
modelstring
updatedAtTimestamp
archivedboolean

AgentVolume is one agent home of the caller’s.

FieldTypeWhat it is
idstring
sizeBytesstring (int64)
createdAtTimestamp
workspaceIdstringThe workspace mounting it, or empty for one no workspace mounts - which a new workspace may.
workspaceNamestringThe name of the workspace that mounts it, or mounted it last.

Alert is one firing or one resolution of an alert rule, as Grafana sent it.

FieldTypeWhat it is
idstringThe installation event’s id.
eventInstallationEventType
namestringThe rule’s title (Grafana’s alertname).
summarystringThe rule’s summary, rendered for what fired; empty where it has none.
descriptionstring
severitystringcritical, warning; empty where the rule says none.
runbookUrlstringWhere the dashboard’s runbook for it is, as the rule names it: /admin/runbooks/<id>.
labelsmap of string to stringWhat else the alert’s series is labelled with: which host, which volume.
startsAtTimestampWhen it began firing, and for a resolution when it stopped.
endsAtTimestamp
createdAtTimestampWhen the control plane heard it.
sentinteger (int32)How many administrators it was emailed to, is waiting for, and failed every attempt for.
pendinginteger (int32)
failedinteger (int32)

Allowed email/domain entry

FieldTypeWhat it is
idstring
patternstringEmail address or domain
typeAllowedEmailType
descriptionstringOptional description
createdAtTimestamp

Allowed email type enum - ALLOWED_EMAIL_TYPE_EMAIL: Exact email address match - ALLOWED_EMAIL_TYPE_DOMAIN: Domain suffix match (@domain.com)

One of: ALLOWED_EMAIL_TYPE_UNSPECIFIED, ALLOWED_EMAIL_TYPE_EMAIL, ALLOWED_EMAIL_TYPE_DOMAIN.

AuditEntry is one recorded operation, as it was recorded: the log is append-only and nothing here is derived at read time except the actor’s email, which is joined so a reader is not handed a UUID to look up by hand.

FieldTypeWhat it is
idstring
actorIdstringactor_id is empty for an operation nobody was signed in for - a failed login, a runner registering itself - and for one whose user has since been deleted.
actorEmailstringactor_email is empty for the same reasons, and is what the user’s row says now rather than what it said then.
actionstring
resourceTypestring
resourceIdstringresource_id is empty for an operation with no row to point at - a failed login, a change to the installation’s settings. resource_type still says what kind of thing it was about.
detailsstringdetails is the JSON the operation recorded, verbatim. It has no schema: what a login records and what a team membership change records have nothing in common, and a reader that insists on a shape would have to be changed by every new action.
ipAddressstring
createdAtTimestamp

BaseImage is the base image of one machine release, as published.

FieldTypeWhat it is
refstring
versionstringThe machine release it was taken from.
publishedAtTimestamp
clonesstring (int64)How many volumes were cloned from it: every workspace disk that began as it, and still is.
untaggedbooleanIts ref was taken off it: no new workspace gets it, the disks cloned from it go on reading it.
givenbooleanWhat a workspace that names no image is given now.
pinnedbooleanThe one this control plane’s release pins; given once it is published.
volumeIdstringIts volume in the store, which RemoveStoredVolume takes when removable.
removablebooleanNo disk was cloned from it and it is not the one given: RemoveStoredVolume untags it on the way and removes it.
keptBecausestringWhy it stays, in words, where it may not go.
FieldTypeWhat it is
dayTimestampThe day’s first instant, UTC.
serviceslist of ServiceCostCostliest first.

BrokeredRequest is one request the egress proxy read from the workspace’s machine to a brokered name. No header and no body: what the proxy set is the team’s secret, and what the machine sent is its own.

FieldTypeWhat it is
namestring
methodstring
pathstringAs the machine sent it, without the query.
statusinteger (int32)What the real host answered; what the proxy answered for a refusal.
bytesSentstring (int64)
bytesReceivedstring (int64)
atTimestamp
refusedstringEmpty for a request passed on. Otherwise why the proxy refused it: credentials (a secret or token the team does not hold), host (a request for another name), upgrade, method (TRACE or TRACK), scope (a method or path the injecting rule does not allow), authority (the cloud principal refused to sign it).
principalstringWho asked: “user” or “agent”, by the listener the proxy read it on.

BurstMode is how a workspace of a preset may grow past what it starts with. - BURST_MODE_FIXED: FIXED starts at the preset’s size and stays there. - BURST_MODE_TO_PRESET: TO_PRESET starts at the preset’s burst floor and may grow to its size. - BURST_MODE_TO_HOST: TO_HOST starts at the preset’s burst floor and may grow to everything its host has.

One of: BURST_MODE_UNSPECIFIED, BURST_MODE_FIXED, BURST_MODE_TO_PRESET, BURST_MODE_TO_HOST.

CloudAccess is a principal on a cloud a brokered rule’s requests are authorized as.

FieldTypeWhat it is
cloudstringThe cloud: “aws”, whose principal is an IAM role’s ARN and whose requests are signed with SigV4.
principalstring

One thing the config file says differently from the installation.

FieldTypeWhat it is
kindConfigItemKind
namestring
fileSaysstringWhat the file says, as a person reads it; empty where the file no longer declares the item, and applying the change removes it.
installationHasstringWhat the installation has, the same way; empty where it has none.
saysstringThe file’s declaration this change is about, sent back as it came: a decision about one the file has changed since is refused rather than taken as about the newer one.
sinceTimestampWhen the file started saying it.

What one item of the installation’s config file is. - CONFIG_ITEM_KIND_SETTING: A setting, by its key: registration_mode, default_network_tags, allowed_images… - CONFIG_ITEM_KIND_EMAIL: An address or domain registration admits, by itself. - CONFIG_ITEM_KIND_HOST_CLASS: A host class, by its name: the shape of a group of runners (HostClass).

One of: CONFIG_ITEM_KIND_UNSPECIFIED, CONFIG_ITEM_KIND_SETTING, CONFIG_ITEM_KIND_EMAIL, CONFIG_ITEM_KIND_PRESET, CONFIG_ITEM_KIND_POLICY, CONFIG_ITEM_KIND_HOST_CLASS.

What a workspace would cost at what the last billed day charged. An estimate: that day is over and the next may be charged otherwise, so it is never said without the day it is from.

FieldTypeWhat it is
dayTimestampThe billed day the rate is from: its first instant, UTC.
runningHourMicrosstring or null (int64)An hour of its machine running, for the cores and memory it holds; unset where that day billed no runner.
stoppedMonthMicrosstring or null (int64)A month of its disk kept while it is stopped, for the bytes it kept that day; unset where that day billed no volume, or the workspace was made since.

One month of the trend on Admin → Costs, in millionths of the bill’s currency. An estimate of what nobody caused, from the reading it names: a month’s last days are revised by the cloud into the next, and read again until they settle.

FieldTypeWhat it is
monthTimestampIts first instant, UTC.
readAtTimestampThe reading its costs are from.
currencystringISO 4217.
totalMicrosstring (int64)Every cost of its days; idle and unstored are parts of it.
idleMicrosstring (int64)What the runners cost that no workspace held.
unstoredMicrosstring (int64)What the volumes’ bucket cost for bytes no workspace keeps.
budgetLimitMicrosstring or null (int64)The installation’s budget as the month’s last reading in it said; unset where it had none.

What was caused in a month of the cloud’s bill, as the installation shares it out (AdminService.GetCosts): by one workspace, or by several summed. In millionths of the bill’s currency. A share is of days already billed, never of this hour: the bill is read from the cloud a few times a day.

FieldTypeWhat it is
computeMicrosstring (int64)Of the runners: what was held of them.
storageMicrosstring (int64)Of the volumes’ bucket: what the volumes kept.
sentBytesstring (int64)What the traffic came to in the month: the machine’s network out and back, and its sessions through the relay, both ways. Counted, not costed.
receivedBytesstring (int64)
forwardedBytesstring (int64)

CpuUsagePoint is the cores the machine used over a step, on average, against what it held: held_cores attached, lent ones included; cpu_cores its own; max_cpu_cores what it may be lent.

FieldTypeWhat it is
startTimestamp
usedCoresnumber (double)
heldCoresinteger (int32)
cpuCoresinteger (int32)
maxCpuCoresinteger (int32)

DeletedWorkspace is a workspace in the trash.

FieldTypeWhat it is
idstring
namestringThe name it had; another workspace may have taken it since, and an undelete then gives it another.
deletedAtTimestamp
trashedUntilTimestamp
agentVolumeIdstringThe agent’s home it mounts, which its erase keeps for another workspace (ListAgentVolumes); empty for a workspace with none.

DeletionEffect is one thing a workspace has and what a delete does to it, in words its owner reads before confirming.

FieldTypeWhat it is
fateDeletionFate
whatstringWhat it is: “Its disk”, “2 snapshots”.
detailstringWhat happens to it and what follows from that, one sentence.

DeletionFate is what a delete does to one thing a workspace has. - DELETION_FATE_ERASED: Gone when the delete is done, and not undeleted. - DELETION_FATE_TRASHED: In the trash for GetWorkspaceDeletionResponse.trash_days, restored by an undelete, erased when they are up. - DELETION_FATE_KEPT: Outlives the workspace, the trash’s days included.

One of: DELETION_FATE_UNSPECIFIED, DELETION_FATE_ERASED, DELETION_FATE_TRASHED, DELETION_FATE_KEPT.

DepartureFate is what taking a host out does to one workspace on it. - DEPARTURE_FATE_MOVES: Suspended with its memory and resumed on another runner with room. - DEPARTURE_FATE_STAYS: Keeps its place on this runner: a drain moves only what runs. - DEPARTURE_FATE_LOSES_PLACE: Suspended at a published snapshot: its disk is let go of here, and its next start is on another runner, from what it published. - DEPARTURE_FATE_HOLDS: It keeps the host: the removal is refused while it is here. A group’s machine is held by a disk only here, until it is stopped, which publishes it, or moved; a revoked host by any workspace that names it. - DEPARTURE_FATE_STOPS: Its disk is only here and is left here: it runs again only once recovered onto another runner, giving up what this one had not published.

One of: DEPARTURE_FATE_UNSPECIFIED, DEPARTURE_FATE_MOVES, DEPARTURE_FATE_STAYS, DEPARTURE_FATE_LOSES_PLACE, DEPARTURE_FATE_HOLDS, DEPARTURE_FATE_STOPS.

  • DEVICE_LOGIN_STATUS_PENDING: User hasn’t completed login yet - DEVICE_LOGIN_STATUS_COMPLETE: Login complete, token available - DEVICE_LOGIN_STATUS_EXPIRED: Device code expired - DEVICE_LOGIN_STATUS_DENIED: User denied the request

One of: DEVICE_LOGIN_STATUS_UNSPECIFIED, DEVICE_LOGIN_STATUS_PENDING, DEVICE_LOGIN_STATUS_COMPLETE, DEVICE_LOGIN_STATUS_EXPIRED, DEVICE_LOGIN_STATUS_DENIED.

FieldTypeWhat it is
repostringGit URL: https://github.com/user/dotfiles
branchstringBranch to clone (default: main)
installCommandstringCommand to run after clone (default: ./install.sh)

EmailSettings is the SMTP server the installation sends its notifications through. No host is email off: what would have been sent is still recorded, and shown on each person’s page.

FieldTypeWhat it is
hoststring
portinteger (int32)465 is TLS from the first byte; any other port is upgraded with STARTTLS where the server offers it, and a username is refused over a connection that is not encrypted.
usernamestring
passwordSetboolean
fromstringThe address mail is sent from, as the server allows this account to send.
FieldTypeWhat it is
idstring
workspaceIdstring
portinteger (int32)
httpsBackendbooleanThe proxy speaks TLS to this port without verifying its certificate, and only under the {port}s- hostname: 3000-ws and 3000s-ws are different names, and one refuses.
descriptionstring
createdAtTimestamp
urlstringOutput only: computed URL (e.g., https://3000-dev.ws.spinbox.dev)
accessPortAccess
grantslist of PortGrantWho this port is granted to, when access is WHITELIST. Output only, and populated only for the workspace’s owner - who a port is shared with is the owner’s business and not the grantees’.

ExtensionRelease is one release of an extension: the supervisor, or the VS Code servers.

FieldTypeWhat it is
versionstringThe release’s own name: the control plane’s version for the supervisor; for the VS Code servers, the versions it carries joined with +, unless it was named otherwise.
releasedAtTimestamp
newestbooleanWhether a start is given this one.
volumeIdstringIts volume in the store, which RemoveStoredVolume takes when removable.
removablebooleanNot the newest, and open in no machine and no suspended memory: RemoveStoredVolume removes it, and so does the collect-releases job on its own. A release only stopped workspaces last ran is removable, since their next start is given the newest.
keptBecausestringWhy it stays, in words, where it may not go: how many machines and suspended memories have it open, or that it is the newest.

ExtensionVersion is a release and how many workspaces are on it: what an update leaves behind until each workspace is next started.

FieldTypeWhat it is
extensionstring
versionstring
workspacesstring (int64)The machines that have it open and the suspended memories that do: a stopped workspace is given the newest at its next start, and is on none.
newestbooleanWhether a start now would choose this release.

FieldValue is one value a field has, and how many of a search’s records have it.

FieldTypeWhat it is
valuestring
countstring (int64)
FieldTypeWhat it is
pathstringFrom the filesystem’s root, with a leading slash. A name holding bytes that are not UTF-8 has them replaced here, and path_bytes holds the name as it is.
pathBytesstring (byte)
kindFileChangeKind
fromFileStateUnset on the side the path is not on.
toFileState
  • FILE_CHANGE_KIND_MODIFIED: The same type on both sides, and a different content, mode, owner or symlink target.

One of: FILE_CHANGE_KIND_UNSPECIFIED, FILE_CHANGE_KIND_ADDED, FILE_CHANGE_KIND_REMOVED, FILE_CHANGE_KIND_MODIFIED, FILE_CHANGE_KIND_TYPE_CHANGED.

FieldTypeWhat it is
typeFileType
modeintegerPermission bits, setuid, setgid and sticky included.
uidinteger
gidinteger
sizestring (int64)
symlinkTargetstringA symlink’s target as stored, never followed; replaced and in symlink_target_bytes as path is.
symlinkTargetBytesstring (byte)
sha256stringA regular file’s content hash in lowercase hex, where its content is what changed.
modifiedAtTimestamp
  • FILE_TYPE_OTHER: A device, a FIFO or a socket.

One of: FILE_TYPE_UNSPECIFIED, FILE_TYPE_REGULAR, FILE_TYPE_DIRECTORY, FILE_TYPE_SYMLINK, FILE_TYPE_OTHER.

One host class’s group, as the control plane last saw it.

FieldTypeWhat it is
classHostClass
desiredinteger (int32)What it last asked the group for, and the most it may ask now - the class’s own limit, or what the installation’s leaves it: zero of one is a group at rest.
mostinteger (int32)
waitinginteger (int32)Workspaces of the class that have nowhere to run yet, and when the first of them started waiting: this is what makes the control plane ask for a machine.
oldestWaitingTimestamp
busyinteger (int32)Workspaces of the class, and hosts a root shell holds, keeping its group up.
launchFailurestringWhy the group has fewer machines running than it was asked for, in its cloud’s own words - “AWS could not start a runner: <message>” - and when the cloud said it. Empty while it has as many, or while the cloud said nothing that explains it.
launchFailedAtTimestamp
giveBackRefusedstringA machine of the group the cloud would not take back, in its own words - a role or a policy somebody has to change - and when; it is asked again every quarter hour until it is taken. Empty while none is refused.
giveBackRefusedAtTimestamp
capacityRefusedbooleanlaunch_failure is the cloud having no machine of the kind the class asks for - no spot capacity, or the spot quota spent - which the class’s spot setting, or its fallback, is what changes; false for any other failure, and while there is none.
onDemandUntilTimestampSet while a spot class’s group starts on-demand machines because the cloud refused it spot (HostClass.fallback_on_demand): until this, and spot again after. Its class still says spot.

FleetHostVersion is one host’s halves: the runner binary and the machine under it.

FieldTypeWhat it is
hostIdstring
stateHostState
agentVersionstring
machineVersionstringEmpty on a host with no machine, such as the mock runner.
supportedbooleanWhether this control plane serves a host of that version. An unsupported host is refused at its next registration, with note saying why.
notestring
lastHeartbeatTimestamp
FieldTypeWhat it is
forgestringnetpolicy.Forges: “github”.
appIdstring (int64)
slugstring
clientIdstring
apiUrlstring
webUrlstring
hostslist of stringThe exact names a person’s token may be sent to.
installUrlstringWhere the app is installed on an account, which is what lets a token reach its repositories.
deletingbooleanBeing deleted: it takes no connection, and goes once what it granted has been revoked.
updatedAtTimestamp
FieldTypeWhat it is
forgestring
loginstringThe account, as the forge names it.
expiresAtTimestampWhen the token ends: it is refreshed before then.
connectedAtTimestamp
FieldTypeWhat it is
fullNamestringowner/name.
cloneUrlstringWhat a project’s repository is: https, with nothing of a credential in it.
defaultBranchstring
privateboolean
descriptionstring

Grafana is the one the control plane runs over the installation’s metrics and serves to its administrators.

FieldTypeWhat it is
urlstringWhere the control plane serves it: “/monitoring/grafana/”.
dashboardslist of GrafanaDashboardThe release’s, in the order they are listed.
FieldTypeWhat it is
uidstring
titlestring

HeaderInjection is a header the egress proxy sets: header, to prefix and then a value the workspace never holds - a team secret’s, or a token of the workspace’s identity. One of the two.

FieldTypeWhat it is
headerstring
secretstringThe team secret’s name.
prefixstringWhat goes before the value, as “Bearer ”.
identitystringThe audience of a token of the workspace’s identity, issued for the proxy to present: bound to no key, and saying so (spin.via = egress-proxy).
forgestringThe forge whose credential goes in the header, whole: “github” is the workspace owner’s own token, connected through the installation’s OAuth App (ForgeService), which the control plane keeps and refreshes.
methodslist of stringThe requests the header is set on: these methods, and paths under path_prefix by whole segments. Another request to the rule’s names is answered 403. None of either is every request.
pathPrefixstring

HealthCheck is one part of the installation as the control plane knows it.

FieldTypeWhat it is
partHealthPart
statusHealthStatus
reasonstringreason says in a line what was found, OK or not.
knownAtTimestampknown_at is when what decided the status was so: the moment it was asked for a part asked now, the collector’s last report, the last WAL file archived or failed, a failed job’s run.
problemslist of ProblemWhat is wrong in this part, each on its own: one per host, one per job, one for a part that is a single thing. Empty while the part is OK. At most 20 are listed, the worst first; problem_count is how many there are.
problemCountinteger (int32)
FieldTypeWhat it is
namestring
passedboolean
valuestringActual value from check
messagestringError message if failed

HealthPart is which part of the installation a check is of. - HEALTH_PART_DATABASE: The control plane’s database answers a query. - HEALTH_PART_DATABASE_ARCHIVE: The database’s continuous archive keeps up: its last WAL file sent and how many wait. Its base backups are taken by a timer outside the control plane, which records nothing it can read. - HEALTH_PART_LOG_STORE: The log store (Quickwit) beside the control plane answers that it is ready. - HEALTH_PART_COLLECTOR: The collector sends what it is given: spans to the trace store, samples to the metric store (GetTelemetryStatus). It is what says whether the metric store takes writes - the control plane is not one of the metric store’s readers. - HEALTH_PART_JOBS: The control plane’s periodic work: a job whose last run failed (ListJobs). - HEALTH_PART_HOSTS: The hosts registered and not taken out of the fleet: those whose command stream is not up, and those that answer and fail a check of their own (HostCheck). - HEALTH_PART_WAITING_WORKSPACES: Workspaces waiting for a runner, across the whole fleet.

One of: HEALTH_PART_UNSPECIFIED, HEALTH_PART_DATABASE, HEALTH_PART_DATABASE_ARCHIVE, HEALTH_PART_LOG_STORE, HEALTH_PART_COLLECTOR, HEALTH_PART_JOBS, HEALTH_PART_HOSTS, HEALTH_PART_WAITING_WORKSPACES.

HealthReport is what the supervisor inside a workspace observes about it. Here rather than beside the stream that carries it, for the reason SupervisorState is here: it is read from both sides - reported by the supervisor on its own connection (spin.agent.v1), and returned to an operator by WorkspaceService.GetWorkspaceStatus. It is also what keeps the dependency between the two packages pointing one way. spin.v1 is the vocabulary and spin.agent.v1 is the machine surface built on it; a type the operator’s side needs from the agent’s side would make each package need the other.

FieldTypeWhat it is
healthyboolean
checkslist of HealthCheckResult
  • HEALTH_STATUS_DEGRADED: Working, and something in it wants a look: some hosts not connected, a job’s last run failed, a workspace waiting longer than a machine takes to boot. - HEALTH_STATUS_FAILED: Not doing what it is for: the database does not answer, the archive’s last send failed, no host is connected.

One of: HEALTH_STATUS_UNSPECIFIED, HEALTH_STATUS_OK, HEALTH_STATUS_DEGRADED, HEALTH_STATUS_FAILED.

FieldTypeWhat it is
idstring
addressstring
stateHostState
capacityResources
allocatedResources
workspaceCountinteger (int32)
agentVersionstring
labelsmap of string to string
lastHeartbeatTimestamplast_heartbeat is whichever of this host’s two channels was heard from last, and they are not the same thing: the command stream carries what the host can be *told* (start this, stop that), and the volume agent’s own heartbeat renews the lease its disks are served under. Either refreshes this, so a fresh stamp says one of them is alive and not which: stream_heard_at and lease_renewed_at are each on its own. It is what the sweep that forgets a host gone for good reads.
registeredAtTimestamp
connectedbooleanconnected is the command stream, now: the half that decides whether this host can be given a workspace or asked to stop one. A host whose stream is gone while its volume agent keeps renewing reads as freshly heartbeated above and can be told nothing at all - which is the state an operator is looking at when they ask why a host takes no work.
goingAwaybooleangoing_away is this host on its way out: a runner told the control plane it is stopping - an operator’s restart, or the cloud taking the machine away - and it takes no new workspace from that moment. Nothing is written to the database for it (a state there would outlive the restart it described), so this is the only place an operator can see that the host they are looking at is leaving rather than idle.
checkslist of HostCheckchecks are what the host last found when it asked itself whether a workspace can run on it as it should, as its heartbeat said: held for as long as the host is connected, like going_away, and empty for a host that has said nothing yet.
hostClassstringhost_class is the class (HostClass.name) of the group that launched the machine, which ties the host to its FleetClass: “default” for a machine no group launched.
machineVersionstringmachine_version is the spin-machine release the host registered (its QEMU, kernel and firmware); empty for a host with no machine.
detectedResourcesdetected is what the host found it has when it last registered (cores, memory, disk GB), beside capacity, which is what it advertises: a HostPolicy capacity holds a machine back by saying it has less. Zero for a host that has not registered since it was made.
streamHeardAtTimestampEach channel on its own. stream_heard_at is the command stream’s last heartbeat the control plane recorded - unset for a host that never held one - and lease_renewed_at the volume agent’s last renewal of the lease its disks are served under, unset for one that never held a lease. A host whose stream is gone while its lease renews serves its disks and can be told nothing.
leaseRenewedAtTimestamp
connectedChangedAtTimestampconnected_changed_at is when connected last changed, as this control plane saw it: the stream registering while connected, its end while not. Unset where this control plane has seen neither since it started - stream_heard_at then says when the host was last heard. Held in memory, as connected is: a control plane that restarts starts again.
streamEndHostStreamEndWhy the host’s last command stream ended, while it is not connected; UNSPECIFIED while it is connected, and where this control plane has not seen one end. stream_end_detail is the error the stream ended with, in its own words.
streamEndDetailstring
hostnamestringhostname is the name the host’s machine goes by, as it last registered it: how a person tells one host from another where its id says nothing. Empty for a host that has not registered since it was made.
removalHostRemovalremoval is how this host leaves the fleet, decided by where it came from: the only removal the API takes for it, so the dashboard offers that one and no other.
removalRefusedstringremoval_refused is why that removal cannot run now - a workspace whose disk is there - in words an administrator acts on; empty while it can.
keysGiveninteger (int32)keys_given is how many teams’ disks this host was given the key of: what revoking it, or removing it as taken, marks for re-keying.
machineIdstringWhere the host’s machine is, as its cloud said when the host joined - never as the host said of itself: the machine’s id and type as that cloud names them, its zone and its region. Each empty for a host that joined with no cloud (a registration token: a development stack, a machine of one’s own), and for what its cloud did not say.
machineTypestring
zonestring
regionstring
reclaimableboolean or nullreclaimable is whether the cloud may take the machine back, as its cloud said of the instance when it joined - a spot machine is, whatever its class says: a group that fell back to on-demand, or one whose class was changed, starts machines its class does not describe. Unset where nothing says: a host that joined with no cloud, or one its cloud named nothing of.
holderslist of HostHolderholders is what keeps this host in the fleet, from the database: the workspaces whose disk is only here - whichever list of theirs leaves them out, a prebuild’s build, a team’s, another person’s, a failed one - and the volumes still here that are no such workspace’s disk, a trashed workspace’s or an agent’s home, each of which forgetting the host must detach first. At most 10; holder_count is how many there are.
holderCountinteger (int32)

HostCheck is one thing a host asks itself about, at start and every few minutes: a clock that is not synchronised, a KVM it cannot open, a resolver that answers its workspaces nothing - each a host that looks healthy to every other signal and fails its workspaces.

FieldTypeWhat it is
namestringname is what was checked: clock, kvm, resolver.
okboolean
detailstringdetail is what it found when it is not ok, in the host’s words.
checkedAtTimestamp

A kind of runner: the shape of the machines a group of the installation’s cloud starts for it, which the control plane makes and sizes. What a machine boots is the installation’s launch template, never this. “default” is the class a preset that names none runs on.

FieldTypeWhat it is
namestringLower-case letters, digits and -, a letter first, up to 31: it is part of the group’s name.
descriptionstring
instanceTypeslist of stringThe instance types it may be, as the cloud names them, patterns allowed (“c8id.*”); none is any type the rest admits.
vcpusMininteger (int32)
vcpusMaxinteger (int32)
memoryMibPerVcpuinteger (int32)The least memory a vCPU of it has, in MiB; 0 is 2048.
spotbooleanA machine the cloud may take back (each host drains first), or an on-demand one.
maxHostsinteger (int32)The most hosts of it; 0 is no limit of its own (the setting autoscaling_max_hosts bounds them all).
fallbackOnDemandbooleanA spot class whose group the cloud refuses spot machines for capacity starts on-demand ones for a while, and then spot again (FleetClass.on_demand_until); spot itself is not changed. Off, the class’s workspaces wait until somebody changes spot. Only a spot class has it.

HostDeparture is what draining the host, and removing it as Host.removal says, would do to each workspace that names it - the ones a drain moves, the ones that stay, the ones that lose their place on it and the ones that hold it - so the confirmation says it before it is done.

FieldTypeWhat it is
workspaceslist of WorkspaceDepartureAt most 20, the running first; count is how many there are.
countinteger (int32)

HostHolder is one thing a host holds that its removal would lose or has to wait for, with whose it is and what last happened to it.

FieldTypeWhat it is
kindHostHolderKind
workspaceIdstringThe workspace it is or was the disk of; for an agent’s home, the workspace that mounts it, or that last did by name alone (workspace_id empty).
workspaceNamestring
volumeIdstringThe volume, for a holder that is a volume (a trashed workspace’s disk, an agent’s home); empty for a workspace, whose disk the workspace names.
ownerIdstringWhose it is.
ownerEmailstring
stateWorkspaceStateThe workspace’s state; UNSPECIFIED for an agent’s home no workspace mounts.
lastEventWorkspaceEventTypeWhat last happened to the workspace, and when: its history’s newest entry. UNSPECIFIED and unset where it has none.
lastEventAtTimestamp

HostHolderKind is what a holder is, which says which list of whose shows it. - HOST_HOLDER_KIND_WORKSPACE: A person’s own workspace, in their workspaces list. - HOST_HOLDER_KIND_TEAM_WORKSPACE: A workspace of a team, in its members’ lists. - HOST_HOLDER_KIND_PREBUILD_BUILD: A prebuild’s build: kept stopped as its prebuild’s anchor, and in nobody’s list. - HOST_HOLDER_KIND_TRASHED_WORKSPACE: The disk of a workspace in its owner’s trash. - HOST_HOLDER_KIND_AGENT_HOME: A person’s agent’s home (AgentVolume).

One of: HOST_HOLDER_KIND_UNSPECIFIED, HOST_HOLDER_KIND_WORKSPACE, HOST_HOLDER_KIND_TEAM_WORKSPACE, HOST_HOLDER_KIND_PREBUILD_BUILD, HOST_HOLDER_KIND_TRASHED_WORKSPACE, HOST_HOLDER_KIND_AGENT_HOME.

FieldTypeWhat it is
hostIdstring
ruleslist of NetworkRule

HostPolicy is what an installation decides about one host. An unset field is the installation saying nothing about that setting, which leaves the host on its own default - not the same as setting it to nothing.

FieldTypeWhat it is
hostIdstring
shutdownGraceSecondsinteger or null (int32)Seconds this host stays up after a stop signal so what it runs can be suspended off it. The unit’s TimeoutStopSec still bounds it.
preemptibleboolean or nullWhether a stop here is the machine being taken away rather than coming back.
preemptionSourceanyWhich cloud announces that reclaim; setting one implies preemptible.
preemptionMetadataUrlstring or nullThat service’s address, for a private cloud or a test.
capacityCpuCoresinteger or null (int32)What this host advertises to the fleet, which is not what it has: an operator holds a machine back by saying it has less. Unset leaves the host advertising what it detects.
capacityMemoryMbinteger or null (int32)
capacityDiskGbinteger or null (int32)
maxWorkspaceCpuCoresinteger or null (int32)The ceiling one workspace may grow to here, for the machines it starts afterwards.
maxWorkspaceMemoryMbinteger or null (int32)
revisionstringrevision names the content, and is what a host reports it is running under.
writebackLimitBytesstring or null (int64)The host’s writeback thresholds (spin.agent.v1.HostPolicy says why): both or neither, the background below the limit. Unset is what the host booted with.
writebackBackgroundBytesstring or null (int64)
runningRevisionstringrunning_revision is what the host last said, empty where it has not said or is not connected. Different from revision is a policy still on its way, which is normal for the seconds after a write and a fault after that.
maxWorkspaceIoMbPerSecondinteger or null (int32)What one machine may read and write per second here, in MiB and in operations, for the machines it starts afterwards. Unset is no bound.
maxWorkspaceIoOpsPerSecondinteger or null (int32)

HostRemoval is how a host leaves the fleet. - HOST_REMOVAL_REVOKE: A host registered with a token, or a machine of a cloud no group of this installation sizes: RevokeRunner. Nothing else can take its machine away. - HOST_REMOVAL_GIVE_BACK: A machine of an autoscaling group, connected: RemoveHost gives it back to its group, which terminates it and is asked for one less. Revoking it would leave the machine running and paid for, in a group that counts it. - HOST_REMOVAL_FORGET: A machine of an autoscaling group, not connected: RemoveHost gives back a machine the group still has, and forgets the host now rather than once it has been silent for host_forget_after_hours.

One of: HOST_REMOVAL_UNSPECIFIED, HOST_REMOVAL_REVOKE, HOST_REMOVAL_GIVE_BACK, HOST_REMOVAL_FORGET.

FieldTypeWhat it is
idstring
hostIdstring
requestedBystringWho asked, and who approved: an email, or empty for a person no longer on the installation. Approved by nobody where the installation asks for no second administrator.
approvedBystring
reasonstring
incidentbooleanAn incident’s shell opens on a host still running workspaces.
minutesinteger (int32)How long it is open once it opens.
stateHostShellState
requestedAtTimestamp
approvedAtTimestamp
openedAtTimestamp
closesAtTimestamp
endedAtTimestamp
endedstringHow it ended, in words.
hostRetiredbooleanWhether its host has been retired since: revoked, its disks marked to be re-keyed, and given back to its group where it has one.
runninginteger (int32)How many workspaces the host still runs, while it is emptied.
  • HOST_SHELL_STATE_REQUESTED: Asked for, waiting for a second administrator. - HOST_SHELL_STATE_EMPTYING: Approved: the host is cordoned and its workspaces are being suspended to run elsewhere. - HOST_SHELL_STATE_OPEN: Open: a terminal may attach until closes_at. - HOST_SHELL_STATE_ENDED: Over: closed, or past its time. Its host is retired. - HOST_SHELL_STATE_REFUSED: Refused, or withdrawn before it was approved. Its host was never touched.

One of: HOST_SHELL_STATE_UNSPECIFIED, HOST_SHELL_STATE_REQUESTED, HOST_SHELL_STATE_EMPTYING, HOST_SHELL_STATE_OPEN, HOST_SHELL_STATE_ENDED, HOST_SHELL_STATE_REFUSED.

HostState mirrors internal/lifecycle.HostState (§28.1) and the CHECK on hosts.state: one vocabulary for the fleet, whichever component is asking. Only ACTIVE takes new work; a CORDONED or DRAINING host keeps serving (and keeps its lease) while it is evacuated, and the Agent needs to be told which of the two it is. It replaces a second set of names this schema carried for the same states - HEALTHY, DEGRADED, OFFLINE - where DEGRADED was a word nothing branched on and no name said “an operator stopped this host”.

One of: HOST_STATE_UNSPECIFIED, HOST_STATE_ACTIVE, HOST_STATE_CORDONED, HOST_STATE_DRAINING, HOST_STATE_DEAD.

HostStreamEnd is why a host’s command stream ended. - HOST_STREAM_END_HOST_CLOSED: The host closed it: a runner stopping or restarting. - HOST_STREAM_END_LOST: The connection went without the host closing it: a network fault, a runner killed, a machine that went away, a transport that timed out. - HOST_STREAM_END_CONTROL_PLANE_CLOSED: The control plane closed it: the host was revoked, or a newer stream of it replaced this one. - HOST_STREAM_END_TOO_FAST: The host sent far faster than any runner does, and was cut off. - HOST_STREAM_END_REFUSED_RELEASE: Its registration was refused: the host runs another release than the control plane’s. - HOST_STREAM_END_ERROR: Its registration could not be recorded, or the stream failed in a way none of the above says.

One of: HOST_STREAM_END_UNSPECIFIED, HOST_STREAM_END_HOST_CLOSED, HOST_STREAM_END_LOST, HOST_STREAM_END_CONTROL_PLANE_CLOSED, HOST_STREAM_END_TOO_FAST, HOST_STREAM_END_REFUSED_RELEASE, HOST_STREAM_END_ERROR.

Identity provider info (returned to clients for login UI) Built-in provider has id=“github”; dynamic providers have UUIDv7 IDs

FieldTypeWhat it is
idstring“github” for built-in, UUIDv7 for dynamic
namestringDisplay name (e.g., “Sign in with Okta”)
providerTypestringgithub (built-in), oidc, google, azure-ad
teamIdstringEmpty if system-wide provider
isDefaultbooleanTrue for built-in GitHub provider

Image is one name a workspace can be created from: a publication in this installation’s database that its settings also permit. It is not a container image and does not come from a registry - it is a volume somebody published here, which is why a name that looks like “ubuntu:22.04” is not one unless it was published under that name. A disk image a workspace’s disk can be cloned from: a volume published in this installation, not a container image, and never pulled from a registry.

FieldTypeWhat it is
refstringThe name a workspace asks for. It moves: a publish under it tags new bytes, and what a disk began as is its volume’s parent snapshot, not this.
virtualSizeBytesstring (int64)What the disk cloned from it will hold before the workspace writes anything.
publishedAtTimestampWhen the publication this ref resolves to was made.
namestringWhat a person choosing a disk is shown: its name (“base image”) and what it is ready for. An empty name is a publication made before one was asked for; show the ref.
descriptionstring

InjectionStatus is one header the egress proxy sets on the workspace’s requests to a brokered name, and whether the workspace’s team holds what it is set from.

FieldTypeWhat it is
policystringThe policy, by name, and the names its rule brokers.
nameslist of string
headerstring
fromstringWhat the header is set from: a team secret by name, “<forge> app”, or “identity for <audience>”.
heldbooleanWhether the team holds it: the secret is set, the forge app is set, an identity is always held. False is a request refused with credentials.

What happened to the installation itself, which its administrators are told of: an event of no workspace, recorded where the control plane hears it. - INSTALLATION_EVENT_TYPE_ALERT_FIRING: One of the release’s alert rules fired in the installation’s Grafana - INSTALLATION_EVENT_TYPE_ALERT_RESOLVED: A rule that fired is no longer past its threshold

One of: INSTALLATION_EVENT_TYPE_UNSPECIFIED, INSTALLATION_EVENT_TYPE_ALERT_FIRING, INSTALLATION_EVENT_TYPE_ALERT_RESOLVED.

InstallationPlace is where the installation runs, as its control plane’s machine read it once when it started - never asked of the cloud again per request - and the release it runs. What a cloud did not say, or an installation with no cloud (a development stack, a machine of one’s own), is empty.

FieldTypeWhat it is
providerstringThe provider the installation was made on, as its document names it: “aws”, “self-hosted”.
accountstringThe cloud account it runs in, as that cloud names it.
regionstring
releasestringThe release the control plane runs, “v20261112.01”.
machineImagestringThe machine image the control plane’s machine booted, as its cloud names it.
FieldTypeWhat it is
namestring
intervalSecondsstring (int64)Zero for a job only run by hand, which has no next_run_at.
runningboolean
nextRunAtTimestampWhen the schedule next starts it.
lastRunJobRunUnset until it has run on this installation.
lastSucceededAtTimestamp
titlestringThe job as a person names it: “Storage collection” for storage-gc.
doesstringA sentence of what it does.
whileFailingstringWhat stays undone while it fails, said after “While it fails, ”: “new workspaces start from an older prebuild”. What a failure’s verdict says, so whoever reads it knows how soon it needs them.
recentRunslist of JobRunIts newest runs, newest first, at most twenty: what a list of jobs shows each one’s recent outcomes and durations from, without asking for every job’s runs. Each has its id, start, end and outcome only; ListJobRuns has the rest.
FieldTypeWhat it is
runIdstring
jobstring
startedAtTimestamp
finishedAtTimestampUnset while it runs.
outcomeJobRunOutcome
countsmap of string to string (int64)What it did, by the job’s own names for it: objects deleted, bytes freed, hosts forgotten.
errorstringWhy it failed; empty when it did not.
traceIdstringThe run’s trace id, which every record it logged carries; empty when it was not recorded. Whether the store kept the trace is LogService.KeptTraces’s to say.
askedBystringThe admin who ran it by hand; empty for a run the schedule started.

How one run of a job ended, or that it has not.

One of: JOB_RUN_OUTCOME_UNSPECIFIED, JOB_RUN_OUTCOME_RUNNING, JOB_RUN_OUTCOME_SUCCEEDED, JOB_RUN_OUTCOME_FAILED.

LogIndex is one index of the store.

FieldTypeWhat it is
idstring
retentionstringHow long it keeps what it holds, in the store’s words (“30 days”); empty for forever.
timestampFieldstringThe field its records are dated by: what a search’s window is over.
defaultSearchFieldslist of stringWhat a query’s bare words are searched in.
fieldslist of LogIndexField
documentsstring (int64)What it holds: records, the splits they are kept in, and the splits’ size in the bucket and the records’ before compression.
splitsstring (int64)
sizeBytesstring (int64)
uncompressedBytesstring (int64)
oldestTimestampWhen its oldest and newest records are dated; unset while it holds none.
newestTimestamp

LogIndexField is one field of an index’s mapping.

FieldTypeWhat it is
namestringA dotted path for a field inside an object field.
typestringThe store’s type: text, json, u64, bool, bytes, datetime, array<text>…
tokenizerstringHow a text or JSON field is split into what a query matches: “raw” is the whole value as written, “default” is its words, lowercased. Empty for any other type.
indexedbooleanWhether a query can match it, and whether it can be counted and ranged over fast.
fastboolean

LogInterval is how many records one interval holds, by severity.

FieldTypeWhat it is
startTimestamp
bySeveritymap of string to string (int64)

LogRecord is one record as OpenTelemetry names its parts.

FieldTypeWhat it is
timeTimestamp
severitystring
servicestringThe process that wrote it: controlplane, runner, proxy.
bodyValueWhat was logged: its message, or the structure it logged.
attributesStruct
resourceAttributesStruct
traceIdstringThe trace it was written in, hex; empty for none.
spanIdstring

MemoryUsagePoint is the most the machine used over a step - running out is a peak, not a mean - against what it held, as CpuUsagePoint.

FieldTypeWhat it is
startTimestamp
usedBytesstring (int64)
heldBytesstring (int64)
memoryBytesstring (int64)
maxMemoryBytesstring (int64)

NetworkPolicy is a tag a workspace can be created with, and what the hosts reporting it say it allows. The hosts are the authority: this is what they last said they enforce.

FieldTypeWhat it is
namestring
hostslist of HostNetworkPolicyWhat each host reporting this tag says it enforces.
declaredbooleandeclared says the installation has this policy, and rules are what it allows. A policy with no hosts is declared and not yet enforced anywhere.
ruleslist of NetworkRule
teamIdstringThe team whose admins declared it, which only its workspaces and those of the teams below it may run under; empty is the installation’s.

NetworkPolicyRule is a policy as an administrator writes it, in the words the config file takes: a name, which is a tag - letters, digits, - and _, up to 32 - and the rules it allows, each these destinations on these ports. A policy with no rules allows nothing.

FieldTypeWhat it is
namestring
ruleslist of NetworkRule

NetworkRule is one thing a network policy allows: these destinations on these ports. Within a rule the two intersect - every destination on every port - and a policy is the union of its rules, so “53/udp to one resolver and 443 to github.com” is two rules and not a product of both. Here and not beside a policy for the reason HealthReport is: the control plane’s policy, the one a host reports it enforces and the one a host is given are one vocabulary.

FieldTypeWhat it is
allowlist of stringIPv4 prefixes in CIDR.
allowNameslist of stringNames, exact or with a leading ”*.”: the host opens the address its own resolver answers a machine with, for as long as the answer lives.
portslist of stringDestination ports as “443” (TCP, which is what a bare number means), “443/udp”, a range as “8000-8100” or “8000-8100/udp”, or “icmp” for a ping. None is every port, at the destinations above; none of those is every destination, on these ports.
brokerbooleanThe host’s egress proxy stands in for these names, on HTTPS only: a machine reaches them through it and never directly, and it adds what the machine never holds. Names only.
injectlist of HeaderInjectionHeaders the proxy sets on a brokered rule’s requests, each from a secret of the workspace’s team (or the nearest team above it with one by that name). Brokered rules only.
cloudCloudAccessThe principal the proxy authorizes a brokered rule’s requests as, on its cloud: the host takes its credentials as the workspace, with a token of its identity. Brokered rules naming that cloud’s endpoints only, and not with inject.
verifySnibooleanThe host’s egress proxy reads the TLS server name of each connection to these names and passes on, untouched, only one this rule names: an address shared with other names opens only these to a client that says which it wants. A connection with no name, or one hiding it (ECH), goes nowhere. Names only, on TCP, never with broker; it does not stop a client that lies.
principalstringWhose connections a brokered rule stands in for: “agent” (the workspace’s agent, whose packets its guest marks), “user” (everything else the workspace sends), or “any” (empty: both). Two rules for one name, one per principal, each with its own injections and methods, say what the person may do and what the agent may. Brokered rules only: an agent reaches nothing outside the proxy, so a rule that is not brokered is the person’s already.

NetworkUsagePoint is what the machine’s network carried over a step.

FieldTypeWhat it is
startTimestamp
sentBytesstring (int64)
receivedBytesstring (int64)

Notification is one event of a workspace’s timeline its owner is told of: what happened, and what they can do about it.

FieldTypeWhat it is
idstringThe workspace event’s id.
workspaceIdstring
workspaceNamestring
eventWorkspaceEventType
createdAtTimestamp
subjectstringOne line saying what happened.
bodystringWhat happened, in full.
commandstringThe command that does what the owner can do about it; empty where nothing is to be done.
deliverieslist of NotificationDeliveryEmpty where it was never sent: email off, or this kind turned off.

How a notification leaves the installation.

One of: NOTIFICATION_CHANNEL_UNSPECIFIED, NOTIFICATION_CHANNEL_EMAIL.

FieldTypeWhat it is
channelNotificationChannel
stateNotificationDeliveryState
attemptsinteger (int32)
lastErrorstringWhat the last attempt that failed was told; empty once one succeeded.
sentAtTimestamp

Where one notification’s delivery on one channel is. - NOTIFICATION_DELIVERY_STATE_PENDING: Not sent yet, or tried and to be tried again - NOTIFICATION_DELIVERY_STATE_SENT: The channel accepted it - NOTIFICATION_DELIVERY_STATE_FAILED: Every attempt failed; it is not tried again

One of: NOTIFICATION_DELIVERY_STATE_UNSPECIFIED, NOTIFICATION_DELIVERY_STATE_PENDING, NOTIFICATION_DELIVERY_STATE_SENT, NOTIFICATION_DELIVERY_STATE_FAILED.

One kind of event and whether the caller is emailed about it: a workspace’s event, or the installation’s (an administrator’s alone). Exactly one of event and installation_event is set.

FieldTypeWhat it is
eventWorkspaceEventType
emailboolean
installationEventInstallationEventType

ObservedDestination is one address the workspace was allowed to reach, with what the host’s ruleset counted and the name its resolver answered with that address, where it holds one.

FieldTypeWhat it is
addressstring
namestring
packetsstring (int64)What the workspace sent there, every packet of every flow.
bytesstring (int64)
protocolstring“tcp”, “udp”, “icmp”, or the protocol’s number.
portintegerFor tcp and udp; zero otherwise.
packetsReceivedstring (int64)What came back to the workspace from there.
bytesReceivedstring (int64)

OutsideShareState is how far a snapshot’s share outside its team is. - OUTSIDE_SHARE_STATE_UNSPECIFIED: None: the snapshot was never shared outside its team, nor made public. - OUTSIDE_SHARE_STATE_PREPARING: A host is writing the keys a clone outside the team reads the snapshot with. - OUTSIDE_SHARE_STATE_READY: Somebody of another team can create a workspace from it.

One of: OUTSIDE_SHARE_STATE_UNSPECIFIED, OUTSIDE_SHARE_STATE_PREPARING, OUTSIDE_SHARE_STATE_READY.

Pagination for list requests

FieldTypeWhat it is
pageSizeinteger (int32)
pageTokenstring
FieldTypeWhat it is
nextPageTokenstring
totalCountinteger (int32)
FieldTypeWhat it is
idstring
namestring
credentialIdstring (byte)
createdAtTimestamp
lastUsedAtTimestamp

PasskeyAssertion is what navigator.credentials.get answers, and the challenge it answers.

FieldTypeWhat it is
challengestring (byte)
credentialIdstring (byte)
clientDataJsonstring (byte)
authenticatorDatastring (byte)
signaturestring (byte)ECDSA’s, in ASN.1 DER, as WebAuthn returns it.

PasskeyPurpose is what a ceremony’s challenge is for. - PASSKEY_PURPOSE_REGISTER: A passkey registered: the registration answers it. Subject: none. - PASSKEY_PURPOSE_ADD_PASSKEY: Another passkey registered while the account has one: an assertion of one it has answers it. Subject: the new credential’s id, base64url. - PASSKEY_PURPOSE_ADD_SSH_KEY: An SSH key added (SSHKeyService.AddSSHKey). Subject: the key, in authorized_keys form. - PASSKEY_PURPOSE_DELETE_PASSKEY: A passkey deleted. Subject: its id. - PASSKEY_PURPOSE_ADD_GUEST: A guest let into a workspace (WorkspaceService.AddWorkspaceGuest). Subject: “<workspace id> <email>”. - PASSKEY_PURPOSE_CREATE_EXEC_KEY: An API key made with workspace:exec (AuthService.CreateAPIKey), which is a shell in every workspace of its person’s. Subject: the key’s name.

One of: PASSKEY_PURPOSE_UNSPECIFIED, PASSKEY_PURPOSE_REGISTER, PASSKEY_PURPOSE_ADD_PASSKEY, PASSKEY_PURPOSE_ADD_SSH_KEY, PASSKEY_PURPOSE_DELETE_PASSKEY, PASSKEY_PURPOSE_ADD_GUEST, PASSKEY_PURPOSE_CREATE_EXEC_KEY.

What one role’s resources of one of the cloud’s services cost, in millionths of the bill’s currency: the control plane, the proxy and the database are three roles of one EC2.

FieldTypeWhat it is
rolestringAs the resources carry it (on AWS, their spin:role tag); empty where they carry none, which is said as untagged.
servicestring
microsstring (int64)
FieldTypeWhat it is
artifactPlatformImageArtifact
statePlatformImageState
detailstringWhy it failed, or why it is left alone.
versionstringThe machine’s release, or the supervisor’s (the control plane’s) version.
updatedAtTimestamp
  • PLATFORM_IMAGE_ARTIFACT_BASE: The machine’s base image, every workspace’s disk’s floor. - PLATFORM_IMAGE_ARTIFACT_SUPERVISOR: The supervisor extension every workspace is handed. - PLATFORM_IMAGE_ARTIFACT_AGENT_HOME: The empty home every agent’s volume is cloned from.

One of: PLATFORM_IMAGE_ARTIFACT_UNSPECIFIED, PLATFORM_IMAGE_ARTIFACT_BASE, PLATFORM_IMAGE_ARTIFACT_SUPERVISOR, PLATFORM_IMAGE_ARTIFACT_AGENT_HOME.

  • PLATFORM_IMAGE_STATE_UNAVAILABLE: This build carries nothing to publish. - PLATFORM_IMAGE_STATE_FOREIGN: The ref names an image somebody else published, which is left as it is.

One of: PLATFORM_IMAGE_STATE_UNSPECIFIED, PLATFORM_IMAGE_STATE_PENDING, PLATFORM_IMAGE_STATE_PUBLISHED, PLATFORM_IMAGE_STATE_PUBLISHING, PLATFORM_IMAGE_STATE_FAILED, PLATFORM_IMAGE_STATE_UNAVAILABLE, PLATFORM_IMAGE_STATE_FOREIGN.

Who may reach a published port. Per port rather than per workspace: one workspace serves a demo anyone may see and an admin panel only its owner may, and a single setting for both makes the safe answer for one the wrong answer for the other. UNSPECIFIED is not a level and is never stored - the column’s CHECK excludes it. A request that leaves it at proto3’s zero is treated as PRIVATE, which is the direction to be wrong in: the cost of failing closed is a confusing error, and the cost of failing open is a port somebody published without meaning to. - PORT_ACCESS_PRIVATE: Only the workspace’s owner, who must be signed in. - PORT_ACCESS_WHITELIST: The owner, and the users the owner granted. See GrantPortAccess. - PORT_ACCESS_PUBLIC: Anyone, with no session at all. Nothing is asked and nobody is redirected to a login. Until the workspace stops or fails: then the port is PRIVATE again, and made public again when it is meant to be.

One of: PORT_ACCESS_UNSPECIFIED, PORT_ACCESS_PRIVATE, PORT_ACCESS_WHITELIST, PORT_ACCESS_PUBLIC.

One user a whitelisted port is shared with.

FieldTypeWhat it is
userIdstring
emailstringOutput only, so a list is readable without a second lookup
grantedAtTimestamp

A prebuild: one build of a project’s ref at a commit, and the snapshot it left.

FieldTypeWhat it is
idstring
projectIdstring
refstring
commitstring
statePrebuildState
snapshotIdstring
parentIdstringThe prebuild it was built on, and how many builds it is from the image (0: built from it).
depthinteger (int32)
imagestring
logstringThe tail of what its build’s create tasks wrote (GetPrebuild only), and why it failed.
errorstring
createdAtTimestamp
builtAtTimestamp
workspaceCountinteger (int32)In ListPrebuilds: the workspaces opened from it that are not deleted, whoever’s they are.
reportedAtTimestampWhen its build’s guest said the checkout and create tasks were done; unset before it did.
spinYamlbooleanWhether the checkout had a .spin.yaml at its root, as the guest reported: without one the build is the clone alone, with no create tasks run. Read only with reported_at.
storedBytesstring or null (int64)What it keeps in the object store, as storage-gc last read it; unset before a reading counted it.
buildWorkspaceIdstringThe workspace that ran its build (workspaces.prebuild_id), while its row is kept, and whose it is: its events, logs and traces are its owner’s to read, and no list of workspaces shows it.
buildWorkspaceOwnerIdstring

A prebuild ref the project’s forge has not.

FieldTypeWhat it is
refstring
sinceTimestampThe job’s first look that found it missing.
  • PREBUILD_STATE_RETIRED: Superseded and given back: its snapshot is being deleted.

One of: PREBUILD_STATE_UNSPECIFIED, PREBUILD_STATE_BUILDING, PREBUILD_STATE_READY, PREBUILD_STATE_FAILED, PREBUILD_STATE_RETIRED.

What a project’s prebuilds keep in the volumes’ bucket, and what that would cost a month at what the last billed day charged: an estimate, never said without the day it is from.

FieldTypeWhat it is
storedBytesstring (int64)As the store was last read (Admin’s Storage, PREBUILD).
dayTimestampThe billed day the rate is from: its first instant, UTC. Unset, with month_micros, where no day before the reading billed the bucket, or the prebuilds keep nothing.
monthMicrosstring or null (int64)

PreemptionSource mirrors spin.agent.v1.PreemptionSource, which is what reaches the host.

One of: PREEMPTION_SOURCE_UNSPECIFIED, PREEMPTION_SOURCE_AWS, PREEMPTION_SOURCE_GCP, PREEMPTION_SOURCE_AZURE.

Problem is one thing wrong with the installation, said whole: why, what it takes down, what shows it and what to do. Nothing is kept of it - it is read off the installation as it is now, and is gone when what caused it is.

FieldTypeWhat it is
causestringcause says in a line what was found.
sinceTimestampsince is when what decided it was so, as HealthCheck.known_at is: a host’s command stream last heard, a check’s last run, a job’s failed run. Unset where nothing says.
impactProblemImpact
evidencelist of ProblemEvidenceWhat shows it, each a thing the console has a page for.
runbookIdstringThe runbook to follow (Runbook.id), of the runbooks this release serves: never empty.
actionslist of ProblemActionWhat the console itself can do about it, each on the host or the job the problem is of.
hostIdstringThe host the problem is of, and the name its machine goes by; empty for one that is not a host’s.
hostnamestring
jobstringThe job (Job.name) the problem is of, and its title; empty for one that is not a job’s.
jobTitlestring

ProblemAction is something the console can do about a problem, each an RPC it has. - PROBLEM_ACTION_CORDON_HOST: DrainHost without suspend: the host takes no new workspace and keeps what it runs. - PROBLEM_ACTION_DRAIN_HOST: DrainHost with suspend: its workspaces are moved to other hosts. - PROBLEM_ACTION_RUN_JOB: RunJobNow: the job is run again, now. - PROBLEM_ACTION_RECOVER_WORKSPACE: RecoverUserWorkspace, of each workspace the problem names: its disk is on a host that is gone, and it runs again only once moved off it.

One of: PROBLEM_ACTION_UNSPECIFIED, PROBLEM_ACTION_CORDON_HOST, PROBLEM_ACTION_DRAIN_HOST, PROBLEM_ACTION_RUN_JOB, PROBLEM_ACTION_RECOVER_WORKSPACE.

ProblemEvidence names one thing that shows a problem. The console turns each into a link to its own page; none is a URL.

No fields: {}.

ProblemImpact is what a problem takes down: the workspaces under it as rows of the database, or, for a part with nothing under it, what stops working.

FieldTypeWhat it is
stopsstringWhat stops working, in a line: “log lines are not kept”. Empty where the rows say it.
runningWorkspacesinteger (int32)The workspaces it affects, counted whole: running on the host now, and at rest with their disk only there - stopped or failed, each one’s next start is on that host. For workspaces waiting for a host, waiting_workspaces.
restingWorkspacesinteger (int32)
waitingWorkspacesinteger (int32)
workspaceslist of AffectedWorkspaceAt most 10 of them, the running first, then by name: the counts above are the whole.

A project: a repository and the shape of the workspace that opens it.

FieldTypeWhat it is
idstring
namestring
slugstringWhat a person names it by in the installation: teams.slug’s shape
descriptionstring
repositorystringAn https URL, with nothing of a credential in it
refstringThe branch or tag a workspace opens at unless the open names one
imagestringAs CreateWorkspaceRequest.image; empty is the installation’s default when opened
presetstringAs CreateWorkspaceRequest.preset; empty likewise
networkTagslist of string
workspaceCountinteger (int32)Workspaces open on it, the trash included
createdAtTimestamp
updatedAtTimestamp
prebuildRefslist of stringThe refs it prebuilds (spin#480 §3): none is none. Each is built as it moves, and opening the project at one clones its newest ready prebuild.
prebuildRebaseEveryinteger (int32)Every how many prebuilds of a ref one is built from the image again, rather than on the one before: a clone is a layer deeper than what it is cloned from.
prebuildOwnerIdstringWho the builds run as, for what they use: the project admin who last named the refs.
sharedWithEveryonebooleanSeen by everybody signed in; otherwise by its admins and shares.
administersbooleanWhether the caller may change, share and delete it.
adminIdslist of stringIts admins and whom it is shared with: shown to its admins, empty to everybody else.
sharedUserIdslist of string
sharedTeamIdslist of string
readyPrebuildCountinteger (int32)In ListProjects: how many of its prebuilds are ready to open from.
prebuildKeepinteger (int32)How many of each ref’s newest ready prebuilds are kept when no workspace was opened from them.
timeToReadyProjectTimeToReadyIn GetProject: how long its workspaces took to be ready. Unset where none has been.

How long a project’s workspaces took from their create to their project being ready in them - the repository checked out and its create tasks done, as each one’s guest first said it, the wait for a host and the boot included - over the last 20 that got there. One that never did - it failed, or was deleted first - is not counted, and neither is one opened from a prebuild: this is what opening without one costs. A workspace whose first boots failed its project counts from its create to the boot that went.

FieldTypeWhat it is
workspacesinteger (int32)How many workspaces the times are over: 1 to 20.
medianDuration
slowestDuration

A workspace open on a project, as the project’s admins read it: whose it is and how it is, and nothing that lets them into it.

FieldTypeWhat it is
idstring
namestring
ownerIdstring
ownerNamestring
ownerEmailstring
stateWorkspaceStateAs Workspace.state, DEGRADED included.
sinceTimestampSince when it has been in that state: when its guest answered for a running one, and when its row last changed for any other.
FieldTypeWhat it is
targetstringWhere the attempt went: the destination, as the supervisor saw it (host and port).
detailsmap of string to stringWhat the supervisor held of it, in its own words: which user in the guest, which process, why the policy refused.
atTimestampWhen the attempt was made, as the guest clock held it.
FieldTypeWhat it is
addressstring
namestring
protocolstring“tcp”, “udp”, “icmp”, or the protocol’s number.
portintegerFor tcp and udp; zero otherwise.
packetsstring (int64)

RefusedVolume is a disk its host is not serving, and the workspace that cannot run for it.

FieldTypeWhat it is
volumeIdstring
refusalstringThe token an alert keys on, and the sentence the host sent with it (VolumeStatus).
refusalDetailstring
hostIdstringThe host refusing it; empty for a disk placed nowhere.
hostNamestring
workspaceIdstringThe workspace it is the disk of; empty for a disk no workspace runs on.
workspaceNamestring
workspaceStateWorkspaceState
ownerIdstringWhose the workspace is.
ownerEmailstring

Registration mode enum - REGISTRATION_MODE_OPEN: Anyone can register - REGISTRATION_MODE_WHITELIST: Only whitelisted emails/domains - REGISTRATION_MODE_CLOSED: No new registrations

One of: REGISTRATION_MODE_UNSPECIFIED, REGISTRATION_MODE_OPEN, REGISTRATION_MODE_WHITELIST, REGISTRATION_MODE_CLOSED.

FieldTypeWhat it is
idstring
tokenPrefixstringFirst 8 chars for identification
descriptionstringHuman-readable description
teamIdstringOptional: team scope for registered host
expiresAtTimestamp
createdAtTimestamp
createdBystring
usedboolean
usedByHostIdstringHost ID that used this token; a reusable token’s last one
reusablebooleanA pool’s token: it registers every host that presents it until it expires or is revoked.
hostPolicyHostPolicyWhat every host it registers is told (HostPolicy without its host_id); unset tells them nothing, and they keep their own defaults until an operator says otherwise.

RekeyState is how far a disk’s re-key is. - REKEY_STATE_PENDING: Marked by a revoke: re-keyed once its workspace cannot run. - REKEY_STATE_COPYING: A host is copying the disk. - REKEY_STATE_READY: Copied: the workspace is pointed at the copy and the disk deleted on the next pass.

One of: REKEY_STATE_UNSPECIFIED, REKEY_STATE_PENDING, REKEY_STATE_COPYING, REKEY_STATE_READY.

FieldTypeWhat it is
namestring
outcomestringfiltered, refused, upstream_failed or malformed.
atTimestamp

ResourcePreset is a class of workspace: its size, and how a workspace of it may grow. Every workspace is created from one.

FieldTypeWhat it is
idstring
namestringDisplay name (e.g., “Small”, “Medium”, “Large”)
descriptionstringDescription of the preset
cpuCoresinteger (int32)Number of CPU cores
memoryMbinteger (int32)Memory in megabytes
diskGbinteger (int32)Disk space in gigabytes
burstBurstMode
isDefaultbooleanThis is the default preset
enabledbooleanPreset is available for selection
sortOrderinteger (int32)Display order (lower = first)
createdAtTimestamp
updatedAtTimestamp
burstFloorCpuCoresinteger (int32)What a workspace of a burst mode starts with; at most cpu_cores and memory_mb.
burstFloorMemoryMbinteger (int32)
bandwidthMbpsinteger (int32)What a workspace of it may carry each way, in megabits a second; 0 is unshaped.
rpoSecondsinteger (int32)How far behind the object store a workspace of it may fall, in seconds; 0 is the installation’s (the setting volume_rpo_seconds).
hostClassstringThe host class its workspaces run on (HostClass).
agentMinMemoryMbinteger (int32)What a workspace has to hold for its agent to start there, in MB, for whoever picks a preset.
fromConfigbooleanSeeded or applied from the installation’s config file (the release’s presets where it names none); false is one an administrator added. An edit since does not change it.
minMemoryMbinteger (int32)The least any preset may start its workspaces at, in MB: memory_mb for a fixed one, burst_floor_memory_mb for a burst one. A create or update below it is refused; one written before it was asked keeps what it has until an administrator changes it.

Resource allocation for workspaces. Initial values (cpu_cores, memory_mb) are used at boot time. Max values control scaling limits: - 0 = unlimited (burstable to host capacity) - >0 = hard limit (cannot exceed)

FieldTypeWhat it is
cpuCoresinteger (int32)Initial CPU cores at boot (default: 1)
memoryMbinteger (int32)Initial memory in MB at boot (default: 512)
diskGbinteger (int32)Disk size in GB (default: 10)
maxCpuCoresinteger (int32)Max CPU cores (0 = unlimited)
maxMemoryMbinteger (int32)Max memory in MB (0 = unlimited)
bandwidthMbpsinteger (int32)What a workspace’s network carries each way, in megabits a second (0 = unshaped): its preset’s, held on its host by a token bucket on each way out of its machine’s namespace. Its vsock - ssh, the editor, forwarded ports - is not shaped.

What one role cost on one day, its services summed.

FieldTypeWhat it is
rolestringEmpty where the resources carry none.
microsstring (int64)
FieldTypeWhat it is
idstringStable: alert rules and pages link /admin/runbooks/<id>.
titlestring
severitystringcritical, warning or info.
ownerstringThe role that keeps it true: operator, security.
lastReviewedstringYYYY-MM-DD: when it was last held to the release it describes.
appliesToRunbookAppliesTo

What sends an operator to a runbook, each as the installation names it.

FieldTypeWhat it is
alertslist of stringGrafana alert rule uids.
jobslist of stringControl plane job names (Job.name).
eventslist of stringThe notices a workspace’s owner gets, by WorkspaceEventType without its prefix: HELD.
dashboardslist of stringGrafana dashboard uids.

User’s uploaded SSH public key

FieldTypeWhat it is
idstring
namestringUser-provided name
fingerprintstringSHA256 fingerprint
publicKeystringFull public key
createdAtTimestamp
expiresAtTimestampNo last_used_at: a user’s key authenticates inside the guest, over SSH, where the control plane is not, so the only honest answer it could give is “unknown”. Compare ApiKey.last_used_at, which the control plane stamps because it is the thing being presented to. When an enrolled key stops logging in; unset for a key of the person’s own.

What one of the cloud’s services cost on one day, in millionths of the bill’s currency.

FieldTypeWhat it is
servicestring
microsstring (int64)

ServiceHealth is one service over a window: the traces begun in it - what it was asked to do - how many failed and how long they took, and how many errors it logged.

FieldTypeWhat it is
servicestring
tracesstring (int64)
failedTracesstring (int64)
p50Millisnumber (double)
p95Millisnumber (double)
errorLogsstring (int64)
intervalslist of ServiceInterval
FieldTypeWhat it is
startTimestamp
tracesstring (int64)
failedTracesstring (int64)

SettingDefinition is one setting of the installation as the code defines it.

FieldTypeWhat it is
keystring
typeSettingType
defaultValuestringWhat is in force where the installation says nothing, as text of the type.
minstring or null (int64)
maxstring or null (int64)
choiceslist of stringThe values a STRING setting takes; empty is any.
reachSettingReachWhat it touches once saved.
restartbooleanIt is read when the control plane starts: a change is in force after its next restart.
sectionstringWhich page it is on: general, workspaces, fleet, network, security, registration, telemetry, logs, bill, email, storage, installation, control_plane.
labelstringA few words that name it, and a sentence that says what it does and what its zero means.
summarystring
writerSettingWriter

SettingReach is what a saved installation setting touches, and when: each setting’s definition declares one (internal/controlplane/settings), so the screen that edits it can say so before the save. - SETTING_REACH_RUNNING_WORKSPACES: The workspaces running now, at the control plane’s next look at them. - SETTING_REACH_NEW_WORKSPACES: Workspaces created from now on; those that exist keep what they were made with. - SETTING_REACH_NEXT_HEARTBEAT: Each runner at its next heartbeat, and the workspaces running on it. - SETTING_REACH_NEXT_REQUEST: What is asked from now on - a project made, a shell opened, a workspace deleted; what was done before keeps the terms it was done under. - SETTING_REACH_NEXT_PASS: The next pass of the job that applies it: the autoscaler, the prebuilds’ retirement, the collector’s read of its policy, the daily look for a release.

One of: SETTING_REACH_UNSPECIFIED, SETTING_REACH_RUNNING_WORKSPACES, SETTING_REACH_NEW_WORKSPACES, SETTING_REACH_NEXT_HEARTBEAT, SETTING_REACH_NEXT_REQUEST, SETTING_REACH_NEXT_PASS.

SettingType is how a setting’s value is written as text, which is how GetSettings answers it and SetSettings takes it. - SETTING_TYPE_INT: A whole number in decimal, within the definition’s min and max. - SETTING_TYPE_BOOL: “true” or “false”. - SETTING_TYPE_STRING: Text; a definition with choices takes only those. - SETTING_TYPE_LIST: A JSON array of strings. - SETTING_TYPE_JSON: A JSON document, as the code that reads it defines it. - SETTING_TYPE_DURATION: A Go duration (”60s”); min and max are seconds.

One of: SETTING_TYPE_UNSPECIFIED, SETTING_TYPE_INT, SETTING_TYPE_BOOL, SETTING_TYPE_STRING, SETTING_TYPE_LIST, SETTING_TYPE_JSON, SETTING_TYPE_DURATION.

SettingWriter is who writes a setting, and so where an administrator changes it. - SETTING_WRITER_ADMIN: SetSettings, and the installation’s file seeds it. - SETTING_WRITER_FILE: The installation’s file alone: what whoever made the installation knows, and a change of which the dashboard cannot make whole - the proxy holds the base domain too. - SETTING_WRITER_STORE: A page of its own, which checks it against the real thing before it is written: the object store, the mail server. - SETTING_WRITER_CONTROL_PLANE: The control plane, for itself.

One of: SETTING_WRITER_UNSPECIFIED, SETTING_WRITER_ADMIN, SETTING_WRITER_FILE, SETTING_WRITER_STORE, SETTING_WRITER_CONTROL_PLANE.

A snapshot is a rotation of a workspace’s volume, published as a commit. It has no name outside its id.

FieldTypeWhat it is
idstring
workspaceIdstring
descriptionstringUser-provided description
createdAtTimestamp
isPublicbooleanWhether snapshot is publicly visible
shareCountinteger (int32)Number of users snapshot is shared with
accessTypeSnapshotAccessTypeHow user has access
stateSnapshotState
withMemorybooleanwith_memory: the snapshot also kept the running machine’s memory, so restoring it resumes the processes where they were instead of booting the disk. The memory is on the host the workspace ran on.
parentSnapshotIdstringThe snapshot the disk this one was taken of had been cloned from. A restore gives the workspace a new disk cloned from the snapshot restored, so the snapshots with one parent are one disk’s, and one whose parent is not ListSnapshotsResponse.base_snapshot_id was taken on a disk a restore left detached. Empty for a disk that was not cloned.

Access type for snapshots - SNAPSHOT_ACCESS_TYPE_OWNER: Owner of the source workspace - SNAPSHOT_ACCESS_TYPE_SHARED: Explicitly shared with user - SNAPSHOT_ACCESS_TYPE_PUBLIC: Public snapshot

One of: SNAPSHOT_ACCESS_TYPE_UNSPECIFIED, SNAPSHOT_ACCESS_TYPE_OWNER, SNAPSHOT_ACCESS_TYPE_SHARED, SNAPSHOT_ACCESS_TYPE_PUBLIC.

A share record for a snapshot

FieldTypeWhat it is
idstring
snapshotIdstring
userIdstring
userEmailstring
userNamestring
grantedAtTimestamp
grantedBystring

How far along a snapshot is. A snapshot is taken by the host serving the volume, so it exists before it is usable: CREATING is the window between asking for one and the host reporting the commit it published. - SNAPSHOT_STATE_CREATING: Requested; the host has not published a commit yet - SNAPSHOT_STATE_PUBLISHED: Usable: a workspace can be created from it

One of: SNAPSHOT_STATE_UNSPECIFIED, SNAPSHOT_STATE_CREATING, SNAPSHOT_STATE_PUBLISHED, SNAPSHOT_STATE_FAILED, SNAPSHOT_STATE_DELETING.

Span is one operation of a trace, as OpenTelemetry names its parts.

FieldTypeWhat it is
traceIdstring
spanIdstring
parentSpanIdstringEmpty for the trace’s first span.
servicestring
namestring
startTimestamp
durationMicrosstring (int64)How long it took, in microseconds.
failedbooleanWhether it ended in an error, and what it said.
statusMessagestring
attributesStruct
eventslist of StructWhat happened during it, as the span recorded it: each event’s name, time and attributes.

What the installation cost on its last billed day before the reading with nobody’s work counted: the platform, the runners’ capacity no workspace held, and the bucket’s bytes no workspace keeps. An estimate of a day nobody works: that day is over, the next may be charged otherwise, and a day people worked held some of the runners - so it is never said without its day (finops.StandbyOf).

FieldTypeWhat it is
dayTimestampThe billed day it is from: its first instant, UTC.
platformlist of RoleCostThe platform by role, costliest first.
idleMicrosstring (int64)
unstoredMicrosstring (int64)
FieldTypeWhat it is
kindStatusDisagreementKind
detailstringOne sentence naming both sides and the gap between them, for a person to read. The kind is what a script branches on.
  • STATUS_DISAGREEMENT_KIND_SUPERVISOR_STALE: The control plane says the workspace runs and the supervisor has gone quiet for longer than several heartbeat intervals. - STATUS_DISAGREEMENT_KIND_SUPERVISOR_ABSENT: The control plane says the workspace runs and no supervisor ever reported. - STATUS_DISAGREEMENT_KIND_HOST_UNREACHABLE: The host holding this workspace is not ACTIVE, or has stopped heartbeating. - STATUS_DISAGREEMENT_KIND_VOLUME_REFUSING: The volume under the workspace is refusing to serve. - STATUS_DISAGREEMENT_KIND_UNHEALTHY: The supervisor reports a failing health check.

One of: STATUS_DISAGREEMENT_KIND_UNSPECIFIED, STATUS_DISAGREEMENT_KIND_SUPERVISOR_STALE, STATUS_DISAGREEMENT_KIND_SUPERVISOR_ABSENT, STATUS_DISAGREEMENT_KIND_HOST_UNREACHABLE, STATUS_DISAGREEMENT_KIND_VOLUME_REFUSING, STATUS_DISAGREEMENT_KIND_UNHEALTHY.

StorageSettings is where the object store is: a bucket, or on one machine a directory.

FieldTypeWhat it is
bucketstring
endpointstringEmpty is the store’s own service for its region.
regionstring
accessKeyIdstringThe control plane’s own credential; empty is the machine’s own.
secretSetbooleanWhether the access key’s secret is set: the secret itself is never read back.
dirstring
principalstringWho the control plane issues each runner’s credential to the store as, as the store names it (for an S3 store, the role it assumes).
FieldTypeWhat it is
objectsstring (int64)
bytesstring (int64)

StoredVolume is one volume in the store: what is under volumes/<volume_id>/, and the layers its commits name under layers/.

FieldTypeWhat it is
volumeIdstring
kindStoredVolumeKind
namestringThe workspace’s name, the prebuild’s project, ref and commit, the image’s ref, or the extension and its version.
workspaceIdstringThe workspace’s, for a workspace’s disk and a prebuild.
ownerEmailstringThe workspace’s owner, or the person whose agent’s home it is.
currentbooleanWhether it is the workspace’s disk now, rather than one it had.
ownStorageTallyThe descriptor, HEAD, the epoch and the commit manifests.
layersStorageTally
checkpointsStorageTallyIts checkpoints’ memory and records.
removablebooleanWhether RemoveStoredVolume would take it: an image no ref names and nothing was cloned from, an extension release nothing runs, an unclaimed volume or an orphan.
untaggablebooleanAn image its ref still names, which UntagImage takes the ref off.
keptBecausestringWhy it stays, in words, where it is an image, a release or an agent’s home that may not go.
labelstringWhat it is and whose, in one line a person reads: “the prebuild of web main@1a2b3c4, ready”, “ana@example.com’s agent’s home, mounted by neat-crow”.
fromDescriptorbooleanThe database names nothing of it, and kind is what its descriptor.json said it was made as when the control plane made it: a volume whose rows were lost, or a database restored from behind the store. Removable as an orphan or an unclaimed volume is.
  • STORED_VOLUME_KIND_WORKSPACE: A workspace’s disk, now or before. - STORED_VOLUME_KIND_IMAGE: An image a workspace’s disk is cloned from. - STORED_VOLUME_KIND_EXTENSION: A release of an extension: the supervisor, the VS Code servers. - STORED_VOLUME_KIND_UNCLAIMED: A volume the database has and nothing names: a clone being made, or a delete not finished. - STORED_VOLUME_KIND_ORPHAN: Objects under a volume the database does not have. - STORED_VOLUME_KIND_PREBUILD: A prebuild: the disk of the workspace that built it, which the workspaces opened from it are cloned from. - STORED_VOLUME_KIND_AGENT_HOME: A person’s agent’s home, which outlives the workspaces that mount it.

One of: STORED_VOLUME_KIND_UNSPECIFIED, STORED_VOLUME_KIND_WORKSPACE, STORED_VOLUME_KIND_IMAGE, STORED_VOLUME_KIND_EXTENSION, STORED_VOLUME_KIND_UNCLAIMED, STORED_VOLUME_KIND_ORPHAN, STORED_VOLUME_KIND_PREBUILD, STORED_VOLUME_KIND_AGENT_HOME.

SupervisorState is what the supervisor inside a VM is doing. Here rather than beside the stream that carries it, because it is read from both sides: the supervisor reports it on its own connection (spin.agent.v1) and an operator asks for it through WorkspaceService.GetWorkspaceStatus. A vocabulary with two definitions is two vocabularies.

One of: SUPERVISOR_STATE_UNSPECIFIED, SUPERVISOR_STATE_INITIALIZING, SUPERVISOR_STATE_READY, SUPERVISOR_STATE_RUNNING_HOOK, SUPERVISOR_STATE_ERROR, SUPERVISOR_STATE_DISCONNECTED.

What the supervisor inside the guest last reported. Absent (connected false with a zero last_heartbeat) means no supervisor of this workspace has ever reached a control plane.

FieldTypeWhat it is
stateSupervisorState
versionstring
lastHeartbeatTimestamp
connectedbooleanWhether a control plane holds this supervisor’s stream right now. It is read from the durable row and not from the local connection table on purpose: a request may be served by a control plane other than the one the supervisor is attached to, and that one knows nothing about it.
healthHealthReport
FieldTypeWhat it is
idstring
parentIdstringEmpty if root team
namestring
slugstring
pathstringMaterialized path: “/engineering/backend”
depthinteger (int32)1, 2, or 3
descriptionstring
memberCountinteger (int32)Direct members only
workspaceCountinteger (int32)Direct workspaces only
createdAtTimestamp
updatedAtTimestamp
displayNamestringHuman-friendly name (falls back to name if empty)
isPersonalbooleanPersonal team for a single user (cannot be deleted or left by owner)
FieldTypeWhat it is
idstring
namestring
providerTypestringoidc, github, google, azure-ad
issuerUrlstring
autoJoinCelExpressionstringCEL expression for auto-membership
roleCelExpressionstringCEL expression for role assignment
enabledboolean
createdAtTimestamp
refusedRemovalstringWhy disabling or deleting it would be refused; empty where it would not be. An installation provider that the only administrators who can sign in sign in through (lockout).
FieldTypeWhat it is
userIdstring
emailstring
namestring
roleTeamRole
joinedAtTimestamp

Team member role enum - TEAM_ROLE_OWNER: Full control, can delete team - TEAM_ROLE_ADMIN: Can manage members and settings - TEAM_ROLE_MEMBER: Can create workspaces, view team resources

One of: TEAM_ROLE_UNSPECIFIED, TEAM_ROLE_OWNER, TEAM_ROLE_ADMIN, TEAM_ROLE_MEMBER.

FieldTypeWhat it is
namestring
updatedAtTimestamp
hostslist of string
refstringWhere the team keeps the value; empty where the control plane does.

What one of a team’s workspaces cost in the month.

FieldTypeWhat it is
workspaceIdstring
namestring
shareCostShare

TelemetryFlow is what one exporter of the collector did over the last window.

FieldTypeWhat it is
sentstring (int64)
failedstring (int64)

ThirdPartyAcceptance is an administrator’s acceptance of an item’s terms.

FieldTypeWhat it is
termsVersionstringThe version of the text that was accepted; an older one than the response’s counts as none.
acceptedBystringWho accepted, by email: kept as it was when they did.
acceptedAtTimestamp

ThirdPartyItem is what an administrator accepts the terms of, one download at a time: the software the control plane fetches together, as one extension. - THIRD_PARTY_ITEM_VSCODE_SERVER: Microsoft’s VS Code server and its CLI: the vsc-<commit> extensions. - THIRD_PARTY_ITEM_AGENT_CLIS: Claude Code, Codex, T3 Code and the libatomic T3 Code’s server is linked against: the agents extension.

One of: THIRD_PARTY_ITEM_UNSPECIFIED, THIRD_PARTY_ITEM_VSCODE_SERVER, THIRD_PARTY_ITEM_AGENT_CLIS.

ThirdPartyPart is one program an item downloads, and the license it comes under.

FieldTypeWhat it is
namestring
makerstringWho makes it and serves the download.
licensestring
licenseUrlstring
FieldTypeWhat it is
itemThirdPartyItem
namestring
purposestringWhat a workspace gets from it.
partslist of ThirdPartyPart
acceptanceThirdPartyAcceptanceUnset where nobody accepted the terms for it.
acceptedbooleanWhether this installation downloads it: accepted, as the current text.

TimelineActor is who or what did what a TimelineEvent says. - TIMELINE_ACTOR_PERSON: A person signed in, named by actor_id. - TIMELINE_ACTOR_CONTROL_PLANE: The control plane, on its own: a reconciliation, a sweep, a job, a decision nobody asked for. - TIMELINE_ACTOR_HOST: A host, of itself: it joined, said it was going, lost its stream or came back.

One of: TIMELINE_ACTOR_UNSPECIFIED, TIMELINE_ACTOR_PERSON, TIMELINE_ACTOR_CONTROL_PLANE, TIMELINE_ACTOR_HOST.

TimelineEvent is one thing that happened, read from the record that keeps it - the audit log, a workspace’s events, a job’s runs, a project’s prebuilds - and never a copy of it.

FieldTypeWhat it is
sourceTimelineSourceThe record it is read from, and that record’s id there: the evidence a reader opens.
idstring
atTimestamp
actorTimelineActorWho or what did it.
actorIdstringThe person, when actor is PERSON: empty for one whose account has since been deleted, and the email is what their row says now.
actorEmailstring
whatstringWhat happened, in its source’s own words: an audit action (host_state_changed), a workspace event type without its prefix (FAILED), a failed job run’s job (storage-gc), or for a prebuild prebuild_started, prebuild_built or prebuild_failed.
resourceTypestringWhat it happened to: an audit entry’s resource_type and id (workspace, host, settings, job by its name), the workspace of a workspace event, the job of a run, the project of a prebuild.
resourceIdstring
resourceNamestringThe name a person knows it by, where the installation still has its row: a workspace’s, a host’s machine’s, a team’s, a project’s. Empty otherwise.
detailsstringThe JSON the record keeps, verbatim: an audit entry’s details, a workspace event’s, a failed run’s counts and error, a prebuild’s ref, commit and error.
traceIdstringThe trace of the request or the run that did it; empty when none was sampled. Whether the store kept it is LogService.KeptTraces’s to say.

TimelineSource is the record a TimelineEvent is read from. - TIMELINE_SOURCE_AUDIT: An audit entry (AuditEntry.id). - TIMELINE_SOURCE_WORKSPACE_EVENT: A workspace’s event (WorkspaceEvent.id). - TIMELINE_SOURCE_JOB_RUN: A job’s run that failed (JobRun.run_id). - TIMELINE_SOURCE_PREBUILD: A project’s prebuild (Prebuild.id).

One of: TIMELINE_SOURCE_UNSPECIFIED, TIMELINE_SOURCE_AUDIT, TIMELINE_SOURCE_WORKSPACE_EVENT, TIMELINE_SOURCE_JOB_RUN, TIMELINE_SOURCE_PREBUILD.

FieldTypeWhat it is
idstring
emailstring
namestring
avatarUrlstring
subscriptionTierstring
createdAtTimestamp
isInstanceAdminboolean
disabledboolean
disabledReasonstring
lastLoginAtTimestampWhen they last signed in, by any route; unset for one who never has.
FieldTypeWhat it is
apiKeysinteger (int32)API keys not yet expired.
teamsinteger (int32)
FieldTypeWhat it is
dotfilesDotfilesConfig
startupTaskfilestringInline Taskfile YAML
defaultShellstringe.g., /bin/bash, /bin/zsh
editorSettingsmap of string to stringIDE preferences
defaultEnvmap of string to stringEnvironment variables
updatedAtTimestamp

VSCodeServerPublish is this control plane’s publish: the last one, or the one under way.

FieldTypeWhat it is
stateVSCodeServerPublishState
stepstringWhich part is running, while it works.
detailstringWhy it failed.
versionstringWhat it released, once it has.
updatedAtTimestamp
  • VS_CODE_SERVER_PUBLISH_STATE_IDLE: Nothing published since this control plane started.

One of: VS_CODE_SERVER_PUBLISH_STATE_UNSPECIFIED, VS_CODE_SERVER_PUBLISH_STATE_IDLE, VS_CODE_SERVER_PUBLISH_STATE_WORKING, VS_CODE_SERVER_PUBLISH_STATE_PUBLISHED, VS_CODE_SERVER_PUBLISH_STATE_FAILED.

VolumeRekey is a workspace’s disk to re-key or being re-keyed.

FieldTypeWhat it is
volumeIdstring
workspaceIdstring
workspaceNamestring
stateRekeyState
hostIdstringThe host copying it, empty while pending.
reasonstring
FieldTypeWhat it is
idstring
namestring
teamIdstringEvery workspace has one: its owner’s personal team unless another was named
hostIdstring
imagestringContainer image used for this workspace
resourcesResources
stateWorkspaceState
urlstringOutput only: https://{name}.{base domain}; empty until setup records a domain
envmap of string to string
createdAtTimestamp
updatedAtTimestamp
snapshotCountinteger (int32)Number of snapshots in history
failureReasonstringReason for failure (only set when state=FAILED)
networkTagslist of stringThe network policies this workspace runs under, by name. Read back because what a workspace may reach is worth seeing without asking the host that enforces it.
hostConnectedbooleanhost_connected says the host this workspace is on is talking to the control plane now. A workspace’s state is its host’s last word, and a host that stops talking stops correcting it: RUNNING is not transitional, so nothing fails it and nothing moves it, and a workspace whose machine died with its host reads as healthy for ever. The honest answer is not a different state - a host that cannot be reached may be running the machine perfectly well behind a broken network - but to say that the state is old and why. False for a workspace with no host at all (a stopped one), so read it beside the state.
waitingReasonstringwaiting_reason is why a WAITING workspace has no host yet, as of the last attempt to place it: which runner was full of what, or that none is connected. Empty in every other state.
failureWorkspaceFailurefailure is which part failed when state=FAILED, UNSPECIFIED in every other state: what a client says a person can do is decided by it, and failure_reason is the detail.
networkWatchbooleannetwork_watch says its host records where it connects into its logs (SetWorkspaceNetworkWatch).
floorCpuCoresinteger (int32)What its preset started it at. resources.cpu_cores and memory_mb are what it holds now, and above these they are a grant (GrantWorkspaceResources).
floorMemoryMbinteger (int32)
grantExpiresAtTimestampWhen its grant is given back on its own; unset for one kept until it is given back, and for a workspace holding none.
quarantineHeldbooleanquarantine_held says a quarantine holds it: in force (state QUARANTINED), or asked for and its stop still on the way or ended FAILED. Until an administrator releases it, its own person cannot start, move or delete it, whatever the state says.
progressWorkspaceProgressprogress is where a transition is while one is under way - CREATING, STARTING, STOPPING, WAITING - and unset at rest: which attempt, why the one before failed, what the host is doing now, since when and until when before the control plane gives up on it.
allowedActionslist of WorkspaceActionallowed_actions are what the server takes from this workspace as it is: its state, a quarantine’s hold, and the failure it ended in. A client offers these and no others.
failureSummarystringfailure_summary says in a sentence what failed when state=FAILED, decided by failure: what a client shows above failure_reason, so the dashboard and the CLI say the same thing. What to do next is each client’s, from allowed_actions.
readyAtTimestampready_at is when the workspace’s supervisor answered for its current run: the workspace is usable, not only its machine handed off. Unset before, and while it is not running.
traceIdstringtrace_id is the trace of the request that asked for its current generation, which runs through the host’s operation and the state it reported. Empty when that request was not sampled.
durabilityWorkspaceDurabilitydurability is how much of its disk is in the object store, in every state - running, stopped or suspended. Answered by GetWorkspace only, and only for a workspace with a volume: a listing does not ask every volume.
rolestringrole is the caller’s in it: “owner”, or “guest” - who may connect, see it and open its ports, and nothing that changes it.
checkoutPathstringcheckout_path is where the workspace’s project is checked out (projects.CheckoutPath), empty for a workspace that opened none: where its agent works unless told otherwise. GetWorkspace alone says it.
memoryMachineGonebooleanmemory_machine_gone says it is suspended with memory taken on a machine no host of the installation registers now (WORKSPACE_FAILURE_MACHINE_CHANGED): a start cannot resume it, and WORKSPACE_ACTION_START_FROM_DISK, which drops the memory, is what is offered instead.
suspendsAtTimestampThe question before a suspension: when the installation suspends it unless somebody keeps it (KeepWorkspace), asked ten minutes ahead, and which of the two suspensions is due (WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED or WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED). Unset while none is due within the warning: somebody used it since, or it is kept.
suspendsForWorkspaceEventType
keptUntilTimestampAn answer: kept awake until then, and neither suspension fires before it.
leaseslist of WorkspaceLeaseThe leases its processes hold, as its supervisor last reported them: while one is held and within the installation’s workspace_lease_max_minutes of its start, nobody is asked, nothing idle is suspended, and the running cap waits for the lease’s end.
projectIdstringThe project it opened and the ref it was opened at; empty for a workspace that opened none.
refstring
wakeOnAccessbooleanSuspended, it is resumed by a signed-in visitor of one of its published ports (OpenWorkspaceProxySession). Never by an anonymous one: that would undo the idle suspension for whoever has a public port’s URL.
suspendedSnapshotIdstringThe snapshot it was suspended into: its next start resumes it rather than booting its disk. Empty when a start boots the disk - never suspended, resumed since, or the snapshot deleted.
fromPrebuildIdstringThe prebuild its disk is a clone of; empty for one that opened with none.
agentMinMemoryMbinteger (int32)What it has to hold for its agent to start there, in MB (the supervisor refuses below it).
projectErrorstringproject_error is what its guest last said went wrong with its project - the clone, its .spin.yaml or its create tasks - as the guest said it; empty when all of it went, or nothing has reported. The next boot tries again. A running workspace with one is DEGRADED.
ownerIdstringWhose it is: on a team’s workspace, which member’s. owner_id is in every answer; the name and email are answered by GetWorkspace and ListWorkspaces, whose callers - its owner and the guests its owner let in - are who may see it at all.
ownerNamestring
ownerEmailstring
hostClassstringhost_class is the host class it runs on (HostClass.name), from its preset: placed only on a host of it, “default” where its preset named none.
attemptslist of WorkspaceAttemptattempts are the attempts its host failed at its current generation, oldest first: each one the host retried, and the last when the host ended the generation FAILED. Kept once it settles - FAILED says which attempt it was and what the ones before it hit - and gone with the next start, which is a new generation. An attempt whose report never reached the control plane is not here: the host reports why the attempt before failed, and a lost report is replaced by the next.
projectReportedAtTimestampproject_reported_at is when its guest said how its project went in this run, unset until it has: an empty project_error before then is a clone still going, not one that went. project_head is the commit it checked out, as the guest said it; empty when it did not say one.
projectHeadstring
hostNamestringhost_name is the name host_id’s machine registered, for a person to tell hosts apart; empty with no host, or one that registered none. Answered by GetWorkspace and ListWorkspaces, so a list row says where each runs without a status read per row; never placed or trusted by.
withoutPrebuildstringwithout_prebuild is why a workspace opening a project at a ref it prebuilds started from none of its prebuilds, and cloned the repository at its first boot: none ready, the ready one of another image, its disk not cloneable yet. Empty with from_prebuild_id set, or for a project that prebuilds nothing.

WorkspaceAction is an act a person can ask of a workspace. - WORKSPACE_ACTION_FORCE_STOP: Stop without waiting for the guest: also what ends a stop that does not finish. - WORKSPACE_ACTION_SUSPEND: Put down with its memory, to be resumed where it was. - WORKSPACE_ACTION_START_FROM_DISK: Boot a suspended workspace from its disk, dropping its memory (StartWorkspaceRequest.from_disk): offered when that memory’s machine is run by no host (Workspace.memory_machine_gone).

One of: WORKSPACE_ACTION_UNSPECIFIED, WORKSPACE_ACTION_START, WORKSPACE_ACTION_STOP, WORKSPACE_ACTION_FORCE_STOP, WORKSPACE_ACTION_DELETE, WORKSPACE_ACTION_FORCE_DELETE, WORKSPACE_ACTION_SUSPEND, WORKSPACE_ACTION_START_FROM_DISK.

WorkspaceAgentThreads is one workspace’s chats with what a rail names it by: the workspace, its state, and the project it opened.

FieldTypeWhat it is
workspaceIdstring
workspaceNamestring
stateWorkspaceState
projectIdstringEmpty for a workspace that opened no project.
projectNamestring
environmentIdstringAs ListAgentThreadsResponse.environment_id: the first part of a thread’s page.
threadslist of AgentThreadNewest first.

WorkspaceAttempt is one attempt a host made at a workspace’s generation that failed.

FieldTypeWhat it is
attemptinteger (int32)attempt is its number, from 1, of the host’s attempts at the generation (WorkspaceProgress .attempts is how many it makes); zero where the host never said which it was on.
failureWorkspaceFailureWhich part failed, and the host’s words for why.
reasonstring
failedAtTimestampfailed_at is when the control plane heard that it failed.

What one workspace cost in the month, in millionths of the bill’s currency, and whose it was on the last day it cost anything.

FieldTypeWhat it is
workspaceIdstring
namestring
teamIdstring
teamNamestringEmpty where the team was deleted since.
ownerIdstring
ownerEmailstringEmpty where the owner was deleted since.
computeMicrosstring (int64)Its share of the runners: what it held of them.
storageMicrosstring (int64)Its share of the volumes’ bucket: what its volumes kept.
sentBytesstring (int64)What its traffic came to in the month: its machine’s network out and back, and its sessions - ssh, the editor, forwarded ports - through the relay, both ways. Counted, not yet costed.
receivedBytesstring (int64)
forwardedBytesstring (int64)

WorkspaceDeparture is one workspace on a host and what each way of taking the host out does to it.

FieldTypeWhat it is
workspaceIdstring
workspaceNamestring
ownerEmailstring
stateWorkspaceState
drainDepartureFateWhat a drain that moves the host’s workspaces (DrainHostRequest.suspend) does to it: MOVES or STAYS.
removalDepartureFateWhat Host.removal does to it: LOSES_PLACE or HOLDS. UNSPECIFIED where the host has no removal.
takenDepartureFateWhat removing the host as taken (RemoveHostRequest.taken) does to it: LOSES_PLACE or STOPS. UNSPECIFIED for a host that is revoked, whose revoke already is that.

WorkspaceDurability is what of a workspace’s disk is published, so it survives its host. While a host serves the disk - running, or stopped with its disk kept there - it is that host’s last report; once none does - suspended, or its disk handed back to the store - it is the newest published snapshot of the disk (snapshot_id), which is what a start boots from.

FieldTypeWhat it is
lastPublishedAtTimestamplast_published_at is when its last commit reached the object store, as its host last said; from a snapshot, when that snapshot was taken.
unpublishedSecondsstring (int64)What is written and not yet published, as of the host’s report plus the time since.
unpublishedBytesstring (int64)
stalledbooleanstalled says publishing has not kept up with the bound it runs to (the volume’s RPO).
reportedAtTimestampreported_at is the host’s report these are as of; unset when they are a snapshot’s.
snapshotIdstringsnapshot_id is the published snapshot the last copy is, when no host serves the disk, and published_bytes how much of the disk it holds. Empty and zero while they are a host’s report.
publishedBytesstring (int64)

Timeline event for workspace state changes

FieldTypeWhat it is
idstring
workspaceIdstring
typeWorkspaceEventType
timestampTimestamp
detailsstringAdditional info (JSON)
  • WORKSPACE_EVENT_TYPE_CREATED: Workspace was created - WORKSPACE_EVENT_TYPE_STARTED: Workspace was started - WORKSPACE_EVENT_TYPE_STOPPED: Workspace was stopped; its disk is kept, and no snapshot is taken - WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED: Manual snapshot - WORKSPACE_EVENT_TYPE_DELETED: Workspace was deleted - WORKSPACE_EVENT_TYPE_FAILED: Workspace start failed - WORKSPACE_EVENT_TYPE_RESTORED: Its disk was put back to a snapshot - WORKSPACE_EVENT_TYPE_RESUMED: It went on from a snapshot’s memory - WORKSPACE_EVENT_TYPE_BOOTED: Suspended, its memory could not be resumed, and its disk was booted - WORKSPACE_EVENT_TYPE_QUARANTINED: An administrator held it: stopped, and startable by nobody until released - WORKSPACE_EVENT_TYPE_UNQUARANTINED: The hold was released: back to stopped, where it was held from - WORKSPACE_EVENT_TYPE_PLACED: A workspace that waited for a host was given one, and its disk there - WORKSPACE_EVENT_TYPE_TRASHED: Deleted into the trash: its disk kept, its owner able to undelete it - WORKSPACE_EVENT_TYPE_UNDELETED: Taken back out of the trash - WORKSPACE_EVENT_TYPE_MOVED: Suspended on its host and resumed on another, which had room for what it was granted - WORKSPACE_EVENT_TYPE_DISPLACED: Its host was drained or went away: suspended there, it is resumed on another on its own - WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED: A stop on a host that can be taken away could not publish its disk first, so it runs on - WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED: Nobody used it for as long as the installation allows: suspended with its processes, a start resumes them - WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED: It ran at a stretch for as long as the installation allows: suspended with its processes, a start resumes them - WORKSPACE_EVENT_TYPE_SUSPENSION_DUE: A suspension is minutes away and the question was asked: its terminals, its page, the CLI; a keep answers it - WORKSPACE_EVENT_TYPE_KEPT: Somebody kept it awake until a time: no suspension before it - WORKSPACE_EVENT_TYPE_UNRESPONSIVE: Its supervisor said nothing for longer than the control plane waits: stopped by force, and a start brings it back - WORKSPACE_EVENT_TYPE_REHOMED: Its host stopped answering and it was moved to another on its own, giving up what that host had not published - WORKSPACE_EVENT_TYPE_HELD: Its host stopped answering and moving it would give up more than the installation does on its own: it waits for its owner - WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN: An administrator moved it off a host that is gone, giving up for its owner what that host had not published; its details say who and why - WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY: It ran out of memory: its guest’s kernel killed a process (cause “guest”, with the kills and their victims), its host found it short at its ceiling for a while (cause “ceiling”), or its host killed the machine (cause “host”). Its details say what it held, its grant and its ceiling. Said, never acted on: nothing resizes a workspace on its own. - WORKSPACE_EVENT_TYPE_OVERSIZED: It held far more than it used for a week: the most memory its processes used stayed under half its own, and a smaller preset would fit what it used. Its details say what it used, what it holds, and that preset. Said, never acted on: nothing resizes a workspace on its own.

One of: WORKSPACE_EVENT_TYPE_UNSPECIFIED, WORKSPACE_EVENT_TYPE_CREATED, WORKSPACE_EVENT_TYPE_STARTED, WORKSPACE_EVENT_TYPE_STOPPED, WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED, WORKSPACE_EVENT_TYPE_DELETED, WORKSPACE_EVENT_TYPE_FAILED, WORKSPACE_EVENT_TYPE_RESTORED, WORKSPACE_EVENT_TYPE_RESUMED, WORKSPACE_EVENT_TYPE_BOOTED, WORKSPACE_EVENT_TYPE_QUARANTINED, WORKSPACE_EVENT_TYPE_UNQUARANTINED, WORKSPACE_EVENT_TYPE_PLACED, WORKSPACE_EVENT_TYPE_TRASHED, WORKSPACE_EVENT_TYPE_UNDELETED, WORKSPACE_EVENT_TYPE_MOVED, WORKSPACE_EVENT_TYPE_DISPLACED, WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED, WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED, WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED, WORKSPACE_EVENT_TYPE_SUSPENSION_DUE, WORKSPACE_EVENT_TYPE_KEPT, WORKSPACE_EVENT_TYPE_UNRESPONSIVE, WORKSPACE_EVENT_TYPE_REHOMED, WORKSPACE_EVENT_TYPE_HELD, WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN, WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY, WORKSPACE_EVENT_TYPE_OVERSIZED.

WorkspaceFailure is why a FAILED workspace failed: which part of its run, closed so what a person can do about it - and a failure rate split by the repair it needs - is decided by the kind rather than by the text of an error. The reason beside it is the detail. One enum for the client and the host’s report (spin.agent.v1.ObservedWorkspace): the kind a person is shown is the one the host named, with no second list to keep in step. - WORKSPACE_FAILURE_UNSPECIFIED: Not classified. A failure that lands here is a site missing its classification. - WORKSPACE_FAILURE_VOLUME: Its disk could not be served or made: the host is not serving its volume (its refusal says why), or what the disk was to be made from is gone. - WORKSPACE_FAILURE_EXTENSION: An extension could not be attached, or the releases it starts with could not be named. - WORKSPACE_FAILURE_NETWORK: The machine’s network namespace or its tags could not be set up. - WORKSPACE_FAILURE_RESOURCES: The machine could not be given the cores or memory it was asked for. - WORKSPACE_FAILURE_MACHINE: QEMU could not be prepared or did not boot. - WORKSPACE_FAILURE_GUEST: The guest booted and did not take its identity or its own filesystem. - WORKSPACE_FAILURE_RELEASE_GONE: A resume needs an extension release that is no longer in the object store: the memory cannot be resumed anywhere, and the control plane boots the disk with the newest releases. - WORKSPACE_FAILURE_EXITED: The machine ended without being asked to, and not by a panic of its guest’s kernel: its guest reset it, or its QEMU was killed, exited with an error or crashed. The detail says which. - WORKSPACE_FAILURE_STOP: The machine could not be stopped or removed. - WORKSPACE_FAILURE_TIMED_OUT: Its host did not bring a start or a stop to an end before the deadline: unreachable, or its attempts outlasted it. The control plane’s verdict (the stuck sweep), never a host’s. - WORKSPACE_FAILURE_NO_HOST: No host could take it: none came with room while it waited, or its disk is only on a host that is not connected. The control plane’s verdict, never a host’s. - WORKSPACE_FAILURE_MACHINE_CHANGED: Its memory was taken on a machine no host of the installation runs now: the machine’s contract moved (a release that changed it), or the processor did. The memory resumes nowhere; the workspace stays suspended, and booting it from its disk, which drops the memory, is its owner’s to choose (StartWorkspaceRequest.from_disk). - WORKSPACE_FAILURE_GUEST_PANIC: The guest’s kernel panicked, which ended its machine. The cause is inside the guest: the detail quotes the console’s panic line, and the console has what led to it.

One of: WORKSPACE_FAILURE_UNSPECIFIED, WORKSPACE_FAILURE_VOLUME, WORKSPACE_FAILURE_EXTENSION, WORKSPACE_FAILURE_NETWORK, WORKSPACE_FAILURE_RESOURCES, WORKSPACE_FAILURE_MACHINE, WORKSPACE_FAILURE_GUEST, WORKSPACE_FAILURE_RELEASE_GONE, WORKSPACE_FAILURE_EXITED, WORKSPACE_FAILURE_STOP, WORKSPACE_FAILURE_TIMED_OUT, WORKSPACE_FAILURE_NO_HOST, WORKSPACE_FAILURE_MACHINE_CHANGED, WORKSPACE_FAILURE_GUEST_PANIC.

FieldTypeWhat it is
userIdstring
emailstring
namestring
invitedAtTimestamp

Whether the machine’s host is reachable at all. A workspace cannot be healthier than the host under it, and “my workspace is broken” is most often this.

FieldTypeWhat it is
hostIdstring
stateHostState
lastHeartbeatTimestamp
hostnamestringWhich host it is, as a person reads it: the name its machine goes by (Host.hostname), and the class of the group that launched it (“default” for one no group launched). What its owner and guests are shown of the host and no more: its capacity, what else it runs and its policy are an administrator’s (HostService).
hostClassstring
machineTypestringThe host’s machine as its cloud names it, said when the host joined (Host.machine_type, Host.zone): what kind of machine the workspace runs on, and where. Empty for a host that joined with no cloud. The machine’s id and whether it may be taken back stay an administrator’s.
zonestring

WorkspaceLease is a process in the workspace keeping it awake while it lives.

FieldTypeWhat it is
namestringname is the command, or the .spin.yaml task, that holds it.
sinceTimestamp
untilTimestampuntil is when the lease stops counting whether or not the process lives: since plus the installation’s workspace_lease_max_minutes.

WorkspaceNetworkStatus is one policy a workspace runs under, and whether it holds there: the installation declares it, and the workspace’s host reports having installed it. A tag no policy is declared for, or one its host has not installed, is what a start is refused over.

FieldTypeWhat it is
policystring
declaredbooleandeclared says a policy of this name exists: the installation’s, or a team’s.
installedbooleaninstalled says the workspace’s host last reported enforcing a policy of this name. False for a workspace on no host.

WorkspacePhase is what a host is doing to bring a workspace up. - WORKSPACE_PHASE_DISK: Waiting for its disk to be served on the host. - WORKSPACE_PHASE_EXTENSIONS: Holding the extension releases it runs with. - WORKSPACE_PHASE_NETWORK: Setting up its network. - WORKSPACE_PHASE_MACHINE: Booting its machine, or resuming it from a checkpoint. - WORKSPACE_PHASE_FIRST_BOOT: Its first boot of a disk another person’s workspace was cloned from. - WORKSPACE_PHASE_GUEST: The machine is up and its workspace inside is starting. - WORKSPACE_PHASE_BACKUP: Stopping on a host that can be taken away: its disk is being published before the machine stops, the control plane’s doing rather than the host’s, and retried if it restarts.

One of: WORKSPACE_PHASE_UNSPECIFIED, WORKSPACE_PHASE_DISK, WORKSPACE_PHASE_EXTENSIONS, WORKSPACE_PHASE_NETWORK, WORKSPACE_PHASE_MACHINE, WORKSPACE_PHASE_FIRST_BOOT, WORKSPACE_PHASE_GUEST, WORKSPACE_PHASE_BACKUP.

WorkspaceProgress is a transition under way.

FieldTypeWhat it is
attemptinteger (int32)attempt is the host’s attempt at the current generation, from 1, and attempts how many it makes before the workspace fails. Zero before the host has made one.
attemptsinteger (int32)
lastFailureWorkspaceFailureWhy the attempt before this one failed, while this one is in progress: what a retry hides.
lastReasonstring
phaseWorkspacePhasephase is what the host is doing now; UNSPECIFIED when it has not said.
sinceTimestampsince is when the transition began, and deadline when the control plane gives up on it - a wait for a host, or a start or a stop the host does not finish - and fails the workspace.
deadlineTimestamp
typicalDurationtypical is how long a start usually takes on the workspace’s host class: the median, from the request to RUNNING (the same measure as since), of the newest starts that came up there. Unset for a transition that is not a start, and where too few have come up to say. Per step it is not: what a host says of its phases is kept only while one is under way.

Proxy status for workspace access - WORKSPACE_PROXY_STATUS_ACCESSIBLE: Port exposed, workspace running - WORKSPACE_PROXY_STATUS_NOT_RUNNING: Return 503 - WORKSPACE_PROXY_STATUS_NOT_FOUND: Return 404 - WORKSPACE_PROXY_STATUS_PORT_NOT_EXPOSED: Return 403 - WORKSPACE_PROXY_STATUS_WAKING: Not running, and woken for this caller (Workspace.wake_on_access): the proxy opens a session, which resumes it and waits a while, and shows a page that asks again while it is not up.

One of: WORKSPACE_PROXY_STATUS_UNSPECIFIED, WORKSPACE_PROXY_STATUS_ACCESSIBLE, WORKSPACE_PROXY_STATUS_NOT_RUNNING, WORKSPACE_PROXY_STATUS_NOT_FOUND, WORKSPACE_PROXY_STATUS_PORT_NOT_EXPOSED, WORKSPACE_PROXY_STATUS_WAKING.

WorkspaceRuntime is a running workspace’s machine as its host measures it from outside the guest. Answers “is my workspace out of memory” and “did it get the cores it borrowed” for the one person asking, which no metric may: those are labelled by host, never by workspace.

FieldTypeWhat it is
cpuCoresinteger (int32)
memoryBytesstring (int64)
memoryUsedBytesstring (int64)
cpuSecondsnumber (double)
machineStartedAtTimestamp

WorkspaceState is where a workspace is in its life. Each value’s comment is what the API’s document says of it (buf.gen.openapi.yaml’s with-enum-value-descriptions), and the website’s table of states is generated from it: it is written for a person reading that table, in the site’s words (a runner, the CLI’s commands). Why a value is what it is goes in a comment apart, above the value’s own, which the document does not carry. - WORKSPACE_STATE_UNSPECIFIED: Never a workspace’s state: a client that reads it read a field nothing set. - WORKSPACE_STATE_CREATING: The workspace exists and has not run yet. - WORKSPACE_STATE_STARTING: A runner is preparing its disk and starting its machine. - WORKSPACE_STATE_RUNNING: Its machine is up. - WORKSPACE_STATE_STOPPING: Its machine is shutting down, and then what its disk wrote since its last commit is uploaded to the bucket. A stop stays here until the upload is done, and says why it is not; spin workspace stop --force does not wait for it. - WORKSPACE_STATE_STOPPED: Not running. Its disk is kept, and the next start boots from it. - WORKSPACE_STATE_FAILED: A start or a stop failed: spin workspace status says which part, and why. It stays so until it is started again. - WORKSPACE_STATE_DELETED: In the trash, with its disk, for the days the installation keeps it there (workspace_trash_days): spin workspace undelete brings it back, stopped. An installation that keeps no trash erases it at once. - WORKSPACE_STATE_WAITING: Wanted running, and no runner has room for it yet. On AWS, where runners scale to none, one is being started, and the workspace starts on it once it is up. - WORKSPACE_STATE_QUARANTINED: Held by an administrator with spin workspace quarantine: it cannot start until spin workspace unquarantine releases it, and its disk is kept as it was. - WORKSPACE_STATE_DEGRADED: Its machine is up, and what was asked of it inside did not finish: its project’s checkout, .spin.yaml or create tasks. Everything a running workspace allows is allowed; spin workspace get says what failed, and the next boot tries again.

One of: WORKSPACE_STATE_UNSPECIFIED, WORKSPACE_STATE_CREATING, WORKSPACE_STATE_STARTING, WORKSPACE_STATE_RUNNING, WORKSPACE_STATE_STOPPING, WORKSPACE_STATE_STOPPED, WORKSPACE_STATE_FAILED, WORKSPACE_STATE_DELETED, WORKSPACE_STATE_WAITING, WORKSPACE_STATE_QUARANTINED, WORKSPACE_STATE_DEGRADED.

FieldTypeWhat it is
workspaceIdstring
errorstring

Whether the disk under the workspace is being served. refusal is the token an alert keys on; refusal_detail is the sentence the agent sent with it.

FieldTypeWhat it is
volumeIdstring
statestring
refusalstring
refusalDetailstring

WritebackPreset is a pair of writeback thresholds measured on a Spin OS metal host (NVMe, a 4 KiB write+fsync in one workspace beside another writing 2 GiB flat out).

FieldTypeWhat it is
namestringname is how the preset is told apart; label is how a person is shown it.
labelstring
limitBytesstring (int64)Both zero is unset.
backgroundBytesstring (int64)
measuredstringmeasured is what it did, in words.

WritebackRun mirrors spin.agent.v1.WritebackRun, which is what the host reports.

FieldTypeWhat it is
writerBytesPerSecondstring (int64)
probeP50Usstring (int64)
probeP99Usstring (int64)
probeMaxUsstring (int64)
probesinteger (int32)

WritebackTest is one TestHostWriteback: the thresholds tested, both runs, and until when SetHostPolicy takes those thresholds for that host on the strength of it.

FieldTypeWhat it is
hostIdstring
limitBytesstring (int64)
backgroundBytesstring (int64)
candidateWritebackRuncandidate ran under the thresholds above, current under the ones the host held.
currentWritebackRun
testedAtTimestamp
expiresAtTimestamp

Generated by task reference from spin/internal/controlplane/apidocs/spin.v1.openapi.json at 51f7e0dea.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.