Types

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

AccessPerson

AccessPerson is somebody an access names: a user, and their keyring by the version it began at (ownerword.Person). name is how the dashboard shows them, and no part of what is signed.

Field	Type	What it is
userId	string
keyring	string
name	string

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

Allowed email type enum

One of: ALLOWED_EMAIL_TYPE_UNSPECIFIED, ALLOWED_EMAIL_TYPE_EMAIL, ALLOWED_EMAIL_TYPE_DOMAIN.

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

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.

BillDay

Field	Type	What it is
day	Timestamp	The day’s first instant, UTC.
services	list of ServiceCost	Costliest first.

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

BurstMode is how a workspace of a preset may grow past what it starts with.

One of: BURST_MODE_UNSPECIFIED, BURST_MODE_FIXED, BURST_MODE_TO_PRESET, BURST_MODE_TO_HOST.

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

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

What one item of the installation’s config file is.

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

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

DeviceLoginStatus

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

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)

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

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
workspaces	string (int64)	How many workspaces run it; one that nothing runs and is not the newest is collectable.
newest	boolean	Whether a start is given this one.

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)
newest	boolean	Whether a start now would choose this release.

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

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

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

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

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

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

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

Field	Type	What it is
uid	string
title	string

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 for the workspace’s team goes in the header, whole: “github” is an installation token of the team’s GitHub App, minted by the control plane (TeamService.SetForge).
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

HealthCheckResult

Field	Type	What it is
name	string
passed	boolean
value	string	Actual value from check
message	string	Error message if failed

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

Host

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.
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.

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

HostNetworkPolicy

Field	Type	What it is
hostId	string
rules	list of NetworkRule

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)

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.

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

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

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.

InstallationSettings

InstallationSettings contains global settings for the Spin installation

Field	Type	What it is
allowedImages	list of string	Whitelist of allowed images (empty = all allowed)
maxWorkspacesPerUser	integer (int32)	Maximum workspaces per user (0 = unlimited)
defaultNetworkTags	list of string	What a workspace created without a network tag of its own runs under, by policy name. Empty means “offline”, the policy every host has and which allows nothing: no value of this field means open. An installation that wants such a workspace out declares a policy saying what it may reach and names it here.
updatedAt	Timestamp
telemetryTracesKeepPercent	integer (int32)	What the installation’s collector keeps, decided at the collector (internal/controlplane/domain/telemetrypolicy). A trace with an error in any span is always kept, and so is one slower than telemetry_traces_slow_ms (0: none is kept for being slow); of the rest, telemetry_traces_keep_percent, 0 to 100 and 100 until an admin says otherwise.
telemetryTracesSlowMs	integer (int32)
telemetryMetricsDrop	list of string	The metrics that are not kept, by name; a pattern may begin or end with *.
telemetryPerVolumeHistograms	list of string	Read only: the metrics that cost most to keep, a histogram per volume, which a surface may offer to drop as one.
vscodeFetch	boolean	Whether the control plane fetches VS Code servers from Microsoft on its own: the newest stable release, looked for daily, and the server of a client’s commit the installation has not released. False, it fetches none, and a workspace is given the server the control plane’s image carries or one an administrator published.
workspaceTrashDays	integer (int32)	How many days a deleted workspace stays in the trash, whole, for its owner to undelete before it is erased: 0 is no trash, and 7 is what an installation that says nothing keeps.
identityAudiences	list of string	Who a workspace’s identity token may be for; empty is anybody. What the installation’s issuer gives, not who trusts it: a relying party still decides which subjects it admits.
volumeRpoSeconds	integer (int32)	How far behind the object store a workspace’s volume may fall, in seconds, where its preset does not say: what it commits on (v6 §11). 0 is none - it commits on its size and its snapshots alone - and 300 is what an installation that says nothing keeps.
diskReservePercent	integer (int32)	How a host’s disk is lent to workspaces. A volume holds what it wrote, not its size: a host is charged, per volume, the larger of disk_reserve_percent of its size and what it wrote, and takes new ones up to 80% of its device; disk_commit_max_percent bounds the sizes summed - every volume filling at once. 50 and 200 are what an installation that says nothing lends; 100 and 100 lends nothing past what the device holds.
diskCommitMaxPercent	integer (int32)
workspaceIdleSuspendMinutes	integer (int32)	How many minutes a running workspace may go unused - nobody working over its ssh, editor or forwarded ports, and its cores all but still - before it is suspended with its processes, which its next start resumes. 0 suspends none; 60 is what an installation that says nothing keeps, and a week is the most.
workspaceMaxRunningMinutes	integer (int32)	How many minutes a workspace may run at a stretch, used or not, before it is suspended the same way: a process that keeps its cores busy is use to the rule above, and this is what ends it. Counted from its machine’s start, which a resume is too. 0 caps none; 720 is what an installation that says nothing keeps, and a week is the most.
workspaceLeaseMaxMinutes	integer (int32)	How many minutes a process may keep its workspace awake at a stretch (a lease: spin-supervisor keep -- <cmd>, a .spin.yaml task with keep_awake). While a lease is held and within this of its start, nobody is asked, nothing idle is suspended, and the running cap waits for the lease’s end. 0 honours no lease; 480 is what an installation that says nothing keeps, and a week is the most.
teamSecretsRole	string	The IAM role a team’s secret kept in Secrets Manager or Parameter Store is read under, in a session tagged spin-team-id with the team: its policy lets that session read only what carries the same tag. Empty, no secret is kept as a reference.
agentsFetch	boolean	Whether the control plane fetches the agent CLIs - Claude Code and Codex - from their publishers on its own: the newest release of each, looked for daily. False, it fetches none, and a workspace is given the pair the control plane’s image carries or one an administrator published.

Job

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

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, empty when it was not recorded.
askedBy	string	The admin who ran it by hand; empty for a run the schedule started.

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

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

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

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

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

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

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

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.

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

OutsideShareState is how far a snapshot’s share outside its team is.

One of: OUTSIDE_SHARE_STATE_UNSPECIFIED, OUTSIDE_SHARE_STATE_PREPARING, OUTSIDE_SHARE_STATE_READY.

OwnerWord

OwnerWord is a workspace’s access, as its owner signed it with a key of their keyring (internal/ownerword): document is the access as framed JSON, signature the key’s SSH signature over it (sshsig, namespace “spin-access”) - what ssh-keygen -Y sign writes, so a FIDO2 key signs one through ssh-agent.

Field	Type	What it is
document	string (byte)
signature	string (byte)

PageRequest

Pagination for list requests

Field	Type	What it is
pageSize	integer (int32)
pageToken	string

PageResponse

Field	Type	What it is
nextPageToken	string
totalCount	integer (int32)

PendingSignature

PendingSignature is one document the caller is asked to sign.

Field	Type	What it is
kind	SignatureKind
subjectId	string	subject_id is the user, the team or the workspace the document is of.
document	string (byte)	document is the document to sign, as framed JSON: what the client shows and signs as it is.
signers	list of string	signers are the keys, in authorized_keys form, any one of which may sign it.
summary	string	summary is a line saying what it changes, for a list: the document itself is what to read.

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

One of: PLATFORM_IMAGE_ARTIFACT_UNSPECIFIED, PLATFORM_IMAGE_ARTIFACT_BASE, PLATFORM_IMAGE_ARTIFACT_SUPERVISOR.

PlatformImageState

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

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.

One of: PORT_ACCESS_UNSPECIFIED, PORT_ACCESS_PRIVATE, PORT_ACCESS_WHITELIST, PORT_ACCESS_PUBLIC.

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

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
settingsDigest	string	The SHA-256 of the settings its word approved, and of the checkout’s .spin.yaml at the commit.
claim	string (byte)	What its host signed of it (PrebuildClaim), once it is ready.
log	string	The tail of what its build said, and why it failed.
error	string
createdAt	Timestamp
builtAt	Timestamp

PrebuildState

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

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.

Project

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

Field	Type	What it is
id	string
teamId	string
name	string
slug	string	What a person names it by in the team: 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 admin who last named the refs.

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.

RateLimitSettings

RateLimitSettings configures API rate limiting

Field	Type	What it is
enabled	boolean	Enable rate limiting
authRequestsPerMinute	integer (int32)	Auth endpoints (login, token exchange, etc.) Requests per minute for auth endpoints
authBurst	integer (int32)	Burst allowance for auth endpoints
apiRequestsPerMinute	integer (int32)	API endpoints (all other endpoints) Requests per minute for API endpoints
apiBurst	integer (int32)	Burst allowance for API endpoints

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)

RegistrationMode

Registration mode enum

One of: REGISTRATION_MODE_UNSPECIFIED, REGISTRATION_MODE_OPEN, REGISTRATION_MODE_WHITELIST, REGISTRATION_MODE_CLOSED.

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

RekeyState is how far a disk’s re-key is.

One of: REKEY_STATE_UNSPECIFIED, REKEY_STATE_PENDING, REKEY_STATE_COPYING, REKEY_STATE_READY.

RepositoryConfig

The repository a workspace opened, as its guest clones it: the project’s URL, the ref the workspace was opened at, and where on the disk it goes (projects.CheckoutPath). Part of the settings the owner approves, as the environment is: a disk is written to only as its owner said.

Field	Type	What it is
url	string
ref	string
path	string
authorName	string	Who the checkout’s commits are by: the workspace’s owner’s name and email as the installation knows them, set as the checkout’s own user.name and user.email - the push goes as the team’s app, and the commit says the person. Empty is neither set.
authorEmail	string
commit	string	commit is the one a prebuild’s build checks out and runs create at; empty for a workspace a person opens, which follows the ref.
fromCommit	string	from_commit is the commit the disk’s checkout already is, for a disk cloned from a prebuild: the guest holds the tree to it (git fsck, no tracked file changed) before it fetches.
prebuildId	string	The prebuild the disk is a clone of, and the SHA-256 of the claim its host signed of it (PrebuildClaim): what the owner approves when the open was from one.
prebuildClaimDigest	string
pullRef	string	pull_ref is a pull request’s ref as its forge serves it (refs/pull/<n>/head, GitLab’s refs/merge-requests/<n>/head), fetched once ref is cloned and checked out as pr-<n> or mr-<n>; empty for a workspace that opens at ref itself.

ResolverLookup

Field	Type	What it is
name	string
outcome	string	filtered, refused, upstream_failed or malformed.
at	Timestamp

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 (InstallationSettings.volume_rpo_seconds).

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.

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	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.

SecuritySettings

SecuritySettings contains security-related configuration

Field	Type	What it is
rateLimit	RateLimitSettings	Rate limiting configuration
sessionDurationHours	integer (int32)	Session configuration Session token lifetime in hours (default: 168 = 7 days)
allowWorkspaceSharing	boolean	Access control Allow users to share workspaces
allowPublicWorkspaces	boolean	Allow publicly accessible workspace URLs
updatedAt	Timestamp

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

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

Field	Type	What it is
start	Timestamp
traces	string (int64)
failedTraces	string (int64)

SignatureKind

One of: SIGNATURE_KIND_UNSPECIFIED, SIGNATURE_KIND_KEYRING, SIGNATURE_KIND_ROSTER.

SignedDocument

SignedDocument is a document as framed JSON and an SSH signature over it (sshsig) - what ssh-keygen -Y sign writes, so a FIDO2 key signs one through ssh-agent, and a passkey’s WebAuthn assertion is one too (internal/sshauth).

Field	Type	What it is
document	string (byte)
signature	string (byte)

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.

SnapshotAccessType

Access type for snapshots

One of: SNAPSHOT_ACCESS_TYPE_UNSPECIFIED, SNAPSHOT_ACCESS_TYPE_OWNER, SNAPSHOT_ACCESS_TYPE_SHARED, SNAPSHOT_ACCESS_TYPE_PUBLIC.

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

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.

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

Span

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.

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

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

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

Field	Type	What it is
objects	string (int64)
bytes	string (int64)

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 image’s ref, or the extension and its version.
workspaceId	string	The workspace’s, for a workspace’s disk.
ownerEmail	string
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 or a release that may not go.

StoredVolumeKind

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.

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

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

Team

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)

TeamForge

Field	Type	What it is
forge	string
appId	string (int64)
installationId	string (int64)
apiUrl	string
hosts	list of string
updatedAt	Timestamp

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

TeamMember

Field	Type	What it is
userId	string
email	string
name	string
role	TeamRole
joinedAt	Timestamp

TeamRole

Team member role enum

One of: TEAM_ROLE_UNSPECIFIED, TEAM_ROLE_OWNER, TEAM_ROLE_ADMIN, TEAM_ROLE_MEMBER.

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.

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)

User

Field	Type	What it is
id	string
email	string
name	string
avatarUrl	string
subscriptionTier	string
createdAt	Timestamp
isInstanceAdmin	boolean
disabled	boolean
disabledReason	string

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

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

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

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

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 what runs is in the object store. 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.
accessSigned	boolean	access_signed is whether its owner has signed an access of it: nobody logs in until then.
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.

WorkspaceAction

WorkspaceAction is an act a person can ask of a workspace.

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.

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)

WorkspaceDurability

WorkspaceDurability is what of a running workspace is published, so it survives its host.

Field	Type	What it is
lastPublishedAt	Timestamp	last_published_at is when its last commit reached the object store, as its host last said.
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.

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

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.

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.

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.

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

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.

WorkspacePhase

WorkspacePhase is what a host is doing to bring a workspace up.

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

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

WorkspaceProxyStatus

Proxy status for workspace access

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

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

Workspace states

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.

WorkspaceSuspendFailure

Field	Type	What it is
workspaceId	string
error	string

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

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

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

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