Types
APIKey
Section titled “APIKey”| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
prefix | string | First 8 chars for identification |
scopes | list of string | |
createdAt | Timestamp | |
expiresAt | Timestamp | |
lastUsedAt | Timestamp | |
parentId | string | The key it was delegated from, and how far down the chain (0: made by its person). |
depth | integer (int32) | |
teamId | string | The one team it reaches; empty for every team its person is in. Of that team, the projects it reaches; empty for any. |
projectIds | list of string | |
maxWorkspaces | integer 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. |
maxCores | integer or null (int32) |
AffectedWorkspace
Section titled “AffectedWorkspace”| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
state | WorkspaceState |
AgentThread
Section titled “AgentThread”AgentThread is one of the agent’s threads as T3 Code names it: what a person is shown of a chat without opening it.
| Field | Type | What it is |
|---|---|---|
id | string | |
title | string | |
project | string | project is the directory the thread works in. |
model | string | |
updatedAt | Timestamp | |
archived | boolean |
AgentVolume
Section titled “AgentVolume”AgentVolume is one agent home of the caller’s.
| Field | Type | What it is |
|---|---|---|
id | string | |
sizeBytes | string (int64) | |
createdAt | Timestamp | |
workspaceId | string | The workspace mounting it, or empty for one no workspace mounts - which a new workspace may. |
workspaceName | string | The 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.
| Field | Type | What it is |
|---|---|---|
id | string | The installation event’s id. |
event | InstallationEventType | |
name | string | The rule’s title (Grafana’s alertname). |
summary | string | The rule’s summary, rendered for what fired; empty where it has none. |
description | string | |
severity | string | critical, warning; empty where the rule says none. |
runbookUrl | string | Where the dashboard’s runbook for it is, as the rule names it: /admin/runbooks/<id>. |
labels | map of string to string | What else the alert’s series is labelled with: which host, which volume. |
startsAt | Timestamp | When it began firing, and for a resolution when it stopped. |
endsAt | Timestamp | |
createdAt | Timestamp | When the control plane heard it. |
sent | integer (int32) | How many administrators it was emailed to, is waiting for, and failed every attempt for. |
pending | integer (int32) | |
failed | integer (int32) |
AllowedEmail
Section titled “AllowedEmail”Allowed email/domain entry
| Field | Type | What it is |
|---|---|---|
id | string | |
pattern | string | Email address or domain |
type | AllowedEmailType | |
description | string | Optional description |
createdAt | Timestamp |
AllowedEmailType
Section titled “AllowedEmailType”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
Section titled “AuditEntry”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.
| Field | Type | What it is |
|---|---|---|
id | string | |
actorId | string | actor_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. |
actorEmail | string | actor_email is empty for the same reasons, and is what the user’s row says now rather than what it said then. |
action | string | |
resourceType | string | |
resourceId | string | resource_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. |
details | string | details 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. |
ipAddress | string | |
createdAt | Timestamp |
BaseImage
Section titled “BaseImage”BaseImage is the base image of one machine release, as published.
| Field | Type | What it is |
|---|---|---|
ref | string | |
version | string | The machine release it was taken from. |
publishedAt | Timestamp | |
clones | string (int64) | How many volumes were cloned from it: every workspace disk that began as it, and still is. |
untagged | boolean | Its ref was taken off it: no new workspace gets it, the disks cloned from it go on reading it. |
given | boolean | What a workspace that names no image is given now. |
pinned | boolean | The one this control plane’s release pins; given once it is published. |
volumeId | string | Its volume in the store, which RemoveStoredVolume takes when removable. |
removable | boolean | No disk was cloned from it and it is not the one given: RemoveStoredVolume untags it on the way and removes it. |
keptBecause | string | Why it stays, in words, where it may not go. |
BillDay
Section titled “BillDay”| Field | Type | What it is |
|---|---|---|
day | Timestamp | The day’s first instant, UTC. |
services | list of ServiceCost | Costliest first. |
BrokeredRequest
Section titled “BrokeredRequest”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.
| Field | Type | What it is |
|---|---|---|
name | string | |
method | string | |
path | string | As the machine sent it, without the query. |
status | integer (int32) | What the real host answered; what the proxy answered for a refusal. |
bytesSent | string (int64) | |
bytesReceived | string (int64) | |
at | Timestamp | |
refused | string | Empty 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). |
principal | string | Who asked: “user” or “agent”, by the listener the proxy read it on. |
BurstMode
Section titled “BurstMode”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
Section titled “CloudAccess”CloudAccess is a principal on a cloud a brokered rule’s requests are authorized as.
| Field | Type | What it is |
|---|---|---|
cloud | string | The cloud: “aws”, whose principal is an IAM role’s ARN and whose requests are signed with SigV4. |
principal | string |
ConfigChange
Section titled “ConfigChange”One thing the config file says differently from the installation.
| Field | Type | What it is |
|---|---|---|
kind | ConfigItemKind | |
name | string | |
fileSays | string | What the file says, as a person reads it; empty where the file no longer declares the item, and applying the change removes it. |
installationHas | string | What the installation has, the same way; empty where it has none. |
says | string | The 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. |
since | Timestamp | When the file started saying it. |
ConfigItemKind
Section titled “ConfigItemKind”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.
CostEstimate
Section titled “CostEstimate”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.
| Field | Type | What it is |
|---|---|---|
day | Timestamp | The billed day the rate is from: its first instant, UTC. |
runningHourMicros | string or null (int64) | An hour of its machine running, for the cores and memory it holds; unset where that day billed no runner. |
stoppedMonthMicros | string 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. |
CostMonth
Section titled “CostMonth”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.
| Field | Type | What it is |
|---|---|---|
month | Timestamp | Its first instant, UTC. |
readAt | Timestamp | The reading its costs are from. |
currency | string | ISO 4217. |
totalMicros | string (int64) | Every cost of its days; idle and unstored are parts of it. |
idleMicros | string (int64) | What the runners cost that no workspace held. |
unstoredMicros | string (int64) | What the volumes’ bucket cost for bytes no workspace keeps. |
budgetLimitMicros | string or null (int64) | The installation’s budget as the month’s last reading in it said; unset where it had none. |
CostShare
Section titled “CostShare”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.
| Field | Type | What it is |
|---|---|---|
computeMicros | string (int64) | Of the runners: what was held of them. |
storageMicros | string (int64) | Of the volumes’ bucket: what the volumes kept. |
sentBytes | string (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. |
receivedBytes | string (int64) | |
forwardedBytes | string (int64) |
CpuUsagePoint
Section titled “CpuUsagePoint”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.
| Field | Type | What it is |
|---|---|---|
start | Timestamp | |
usedCores | number (double) | |
heldCores | integer (int32) | |
cpuCores | integer (int32) | |
maxCpuCores | integer (int32) |
DeletedWorkspace
Section titled “DeletedWorkspace”DeletedWorkspace is a workspace in the trash.
| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | The name it had; another workspace may have taken it since, and an undelete then gives it another. |
deletedAt | Timestamp | |
trashedUntil | Timestamp | |
agentVolumeId | string | The agent’s home it mounts, which its erase keeps for another workspace (ListAgentVolumes); empty for a workspace with none. |
DeletionEffect
Section titled “DeletionEffect”DeletionEffect is one thing a workspace has and what a delete does to it, in words its owner reads before confirming.
| Field | Type | What it is |
|---|---|---|
fate | DeletionFate | |
what | string | What it is: “Its disk”, “2 snapshots”. |
detail | string | What happens to it and what follows from that, one sentence. |
DeletionFate
Section titled “DeletionFate”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
Section titled “DepartureFate”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.
DeviceLoginStatus
Section titled “DeviceLoginStatus”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.
DotfilesConfig
Section titled “DotfilesConfig”| Field | Type | What it is |
|---|---|---|
repo | string | Git URL: https://github.com/user/dotfiles |
branch | string | Branch to clone (default: main) |
installCommand | string | Command to run after clone (default: ./install.sh) |
EmailSettings
Section titled “EmailSettings”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.
| Field | Type | What it is |
|---|---|---|
host | string | |
port | integer (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. |
username | string | |
passwordSet | boolean | |
from | string | The address mail is sent from, as the server allows this account to send. |
ExposedPort
Section titled “ExposedPort”| Field | Type | What it is |
|---|---|---|
id | string | |
workspaceId | string | |
port | integer (int32) | |
httpsBackend | boolean | The 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. |
description | string | |
createdAt | Timestamp | |
url | string | Output only: computed URL (e.g., https://3000-dev.ws.spinbox.dev) |
access | PortAccess | |
grants | list of PortGrant | Who 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
Section titled “ExtensionRelease”ExtensionRelease is one release of an extension: the supervisor, or the VS Code servers.
| Field | Type | What it is |
|---|---|---|
version | string | The 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. |
releasedAt | Timestamp | |
newest | boolean | Whether a start is given this one. |
volumeId | string | Its volume in the store, which RemoveStoredVolume takes when removable. |
removable | boolean | Not 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. |
keptBecause | string | Why 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
Section titled “ExtensionVersion”ExtensionVersion is a release and how many workspaces are on it: what an update leaves behind until each workspace is next started.
| Field | Type | What it is |
|---|---|---|
extension | string | |
version | string | |
workspaces | string (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. |
newest | boolean | Whether a start now would choose this release. |
FieldValue
Section titled “FieldValue”FieldValue is one value a field has, and how many of a search’s records have it.
| Field | Type | What it is |
|---|---|---|
value | string | |
count | string (int64) |
FileChange
Section titled “FileChange”| Field | Type | What it is |
|---|---|---|
path | string | From 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. |
pathBytes | string (byte) | |
kind | FileChangeKind | |
from | FileState | Unset on the side the path is not on. |
to | FileState |
FileChangeKind
Section titled “FileChangeKind”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.
FileState
Section titled “FileState”| Field | Type | What it is |
|---|---|---|
type | FileType | |
mode | integer | Permission bits, setuid, setgid and sticky included. |
uid | integer | |
gid | integer | |
size | string (int64) | |
symlinkTarget | string | A symlink’s target as stored, never followed; replaced and in symlink_target_bytes as path is. |
symlinkTargetBytes | string (byte) | |
sha256 | string | A regular file’s content hash in lowercase hex, where its content is what changed. |
modifiedAt | Timestamp |
FileType
Section titled “FileType”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.
FleetClass
Section titled “FleetClass”One host class’s group, as the control plane last saw it.
| Field | Type | What it is |
|---|---|---|
class | HostClass | |
desired | integer (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. |
most | integer (int32) | |
waiting | integer (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. |
oldestWaiting | Timestamp | |
busy | integer (int32) | Workspaces of the class, and hosts a root shell holds, keeping its group up. |
launchFailure | string | Why 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. |
launchFailedAt | Timestamp | |
giveBackRefused | string | A 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. |
giveBackRefusedAt | Timestamp | |
capacityRefused | boolean | launch_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. |
onDemandUntil | Timestamp | Set 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
Section titled “FleetHostVersion”FleetHostVersion is one host’s halves: the runner binary and the machine under it.
| Field | Type | What it is |
|---|---|---|
hostId | string | |
state | HostState | |
agentVersion | string | |
machineVersion | string | Empty on a host with no machine, such as the mock runner. |
supported | boolean | Whether this control plane serves a host of that version. An unsupported host is refused at its next registration, with note saying why. |
note | string | |
lastHeartbeat | Timestamp |
ForgeApp
Section titled “ForgeApp”| Field | Type | What it is |
|---|---|---|
forge | string | netpolicy.Forges: “github”. |
appId | string (int64) | |
slug | string | |
clientId | string | |
apiUrl | string | |
webUrl | string | |
hosts | list of string | The exact names a person’s token may be sent to. |
installUrl | string | Where the app is installed on an account, which is what lets a token reach its repositories. |
deleting | boolean | Being deleted: it takes no connection, and goes once what it granted has been revoked. |
updatedAt | Timestamp |
ForgeConnection
Section titled “ForgeConnection”| Field | Type | What it is |
|---|---|---|
forge | string | |
login | string | The account, as the forge names it. |
expiresAt | Timestamp | When the token ends: it is refreshed before then. |
connectedAt | Timestamp |
ForgeRepository
Section titled “ForgeRepository”| Field | Type | What it is |
|---|---|---|
fullName | string | owner/name. |
cloneUrl | string | What a project’s repository is: https, with nothing of a credential in it. |
defaultBranch | string | |
private | boolean | |
description | string |
Grafana
Section titled “Grafana”Grafana is the one the control plane runs over the installation’s metrics and serves to its administrators.
| Field | Type | What it is |
|---|---|---|
url | string | Where the control plane serves it: “/monitoring/grafana/”. |
dashboards | list of GrafanaDashboard | The release’s, in the order they are listed. |
GrafanaDashboard
Section titled “GrafanaDashboard”| Field | Type | What it is |
|---|---|---|
uid | string | |
title | string |
HeaderInjection
Section titled “HeaderInjection”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.
| Field | Type | What it is |
|---|---|---|
header | string | |
secret | string | The team secret’s name. |
prefix | string | What goes before the value, as “Bearer ”. |
identity | string | The 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). |
forge | string | The 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. |
methods | list of string | The 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. |
pathPrefix | string |
HealthCheck
Section titled “HealthCheck”HealthCheck is one part of the installation as the control plane knows it.
| Field | Type | What it is |
|---|---|---|
part | HealthPart | |
status | HealthStatus | |
reason | string | reason says in a line what was found, OK or not. |
knownAt | Timestamp | known_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. |
problems | list of Problem | What 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. |
problemCount | integer (int32) |
HealthCheckResult
Section titled “HealthCheckResult”| Field | Type | What it is |
|---|---|---|
name | string | |
passed | boolean | |
value | string | Actual value from check |
message | string | Error message if failed |
HealthPart
Section titled “HealthPart”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
Section titled “HealthReport”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.
| Field | Type | What it is |
|---|---|---|
healthy | boolean | |
checks | list of HealthCheckResult |
HealthStatus
Section titled “HealthStatus”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.
| Field | Type | What it is |
|---|---|---|
id | string | |
address | string | |
state | HostState | |
capacity | Resources | |
allocated | Resources | |
workspaceCount | integer (int32) | |
agentVersion | string | |
labels | map of string to string | |
lastHeartbeat | Timestamp | last_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. |
registeredAt | Timestamp | |
connected | boolean | connected 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. |
goingAway | boolean | going_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. |
checks | list of HostCheck | checks 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. |
hostClass | string | host_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. |
machineVersion | string | machine_version is the spin-machine release the host registered (its QEMU, kernel and firmware); empty for a host with no machine. |
detected | Resources | detected 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. |
streamHeardAt | Timestamp | Each 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. |
leaseRenewedAt | Timestamp | |
connectedChangedAt | Timestamp | connected_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. |
streamEnd | HostStreamEnd | Why 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. |
streamEndDetail | string | |
hostname | string | hostname 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. |
removal | HostRemoval | removal 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. |
removalRefused | string | removal_refused is why that removal cannot run now - a workspace whose disk is there - in words an administrator acts on; empty while it can. |
keysGiven | integer (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. |
machineId | string | Where 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. |
machineType | string | |
zone | string | |
region | string | |
reclaimable | boolean or null | reclaimable 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. |
holders | list of HostHolder | holders 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. |
holderCount | integer (int32) |
HostCheck
Section titled “HostCheck”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.
| Field | Type | What it is |
|---|---|---|
name | string | name is what was checked: clock, kvm, resolver. |
ok | boolean | |
detail | string | detail is what it found when it is not ok, in the host’s words. |
checkedAt | Timestamp |
HostClass
Section titled “HostClass”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.
| Field | Type | What it is |
|---|---|---|
name | string | Lower-case letters, digits and -, a letter first, up to 31: it is part of the group’s name. |
description | string | |
instanceTypes | list of string | The instance types it may be, as the cloud names them, patterns allowed (“c8id.*”); none is any type the rest admits. |
vcpusMin | integer (int32) | |
vcpusMax | integer (int32) | |
memoryMibPerVcpu | integer (int32) | The least memory a vCPU of it has, in MiB; 0 is 2048. |
spot | boolean | A machine the cloud may take back (each host drains first), or an on-demand one. |
maxHosts | integer (int32) | The most hosts of it; 0 is no limit of its own (the setting autoscaling_max_hosts bounds them all). |
fallbackOnDemand | boolean | A 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
Section titled “HostDeparture”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.
| Field | Type | What it is |
|---|---|---|
workspaces | list of WorkspaceDeparture | At most 20, the running first; count is how many there are. |
count | integer (int32) |
HostHolder
Section titled “HostHolder”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.
| Field | Type | What it is |
|---|---|---|
kind | HostHolderKind | |
workspaceId | string | The 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). |
workspaceName | string | |
volumeId | string | The 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. |
ownerId | string | Whose it is. |
ownerEmail | string | |
state | WorkspaceState | The workspace’s state; UNSPECIFIED for an agent’s home no workspace mounts. |
lastEvent | WorkspaceEventType | What last happened to the workspace, and when: its history’s newest entry. UNSPECIFIED and unset where it has none. |
lastEventAt | Timestamp |
HostHolderKind
Section titled “HostHolderKind”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.
HostNetworkPolicy
Section titled “HostNetworkPolicy”| Field | Type | What it is |
|---|---|---|
hostId | string | |
rules | list of NetworkRule |
HostPolicy
Section titled “HostPolicy”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.
| Field | Type | What it is |
|---|---|---|
hostId | string | |
shutdownGraceSeconds | integer 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. |
preemptible | boolean or null | Whether a stop here is the machine being taken away rather than coming back. |
preemptionSource | any | Which cloud announces that reclaim; setting one implies preemptible. |
preemptionMetadataUrl | string or null | That service’s address, for a private cloud or a test. |
capacityCpuCores | integer 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. |
capacityMemoryMb | integer or null (int32) | |
capacityDiskGb | integer or null (int32) | |
maxWorkspaceCpuCores | integer or null (int32) | The ceiling one workspace may grow to here, for the machines it starts afterwards. |
maxWorkspaceMemoryMb | integer or null (int32) | |
revision | string | revision names the content, and is what a host reports it is running under. |
writebackLimitBytes | string 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. |
writebackBackgroundBytes | string or null (int64) | |
runningRevision | string | running_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. |
maxWorkspaceIoMbPerSecond | integer 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. |
maxWorkspaceIoOpsPerSecond | integer or null (int32) |
HostRemoval
Section titled “HostRemoval”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.
HostShell
Section titled “HostShell”| Field | Type | What it is |
|---|---|---|
id | string | |
hostId | string | |
requestedBy | string | Who 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. |
approvedBy | string | |
reason | string | |
incident | boolean | An incident’s shell opens on a host still running workspaces. |
minutes | integer (int32) | How long it is open once it opens. |
state | HostShellState | |
requestedAt | Timestamp | |
approvedAt | Timestamp | |
openedAt | Timestamp | |
closesAt | Timestamp | |
endedAt | Timestamp | |
ended | string | How it ended, in words. |
hostRetired | boolean | Whether its host has been retired since: revoked, its disks marked to be re-keyed, and given back to its group where it has one. |
running | integer (int32) | How many workspaces the host still runs, while it is emptied. |
HostShellState
Section titled “HostShellState”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
Section titled “HostState”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
Section titled “HostStreamEnd”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.
IdentityProvider
Section titled “IdentityProvider”Identity provider info (returned to clients for login UI) Built-in provider has id=“github”; dynamic providers have UUIDv7 IDs
| Field | Type | What it is |
|---|---|---|
id | string | “github” for built-in, UUIDv7 for dynamic |
name | string | Display name (e.g., “Sign in with Okta”) |
providerType | string | github (built-in), oidc, google, azure-ad |
teamId | string | Empty if system-wide provider |
isDefault | boolean | True 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.
| Field | Type | What it is |
|---|---|---|
ref | string | The 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. |
virtualSizeBytes | string (int64) | What the disk cloned from it will hold before the workspace writes anything. |
publishedAt | Timestamp | When the publication this ref resolves to was made. |
name | string | What 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. |
description | string |
InjectionStatus
Section titled “InjectionStatus”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.
| Field | Type | What it is |
|---|---|---|
policy | string | The policy, by name, and the names its rule brokers. |
names | list of string | |
header | string | |
from | string | What the header is set from: a team secret by name, “<forge> app”, or “identity for <audience>”. |
held | boolean | Whether 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. |
InstallationEventType
Section titled “InstallationEventType”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
Section titled “InstallationPlace”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.
| Field | Type | What it is |
|---|---|---|
provider | string | The provider the installation was made on, as its document names it: “aws”, “self-hosted”. |
account | string | The cloud account it runs in, as that cloud names it. |
region | string | |
release | string | The release the control plane runs, “v20261112.01”. |
machineImage | string | The machine image the control plane’s machine booted, as its cloud names it. |
| Field | Type | What it is |
|---|---|---|
name | string | |
intervalSeconds | string (int64) | Zero for a job only run by hand, which has no next_run_at. |
running | boolean | |
nextRunAt | Timestamp | When the schedule next starts it. |
lastRun | JobRun | Unset until it has run on this installation. |
lastSucceededAt | Timestamp | |
title | string | The job as a person names it: “Storage collection” for storage-gc. |
does | string | A sentence of what it does. |
whileFailing | string | What 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. |
recentRuns | list of JobRun | Its 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. |
JobRun
Section titled “JobRun”| Field | Type | What it is |
|---|---|---|
runId | string | |
job | string | |
startedAt | Timestamp | |
finishedAt | Timestamp | Unset while it runs. |
outcome | JobRunOutcome | |
counts | map of string to string (int64) | What it did, by the job’s own names for it: objects deleted, bytes freed, hosts forgotten. |
error | string | Why it failed; empty when it did not. |
traceId | string | The 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. |
askedBy | string | The admin who ran it by hand; empty for a run the schedule started. |
JobRunOutcome
Section titled “JobRunOutcome”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
Section titled “LogIndex”LogIndex is one index of the store.
| Field | Type | What it is |
|---|---|---|
id | string | |
retention | string | How long it keeps what it holds, in the store’s words (“30 days”); empty for forever. |
timestampField | string | The field its records are dated by: what a search’s window is over. |
defaultSearchFields | list of string | What a query’s bare words are searched in. |
fields | list of LogIndexField | |
documents | string (int64) | What it holds: records, the splits they are kept in, and the splits’ size in the bucket and the records’ before compression. |
splits | string (int64) | |
sizeBytes | string (int64) | |
uncompressedBytes | string (int64) | |
oldest | Timestamp | When its oldest and newest records are dated; unset while it holds none. |
newest | Timestamp |
LogIndexField
Section titled “LogIndexField”LogIndexField is one field of an index’s mapping.
| Field | Type | What it is |
|---|---|---|
name | string | A dotted path for a field inside an object field. |
type | string | The store’s type: text, json, u64, bool, bytes, datetime, array<text>… |
tokenizer | string | How 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. |
indexed | boolean | Whether a query can match it, and whether it can be counted and ranged over fast. |
fast | boolean |
LogInterval
Section titled “LogInterval”LogInterval is how many records one interval holds, by severity.
| Field | Type | What it is |
|---|---|---|
start | Timestamp | |
bySeverity | map of string to string (int64) |
LogRecord
Section titled “LogRecord”LogRecord is one record as OpenTelemetry names its parts.
| Field | Type | What it is |
|---|---|---|
time | Timestamp | |
severity | string | |
service | string | The process that wrote it: controlplane, runner, proxy. |
body | Value | What was logged: its message, or the structure it logged. |
attributes | Struct | |
resourceAttributes | Struct | |
traceId | string | The trace it was written in, hex; empty for none. |
spanId | string |
MemoryUsagePoint
Section titled “MemoryUsagePoint”MemoryUsagePoint is the most the machine used over a step - running out is a peak, not a mean - against what it held, as CpuUsagePoint.
| Field | Type | What it is |
|---|---|---|
start | Timestamp | |
usedBytes | string (int64) | |
heldBytes | string (int64) | |
memoryBytes | string (int64) | |
maxMemoryBytes | string (int64) |
NetworkPolicy
Section titled “NetworkPolicy”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.
| Field | Type | What it is |
|---|---|---|
name | string | |
hosts | list of HostNetworkPolicy | What each host reporting this tag says it enforces. |
declared | boolean | declared says the installation has this policy, and rules are what it allows. A policy with no hosts is declared and not yet enforced anywhere. |
rules | list of NetworkRule | |
teamId | string | The 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
Section titled “NetworkPolicyRule”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.
| Field | Type | What it is |
|---|---|---|
name | string | |
rules | list of NetworkRule |
NetworkRule
Section titled “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.
| Field | Type | What it is |
|---|---|---|
allow | list of string | IPv4 prefixes in CIDR. |
allowNames | list of string | Names, exact or with a leading ”*.”: the host opens the address its own resolver answers a machine with, for as long as the answer lives. |
ports | list of string | Destination 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. |
broker | boolean | The 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. |
inject | list of HeaderInjection | Headers 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. |
cloud | CloudAccess | The 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. |
verifySni | boolean | The 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. |
principal | string | Whose 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
Section titled “NetworkUsagePoint”NetworkUsagePoint is what the machine’s network carried over a step.
| Field | Type | What it is |
|---|---|---|
start | Timestamp | |
sentBytes | string (int64) | |
receivedBytes | string (int64) |
Notification
Section titled “Notification”Notification is one event of a workspace’s timeline its owner is told of: what happened, and what they can do about it.
| Field | Type | What it is |
|---|---|---|
id | string | The workspace event’s id. |
workspaceId | string | |
workspaceName | string | |
event | WorkspaceEventType | |
createdAt | Timestamp | |
subject | string | One line saying what happened. |
body | string | What happened, in full. |
command | string | The command that does what the owner can do about it; empty where nothing is to be done. |
deliveries | list of NotificationDelivery | Empty where it was never sent: email off, or this kind turned off. |
NotificationChannel
Section titled “NotificationChannel”How a notification leaves the installation.
One of: NOTIFICATION_CHANNEL_UNSPECIFIED, NOTIFICATION_CHANNEL_EMAIL.
NotificationDelivery
Section titled “NotificationDelivery”| Field | Type | What it is |
|---|---|---|
channel | NotificationChannel | |
state | NotificationDeliveryState | |
attempts | integer (int32) | |
lastError | string | What the last attempt that failed was told; empty once one succeeded. |
sentAt | Timestamp |
NotificationDeliveryState
Section titled “NotificationDeliveryState”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.
NotificationPreference
Section titled “NotificationPreference”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.
| Field | Type | What it is |
|---|---|---|
event | WorkspaceEventType | |
email | boolean | |
installationEvent | InstallationEventType |
ObservedDestination
Section titled “ObservedDestination”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.
| Field | Type | What it is |
|---|---|---|
address | string | |
name | string | |
packets | string (int64) | What the workspace sent there, every packet of every flow. |
bytes | string (int64) | |
protocol | string | “tcp”, “udp”, “icmp”, or the protocol’s number. |
port | integer | For tcp and udp; zero otherwise. |
packetsReceived | string (int64) | What came back to the workspace from there. |
bytesReceived | string (int64) |
OutsideShareState
Section titled “OutsideShareState”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.
PageRequest
Section titled “PageRequest”Pagination for list requests
| Field | Type | What it is |
|---|---|---|
pageSize | integer (int32) | |
pageToken | string |
PageResponse
Section titled “PageResponse”| Field | Type | What it is |
|---|---|---|
nextPageToken | string | |
totalCount | integer (int32) |
Passkey
Section titled “Passkey”| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
credentialId | string (byte) | |
createdAt | Timestamp | |
lastUsedAt | Timestamp |
PasskeyAssertion
Section titled “PasskeyAssertion”PasskeyAssertion is what navigator.credentials.get answers, and the challenge it answers.
| Field | Type | What it is |
|---|---|---|
challenge | string (byte) | |
credentialId | string (byte) | |
clientDataJson | string (byte) | |
authenticatorData | string (byte) | |
signature | string (byte) | ECDSA’s, in ASN.1 DER, as WebAuthn returns it. |
PasskeyPurpose
Section titled “PasskeyPurpose”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.
PlatformCost
Section titled “PlatformCost”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.
| Field | Type | What it is |
|---|---|---|
role | string | As the resources carry it (on AWS, their spin:role tag); empty where they carry none, which is said as untagged. |
service | string | |
micros | string (int64) |
PlatformImage
Section titled “PlatformImage”| Field | Type | What it is |
|---|---|---|
artifact | PlatformImageArtifact | |
state | PlatformImageState | |
detail | string | Why it failed, or why it is left alone. |
version | string | The machine’s release, or the supervisor’s (the control plane’s) version. |
updatedAt | Timestamp |
PlatformImageArtifact
Section titled “PlatformImageArtifact”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.
PlatformImageState
Section titled “PlatformImageState”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.
PortAccess
Section titled “PortAccess”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.
PortGrant
Section titled “PortGrant”One user a whitelisted port is shared with.
| Field | Type | What it is |
|---|---|---|
userId | string | |
email | string | Output only, so a list is readable without a second lookup |
grantedAt | Timestamp |
Prebuild
Section titled “Prebuild”A prebuild: one build of a project’s ref at a commit, and the snapshot it left.
| Field | Type | What it is |
|---|---|---|
id | string | |
projectId | string | |
ref | string | |
commit | string | |
state | PrebuildState | |
snapshotId | string | |
parentId | string | The prebuild it was built on, and how many builds it is from the image (0: built from it). |
depth | integer (int32) | |
image | string | |
log | string | The tail of what its build’s create tasks wrote (GetPrebuild only), and why it failed. |
error | string | |
createdAt | Timestamp | |
builtAt | Timestamp | |
workspaceCount | integer (int32) | In ListPrebuilds: the workspaces opened from it that are not deleted, whoever’s they are. |
reportedAt | Timestamp | When its build’s guest said the checkout and create tasks were done; unset before it did. |
spinYaml | boolean | Whether 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. |
storedBytes | string or null (int64) | What it keeps in the object store, as storage-gc last read it; unset before a reading counted it. |
buildWorkspaceId | string | The 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. |
buildWorkspaceOwnerId | string |
PrebuildRefNotFound
Section titled “PrebuildRefNotFound”A prebuild ref the project’s forge has not.
| Field | Type | What it is |
|---|---|---|
ref | string | |
since | Timestamp | The job’s first look that found it missing. |
PrebuildState
Section titled “PrebuildState”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.
PrebuildsKept
Section titled “PrebuildsKept”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.
| Field | Type | What it is |
|---|---|---|
storedBytes | string (int64) | As the store was last read (Admin’s Storage, PREBUILD). |
day | Timestamp | The 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. |
monthMicros | string or null (int64) |
PreemptionSource
Section titled “PreemptionSource”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
Section titled “Problem”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.
| Field | Type | What it is |
|---|---|---|
cause | string | cause says in a line what was found. |
since | Timestamp | since 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. |
impact | ProblemImpact | |
evidence | list of ProblemEvidence | What shows it, each a thing the console has a page for. |
runbookId | string | The runbook to follow (Runbook.id), of the runbooks this release serves: never empty. |
actions | list of ProblemAction | What the console itself can do about it, each on the host or the job the problem is of. |
hostId | string | The host the problem is of, and the name its machine goes by; empty for one that is not a host’s. |
hostname | string | |
job | string | The job (Job.name) the problem is of, and its title; empty for one that is not a job’s. |
jobTitle | string |
ProblemAction
Section titled “ProblemAction”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
Section titled “ProblemEvidence”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
Section titled “ProblemImpact”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.
| Field | Type | What it is |
|---|---|---|
stops | string | What stops working, in a line: “log lines are not kept”. Empty where the rows say it. |
runningWorkspaces | integer (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. |
restingWorkspaces | integer (int32) | |
waitingWorkspaces | integer (int32) | |
workspaces | list of AffectedWorkspace | At most 10 of them, the running first, then by name: the counts above are the whole. |
Project
Section titled “Project”A project: a repository and the shape of the workspace that opens it.
| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
slug | string | What a person names it by in the installation: teams.slug’s shape |
description | string | |
repository | string | An https URL, with nothing of a credential in it |
ref | string | The branch or tag a workspace opens at unless the open names one |
image | string | As CreateWorkspaceRequest.image; empty is the installation’s default when opened |
preset | string | As CreateWorkspaceRequest.preset; empty likewise |
networkTags | list of string | |
workspaceCount | integer (int32) | Workspaces open on it, the trash included |
createdAt | Timestamp | |
updatedAt | Timestamp | |
prebuildRefs | list of string | The 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. |
prebuildRebaseEvery | integer (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. |
prebuildOwnerId | string | Who the builds run as, for what they use: the project admin who last named the refs. |
sharedWithEveryone | boolean | Seen by everybody signed in; otherwise by its admins and shares. |
administers | boolean | Whether the caller may change, share and delete it. |
adminIds | list of string | Its admins and whom it is shared with: shown to its admins, empty to everybody else. |
sharedUserIds | list of string | |
sharedTeamIds | list of string | |
readyPrebuildCount | integer (int32) | In ListProjects: how many of its prebuilds are ready to open from. |
prebuildKeep | integer (int32) | How many of each ref’s newest ready prebuilds are kept when no workspace was opened from them. |
timeToReady | ProjectTimeToReady | In GetProject: how long its workspaces took to be ready. Unset where none has been. |
ProjectTimeToReady
Section titled “ProjectTimeToReady”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.
| Field | Type | What it is |
|---|---|---|
workspaces | integer (int32) | How many workspaces the times are over: 1 to 20. |
median | Duration | |
slowest | Duration |
ProjectWorkspace
Section titled “ProjectWorkspace”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.
| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
ownerId | string | |
ownerName | string | |
ownerEmail | string | |
state | WorkspaceState | As Workspace.state, DEGRADED included. |
since | Timestamp | Since when it has been in that state: when its guest answered for a running one, and when its row last changed for any other. |
QuarantineDenial
Section titled “QuarantineDenial”| Field | Type | What it is |
|---|---|---|
target | string | Where the attempt went: the destination, as the supervisor saw it (host and port). |
details | map of string to string | What the supervisor held of it, in its own words: which user in the guest, which process, why the policy refused. |
at | Timestamp | When the attempt was made, as the guest clock held it. |
RefusedDestination
Section titled “RefusedDestination”| Field | Type | What it is |
|---|---|---|
address | string | |
name | string | |
protocol | string | “tcp”, “udp”, “icmp”, or the protocol’s number. |
port | integer | For tcp and udp; zero otherwise. |
packets | string (int64) |
RefusedVolume
Section titled “RefusedVolume”RefusedVolume is a disk its host is not serving, and the workspace that cannot run for it.
| Field | Type | What it is |
|---|---|---|
volumeId | string | |
refusal | string | The token an alert keys on, and the sentence the host sent with it (VolumeStatus). |
refusalDetail | string | |
hostId | string | The host refusing it; empty for a disk placed nowhere. |
hostName | string | |
workspaceId | string | The workspace it is the disk of; empty for a disk no workspace runs on. |
workspaceName | string | |
workspaceState | WorkspaceState | |
ownerId | string | Whose the workspace is. |
ownerEmail | string |
RegistrationMode
Section titled “RegistrationMode”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.
RegistrationToken
Section titled “RegistrationToken”| Field | Type | What it is |
|---|---|---|
id | string | |
tokenPrefix | string | First 8 chars for identification |
description | string | Human-readable description |
teamId | string | Optional: team scope for registered host |
expiresAt | Timestamp | |
createdAt | Timestamp | |
createdBy | string | |
used | boolean | |
usedByHostId | string | Host ID that used this token; a reusable token’s last one |
reusable | boolean | A pool’s token: it registers every host that presents it until it expires or is revoked. |
hostPolicy | HostPolicy | What 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
Section titled “RekeyState”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.
ResolverLookup
Section titled “ResolverLookup”| Field | Type | What it is |
|---|---|---|
name | string | |
outcome | string | filtered, refused, upstream_failed or malformed. |
at | Timestamp |
ResourcePreset
Section titled “ResourcePreset”ResourcePreset is a class of workspace: its size, and how a workspace of it may grow. Every workspace is created from one.
| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | Display name (e.g., “Small”, “Medium”, “Large”) |
description | string | Description of the preset |
cpuCores | integer (int32) | Number of CPU cores |
memoryMb | integer (int32) | Memory in megabytes |
diskGb | integer (int32) | Disk space in gigabytes |
burst | BurstMode | |
isDefault | boolean | This is the default preset |
enabled | boolean | Preset is available for selection |
sortOrder | integer (int32) | Display order (lower = first) |
createdAt | Timestamp | |
updatedAt | Timestamp | |
burstFloorCpuCores | integer (int32) | What a workspace of a burst mode starts with; at most cpu_cores and memory_mb. |
burstFloorMemoryMb | integer (int32) | |
bandwidthMbps | integer (int32) | What a workspace of it may carry each way, in megabits a second; 0 is unshaped. |
rpoSeconds | integer (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). |
hostClass | string | The host class its workspaces run on (HostClass). |
agentMinMemoryMb | integer (int32) | What a workspace has to hold for its agent to start there, in MB, for whoever picks a preset. |
fromConfig | boolean | Seeded 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. |
minMemoryMb | integer (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. |
Resources
Section titled “Resources”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)
| Field | Type | What it is |
|---|---|---|
cpuCores | integer (int32) | Initial CPU cores at boot (default: 1) |
memoryMb | integer (int32) | Initial memory in MB at boot (default: 512) |
diskGb | integer (int32) | Disk size in GB (default: 10) |
maxCpuCores | integer (int32) | Max CPU cores (0 = unlimited) |
maxMemoryMb | integer (int32) | Max memory in MB (0 = unlimited) |
bandwidthMbps | integer (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. |
RoleCost
Section titled “RoleCost”What one role cost on one day, its services summed.
| Field | Type | What it is |
|---|---|---|
role | string | Empty where the resources carry none. |
micros | string (int64) |
Runbook
Section titled “Runbook”| Field | Type | What it is |
|---|---|---|
id | string | Stable: alert rules and pages link /admin/runbooks/<id>. |
title | string | |
severity | string | critical, warning or info. |
owner | string | The role that keeps it true: operator, security. |
lastReviewed | string | YYYY-MM-DD: when it was last held to the release it describes. |
appliesTo | RunbookAppliesTo |
RunbookAppliesTo
Section titled “RunbookAppliesTo”What sends an operator to a runbook, each as the installation names it.
| Field | Type | What it is |
|---|---|---|
alerts | list of string | Grafana alert rule uids. |
jobs | list of string | Control plane job names (Job.name). |
events | list of string | The notices a workspace’s owner gets, by WorkspaceEventType without its prefix: HELD. |
dashboards | list of string | Grafana dashboard uids. |
SSHKey
Section titled “SSHKey”User’s uploaded SSH public key
| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | User-provided name |
fingerprint | string | SHA256 fingerprint |
publicKey | string | Full public key |
createdAt | Timestamp | |
expiresAt | Timestamp | No 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. |
ServiceCost
Section titled “ServiceCost”What one of the cloud’s services cost on one day, in millionths of the bill’s currency.
| Field | Type | What it is |
|---|---|---|
service | string | |
micros | string (int64) |
ServiceHealth
Section titled “ServiceHealth”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.
| Field | Type | What it is |
|---|---|---|
service | string | |
traces | string (int64) | |
failedTraces | string (int64) | |
p50Millis | number (double) | |
p95Millis | number (double) | |
errorLogs | string (int64) | |
intervals | list of ServiceInterval |
ServiceInterval
Section titled “ServiceInterval”| Field | Type | What it is |
|---|---|---|
start | Timestamp | |
traces | string (int64) | |
failedTraces | string (int64) |
SettingDefinition
Section titled “SettingDefinition”SettingDefinition is one setting of the installation as the code defines it.
| Field | Type | What it is |
|---|---|---|
key | string | |
type | SettingType | |
defaultValue | string | What is in force where the installation says nothing, as text of the type. |
min | string or null (int64) | |
max | string or null (int64) | |
choices | list of string | The values a STRING setting takes; empty is any. |
reach | SettingReach | What it touches once saved. |
restart | boolean | It is read when the control plane starts: a change is in force after its next restart. |
section | string | Which page it is on: general, workspaces, fleet, network, security, registration, telemetry, logs, bill, email, storage, installation, control_plane. |
label | string | A few words that name it, and a sentence that says what it does and what its zero means. |
summary | string | |
writer | SettingWriter |
SettingReach
Section titled “SettingReach”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
Section titled “SettingType”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
Section titled “SettingWriter”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.
Snapshot
Section titled “Snapshot”A snapshot is a rotation of a workspace’s volume, published as a commit. It has no name outside its id.
| Field | Type | What it is |
|---|---|---|
id | string | |
workspaceId | string | |
description | string | User-provided description |
createdAt | Timestamp | |
isPublic | boolean | Whether snapshot is publicly visible |
shareCount | integer (int32) | Number of users snapshot is shared with |
accessType | SnapshotAccessType | How user has access |
state | SnapshotState | |
withMemory | boolean | with_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. |
parentSnapshotId | string | The 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. |
SnapshotAccessType
Section titled “SnapshotAccessType”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.
SnapshotShare
Section titled “SnapshotShare”A share record for a snapshot
| Field | Type | What it is |
|---|---|---|
id | string | |
snapshotId | string | |
userId | string | |
userEmail | string | |
userName | string | |
grantedAt | Timestamp | |
grantedBy | string |
SnapshotState
Section titled “SnapshotState”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.
| Field | Type | What it is |
|---|---|---|
traceId | string | |
spanId | string | |
parentSpanId | string | Empty for the trace’s first span. |
service | string | |
name | string | |
start | Timestamp | |
durationMicros | string (int64) | How long it took, in microseconds. |
failed | boolean | Whether it ended in an error, and what it said. |
statusMessage | string | |
attributes | Struct | |
events | list of Struct | What happened during it, as the span recorded it: each event’s name, time and attributes. |
StandbyCost
Section titled “StandbyCost”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).
| Field | Type | What it is |
|---|---|---|
day | Timestamp | The billed day it is from: its first instant, UTC. |
platform | list of RoleCost | The platform by role, costliest first. |
idleMicros | string (int64) | |
unstoredMicros | string (int64) |
StatusDisagreement
Section titled “StatusDisagreement”| Field | Type | What it is |
|---|---|---|
kind | StatusDisagreementKind | |
detail | string | One sentence naming both sides and the gap between them, for a person to read. The kind is what a script branches on. |
StatusDisagreementKind
Section titled “StatusDisagreementKind”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
Section titled “StorageSettings”StorageSettings is where the object store is: a bucket, or on one machine a directory.
| Field | Type | What it is |
|---|---|---|
bucket | string | |
endpoint | string | Empty is the store’s own service for its region. |
region | string | |
accessKeyId | string | The control plane’s own credential; empty is the machine’s own. |
secretSet | boolean | Whether the access key’s secret is set: the secret itself is never read back. |
dir | string | |
principal | string | Who 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). |
StorageTally
Section titled “StorageTally”| Field | Type | What it is |
|---|---|---|
objects | string (int64) | |
bytes | string (int64) |
StoredVolume
Section titled “StoredVolume”StoredVolume is one volume in the store: what is under volumes/<volume_id>/, and the layers its commits name under layers/.
| Field | Type | What it is |
|---|---|---|
volumeId | string | |
kind | StoredVolumeKind | |
name | string | The workspace’s name, the prebuild’s project, ref and commit, the image’s ref, or the extension and its version. |
workspaceId | string | The workspace’s, for a workspace’s disk and a prebuild. |
ownerEmail | string | The workspace’s owner, or the person whose agent’s home it is. |
current | boolean | Whether it is the workspace’s disk now, rather than one it had. |
own | StorageTally | The descriptor, HEAD, the epoch and the commit manifests. |
layers | StorageTally | |
checkpoints | StorageTally | Its checkpoints’ memory and records. |
removable | boolean | Whether 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. |
untaggable | boolean | An image its ref still names, which UntagImage takes the ref off. |
keptBecause | string | Why it stays, in words, where it is an image, a release or an agent’s home that may not go. |
label | string | What 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”. |
fromDescriptor | boolean | The 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. |
StoredVolumeKind
Section titled “StoredVolumeKind”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
Section titled “SupervisorState”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.
SupervisorStatus
Section titled “SupervisorStatus”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.
| Field | Type | What it is |
|---|---|---|
state | SupervisorState | |
version | string | |
lastHeartbeat | Timestamp | |
connected | boolean | Whether 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. |
health | HealthReport |
| Field | Type | What it is |
|---|---|---|
id | string | |
parentId | string | Empty if root team |
name | string | |
slug | string | |
path | string | Materialized path: “/engineering/backend” |
depth | integer (int32) | 1, 2, or 3 |
description | string | |
memberCount | integer (int32) | Direct members only |
workspaceCount | integer (int32) | Direct workspaces only |
createdAt | Timestamp | |
updatedAt | Timestamp | |
displayName | string | Human-friendly name (falls back to name if empty) |
isPersonal | boolean | Personal team for a single user (cannot be deleted or left by owner) |
TeamIdentityProvider
Section titled “TeamIdentityProvider”| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
providerType | string | oidc, github, google, azure-ad |
issuerUrl | string | |
autoJoinCelExpression | string | CEL expression for auto-membership |
roleCelExpression | string | CEL expression for role assignment |
enabled | boolean | |
createdAt | Timestamp | |
refusedRemoval | string | Why 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). |
TeamMember
Section titled “TeamMember”| Field | Type | What it is |
|---|---|---|
userId | string | |
email | string | |
name | string | |
role | TeamRole | |
joinedAt | Timestamp |
TeamRole
Section titled “TeamRole”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.
TeamSecret
Section titled “TeamSecret”| Field | Type | What it is |
|---|---|---|
name | string | |
updatedAt | Timestamp | |
hosts | list of string | |
ref | string | Where the team keeps the value; empty where the control plane does. |
TeamWorkspaceCost
Section titled “TeamWorkspaceCost”What one of a team’s workspaces cost in the month.
| Field | Type | What it is |
|---|---|---|
workspaceId | string | |
name | string | |
share | CostShare |
TelemetryFlow
Section titled “TelemetryFlow”TelemetryFlow is what one exporter of the collector did over the last window.
| Field | Type | What it is |
|---|---|---|
sent | string (int64) | |
failed | string (int64) |
ThirdPartyAcceptance
Section titled “ThirdPartyAcceptance”ThirdPartyAcceptance is an administrator’s acceptance of an item’s terms.
| Field | Type | What it is |
|---|---|---|
termsVersion | string | The version of the text that was accepted; an older one than the response’s counts as none. |
acceptedBy | string | Who accepted, by email: kept as it was when they did. |
acceptedAt | Timestamp |
ThirdPartyItem
Section titled “ThirdPartyItem”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
Section titled “ThirdPartyPart”ThirdPartyPart is one program an item downloads, and the license it comes under.
| Field | Type | What it is |
|---|---|---|
name | string | |
maker | string | Who makes it and serves the download. |
license | string | |
licenseUrl | string |
ThirdPartyTermsItem
Section titled “ThirdPartyTermsItem”| Field | Type | What it is |
|---|---|---|
item | ThirdPartyItem | |
name | string | |
purpose | string | What a workspace gets from it. |
parts | list of ThirdPartyPart | |
acceptance | ThirdPartyAcceptance | Unset where nobody accepted the terms for it. |
accepted | boolean | Whether this installation downloads it: accepted, as the current text. |
TimelineActor
Section titled “TimelineActor”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
Section titled “TimelineEvent”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.
| Field | Type | What it is |
|---|---|---|
source | TimelineSource | The record it is read from, and that record’s id there: the evidence a reader opens. |
id | string | |
at | Timestamp | |
actor | TimelineActor | Who or what did it. |
actorId | string | The person, when actor is PERSON: empty for one whose account has since been deleted, and the email is what their row says now. |
actorEmail | string | |
what | string | What 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. |
resourceType | string | What 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. |
resourceId | string | |
resourceName | string | The 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. |
details | string | The 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. |
traceId | string | The 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
Section titled “TimelineSource”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.
| Field | Type | What it is |
|---|---|---|
id | string | |
email | string | |
name | string | |
avatarUrl | string | |
subscriptionTier | string | |
createdAt | Timestamp | |
isInstanceAdmin | boolean | |
disabled | boolean | |
disabledReason | string | |
lastLoginAt | Timestamp | When they last signed in, by any route; unset for one who never has. |
UserHoldings
Section titled “UserHoldings”| Field | Type | What it is |
|---|---|---|
apiKeys | integer (int32) | API keys not yet expired. |
teams | integer (int32) |
UserSettings
Section titled “UserSettings”| Field | Type | What it is |
|---|---|---|
dotfiles | DotfilesConfig | |
startupTaskfile | string | Inline Taskfile YAML |
defaultShell | string | e.g., /bin/bash, /bin/zsh |
editorSettings | map of string to string | IDE preferences |
defaultEnv | map of string to string | Environment variables |
updatedAt | Timestamp |
VSCodeServerPublish
Section titled “VSCodeServerPublish”VSCodeServerPublish is this control plane’s publish: the last one, or the one under way.
| Field | Type | What it is |
|---|---|---|
state | VSCodeServerPublishState | |
step | string | Which part is running, while it works. |
detail | string | Why it failed. |
version | string | What it released, once it has. |
updatedAt | Timestamp |
VSCodeServerPublishState
Section titled “VSCodeServerPublishState”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
Section titled “VolumeRekey”VolumeRekey is a workspace’s disk to re-key or being re-keyed.
| Field | Type | What it is |
|---|---|---|
volumeId | string | |
workspaceId | string | |
workspaceName | string | |
state | RekeyState | |
hostId | string | The host copying it, empty while pending. |
reason | string |
Workspace
Section titled “Workspace”| Field | Type | What it is |
|---|---|---|
id | string | |
name | string | |
teamId | string | Every workspace has one: its owner’s personal team unless another was named |
hostId | string | |
image | string | Container image used for this workspace |
resources | Resources | |
state | WorkspaceState | |
url | string | Output only: https://{name}.{base domain}; empty until setup records a domain |
env | map of string to string | |
createdAt | Timestamp | |
updatedAt | Timestamp | |
snapshotCount | integer (int32) | Number of snapshots in history |
failureReason | string | Reason for failure (only set when state=FAILED) |
networkTags | list of string | The 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. |
hostConnected | boolean | host_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. |
waitingReason | string | waiting_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. |
failure | WorkspaceFailure | failure 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. |
networkWatch | boolean | network_watch says its host records where it connects into its logs (SetWorkspaceNetworkWatch). |
floorCpuCores | integer (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). |
floorMemoryMb | integer (int32) | |
grantExpiresAt | Timestamp | When its grant is given back on its own; unset for one kept until it is given back, and for a workspace holding none. |
quarantineHeld | boolean | quarantine_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. |
progress | WorkspaceProgress | progress 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. |
allowedActions | list of WorkspaceAction | allowed_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. |
failureSummary | string | failure_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. |
readyAt | Timestamp | ready_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. |
traceId | string | trace_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. |
durability | WorkspaceDurability | durability 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. |
role | string | role is the caller’s in it: “owner”, or “guest” - who may connect, see it and open its ports, and nothing that changes it. |
checkoutPath | string | checkout_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. |
memoryMachineGone | boolean | memory_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. |
suspendsAt | Timestamp | The 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. |
suspendsFor | WorkspaceEventType | |
keptUntil | Timestamp | An answer: kept awake until then, and neither suspension fires before it. |
leases | list of WorkspaceLease | The 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. |
projectId | string | The project it opened and the ref it was opened at; empty for a workspace that opened none. |
ref | string | |
wakeOnAccess | boolean | Suspended, 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. |
suspendedSnapshotId | string | The 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. |
fromPrebuildId | string | The prebuild its disk is a clone of; empty for one that opened with none. |
agentMinMemoryMb | integer (int32) | What it has to hold for its agent to start there, in MB (the supervisor refuses below it). |
projectError | string | project_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. |
ownerId | string | Whose 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. |
ownerName | string | |
ownerEmail | string | |
hostClass | string | host_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. |
attempts | list of WorkspaceAttempt | attempts 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. |
projectReportedAt | Timestamp | project_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. |
projectHead | string | |
hostName | string | host_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. |
withoutPrebuild | string | without_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
Section titled “WorkspaceAction”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
Section titled “WorkspaceAgentThreads”WorkspaceAgentThreads is one workspace’s chats with what a rail names it by: the workspace, its state, and the project it opened.
| Field | Type | What it is |
|---|---|---|
workspaceId | string | |
workspaceName | string | |
state | WorkspaceState | |
projectId | string | Empty for a workspace that opened no project. |
projectName | string | |
environmentId | string | As ListAgentThreadsResponse.environment_id: the first part of a thread’s page. |
threads | list of AgentThread | Newest first. |
WorkspaceAttempt
Section titled “WorkspaceAttempt”WorkspaceAttempt is one attempt a host made at a workspace’s generation that failed.
| Field | Type | What it is |
|---|---|---|
attempt | integer (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. |
failure | WorkspaceFailure | Which part failed, and the host’s words for why. |
reason | string | |
failedAt | Timestamp | failed_at is when the control plane heard that it failed. |
WorkspaceCost
Section titled “WorkspaceCost”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.
| Field | Type | What it is |
|---|---|---|
workspaceId | string | |
name | string | |
teamId | string | |
teamName | string | Empty where the team was deleted since. |
ownerId | string | |
ownerEmail | string | Empty where the owner was deleted since. |
computeMicros | string (int64) | Its share of the runners: what it held of them. |
storageMicros | string (int64) | Its share of the volumes’ bucket: what its volumes kept. |
sentBytes | string (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. |
receivedBytes | string (int64) | |
forwardedBytes | string (int64) |
WorkspaceDeparture
Section titled “WorkspaceDeparture”WorkspaceDeparture is one workspace on a host and what each way of taking the host out does to it.
| Field | Type | What it is |
|---|---|---|
workspaceId | string | |
workspaceName | string | |
ownerEmail | string | |
state | WorkspaceState | |
drain | DepartureFate | What a drain that moves the host’s workspaces (DrainHostRequest.suspend) does to it: MOVES or STAYS. |
removal | DepartureFate | What Host.removal does to it: LOSES_PLACE or HOLDS. UNSPECIFIED where the host has no removal. |
taken | DepartureFate | What 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
Section titled “WorkspaceDurability”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.
| Field | Type | What it is |
|---|---|---|
lastPublishedAt | Timestamp | last_published_at is when its last commit reached the object store, as its host last said; from a snapshot, when that snapshot was taken. |
unpublishedSeconds | string (int64) | What is written and not yet published, as of the host’s report plus the time since. |
unpublishedBytes | string (int64) | |
stalled | boolean | stalled says publishing has not kept up with the bound it runs to (the volume’s RPO). |
reportedAt | Timestamp | reported_at is the host’s report these are as of; unset when they are a snapshot’s. |
snapshotId | string | snapshot_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. |
publishedBytes | string (int64) |
WorkspaceEvent
Section titled “WorkspaceEvent”Timeline event for workspace state changes
| Field | Type | What it is |
|---|---|---|
id | string | |
workspaceId | string | |
type | WorkspaceEventType | |
timestamp | Timestamp | |
details | string | Additional info (JSON) |
WorkspaceEventType
Section titled “WorkspaceEventType”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
Section titled “WorkspaceFailure”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.
WorkspaceGuest
Section titled “WorkspaceGuest”| Field | Type | What it is |
|---|---|---|
userId | string | |
email | string | |
name | string | |
invitedAt | Timestamp |
WorkspaceHostStatus
Section titled “WorkspaceHostStatus”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.
| Field | Type | What it is |
|---|---|---|
hostId | string | |
state | HostState | |
lastHeartbeat | Timestamp | |
hostname | string | Which 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). |
hostClass | string | |
machineType | string | The 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. |
zone | string |
WorkspaceLease
Section titled “WorkspaceLease”WorkspaceLease is a process in the workspace keeping it awake while it lives.
| Field | Type | What it is |
|---|---|---|
name | string | name is the command, or the .spin.yaml task, that holds it. |
since | Timestamp | |
until | Timestamp | until is when the lease stops counting whether or not the process lives: since plus the installation’s workspace_lease_max_minutes. |
WorkspaceNetworkStatus
Section titled “WorkspaceNetworkStatus”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.
| Field | Type | What it is |
|---|---|---|
policy | string | |
declared | boolean | declared says a policy of this name exists: the installation’s, or a team’s. |
installed | boolean | installed says the workspace’s host last reported enforcing a policy of this name. False for a workspace on no host. |
WorkspacePhase
Section titled “WorkspacePhase”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
Section titled “WorkspaceProgress”WorkspaceProgress is a transition under way.
| Field | Type | What it is |
|---|---|---|
attempt | integer (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. |
attempts | integer (int32) | |
lastFailure | WorkspaceFailure | Why the attempt before this one failed, while this one is in progress: what a retry hides. |
lastReason | string | |
phase | WorkspacePhase | phase is what the host is doing now; UNSPECIFIED when it has not said. |
since | Timestamp | since 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. |
deadline | Timestamp | |
typical | Duration | typical 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. |
WorkspaceProxyStatus
Section titled “WorkspaceProxyStatus”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
Section titled “WorkspaceRuntime”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.
| Field | Type | What it is |
|---|---|---|
cpuCores | integer (int32) | |
memoryBytes | string (int64) | |
memoryUsedBytes | string (int64) | |
cpuSeconds | number (double) | |
machineStartedAt | Timestamp |
WorkspaceState
Section titled “WorkspaceState”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.
WorkspaceSuspendFailure
Section titled “WorkspaceSuspendFailure”| Field | Type | What it is |
|---|---|---|
workspaceId | string | |
error | string |
WorkspaceVolumeStatus
Section titled “WorkspaceVolumeStatus”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.
| Field | Type | What it is |
|---|---|---|
volumeId | string | |
state | string | |
refusal | string | |
refusalDetail | string |
WritebackPreset
Section titled “WritebackPreset”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).
| Field | Type | What it is |
|---|---|---|
name | string | name is how the preset is told apart; label is how a person is shown it. |
label | string | |
limitBytes | string (int64) | Both zero is unset. |
backgroundBytes | string (int64) | |
measured | string | measured is what it did, in words. |
WritebackRun
Section titled “WritebackRun”WritebackRun mirrors spin.agent.v1.WritebackRun, which is what the host reports.
| Field | Type | What it is |
|---|---|---|
writerBytesPerSecond | string (int64) | |
probeP50Us | string (int64) | |
probeP99Us | string (int64) | |
probeMaxUs | string (int64) | |
probes | integer (int32) |
WritebackTest
Section titled “WritebackTest”WritebackTest is one TestHostWriteback: the thresholds tested, both runs, and until when SetHostPolicy takes those thresholds for that host on the strength of it.
| Field | Type | What it is |
|---|---|---|
hostId | string | |
limitBytes | string (int64) | |
backgroundBytes | string (int64) | |
candidate | WritebackRun | candidate ran under the thresholds above, current under the ones the host held. |
current | WritebackRun | |
testedAt | Timestamp | |
expiresAt | Timestamp |
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.

