Entities
Every persisted object, its fields, its relationships and where it is stored.
Relationships
Organization
| Field | Type | Notes |
|---|---|---|
id | org_<base62> | |
name | string | |
slug | string | Unique, used in dashboard URLs |
billing_email | string | |
price_list_id | pl_… | Effective rates; defaults to the public list |
payment_mode | enum | prepaid · postpaid · invoiced |
credit_balance_minor | int | Minor currency units, prepaid only |
spend_cap_minor | int, nullable | Hard monthly ceiling |
spend_cap_action | enum | block_new · block_and_stop |
residency | object | Allowed regions, enforced everywhere |
status | enum | active · past_due · suspended · closed |
created_at | timestamp |
Store: global Postgres.
Project
| Field | Type | Notes |
|---|---|---|
id | proj_<base62> | |
organization_id | org_… | |
name, slug | string | Slug unique within the organization |
default_region | enum | |
default_policy_id | pol_…, nullable | Applied to sessions that name no policy |
quotas | object | Per-tier concurrency and creation rate |
environment | enum | production · staging · development; affects defaults, not capability |
archived_at | timestamp, nullable | Archived projects refuse new sessions |
Store: global Postgres.
ApiKey
| Field | Type | Notes |
|---|---|---|
id | key_<base62> | |
project_id | proj_… | |
kind | enum | secret · publishable |
prefix | string | First 12 characters, shown in UI, used for lookup sharding |
hash | string | Argon2id of the full key; the plaintext is never stored |
scopes | string[] | sessions:write, usage:read, … |
expires_at | timestamp, nullable | |
last_used_at | timestamp, nullable | Written at most once a minute |
revoked_at | timestamp, nullable |
Store: global Postgres.
EndUser
| Field | Type | Notes |
|---|---|---|
id | eu_<base62> | |
organization_id | org_… | Scoped to the organization, not the project |
external_id | string | The customer's own identifier; unique per organization |
metadata | object | Up to 16 keys, searchable |
quotas | object, nullable | Per-end-user concurrency and spend caps |
status | enum | active · blocked |
End users are created implicitly on first use, so an unknown end_user_id on a session creates the
record rather than failing. That keeps attribution from being a setup step a customer can forget.
Store: global Postgres.
Session
| Field | Type | Notes |
|---|---|---|
id | sess_<base62> | |
project_id | proj_… | |
end_user_id | eu_…, nullable | Immutable after creation |
tier | 0–4 | Immutable |
state | enum | See state machines |
state_reason | string, nullable | Populated on every non-trivial transition |
template_digest | string | Resolved content hash, not the friendly name |
region, zone | string | Immutable |
node_id | string, nullable | Internal; not exposed to customers |
resources | object | vcpu, memory_mib, disk_gib, gpu, size_class |
volume_id | vol_…, nullable | |
policy_digest | string | The compiled artifact actually enforced |
idle_timeout_s, max_lifetime_s | int | |
restored_from | snap_…, nullable | |
cold_start | bool | |
preemptible | bool | |
labels | object | Up to 16 keys, used for affinity and reporting |
created_at, started_at, ended_at, last_activity_at | timestamp |
Store: regional Postgres, with a hot index in Redis for gateway routing.
Run
| Field | Type | Notes |
|---|---|---|
id | run_<base62> | |
session_id | sess_… | Present even for one-shot runs, where the session is implicit |
kind | enum | code · command · browser · desktop · tool |
spec | object | Code and runtime, or argv and cwd and env, or an action list |
status | enum | queued · running · succeeded · failed · timed_out · cancelled |
exit_code | int, nullable | |
stdout_ref, stderr_ref | string, nullable | Object-storage pointers; inline when small |
started_at, finished_at, duration_ms | — | |
usage | object | Per-run attribution of the session's meters |
Store: regional Postgres; output bodies in object storage.
Template
| Field | Type | Notes |
|---|---|---|
id | tpl_<base62> | |
project_id | proj_…, nullable | Null means platform-owned |
name, version | string | name is a moving pointer, digest is the identity |
digest | string | sha256:… |
tier_min | 0–4 | The lowest tier this template can run at |
spec | object | Base image, package list, build steps, environment |
size_classes | string[] | Which classes have pre-booted snapshots |
warm_pool | object, nullable | Requested depth per region, if pinned |
scan | object | Vulnerability scan result at publish |
state | enum | building · ready · failed · deprecated |
Store: global Postgres; layers and snapshots in regional caches and object storage.
Volume
| Field | Type | Notes |
|---|---|---|
id | vol_<base62> | |
project_id | proj_… | |
end_user_id | eu_…, nullable | |
region, zone | string | Zonal — constrains placement |
size_gib | int | Resizable up only |
attached_session_id | sess_…, nullable | At most one |
state | enum | creating · available · attached · deleting · error |
Store: regional Postgres; data on networked block storage.
Snapshot
| Field | Type | Notes |
|---|---|---|
id | snap_<base62> | |
project_id | proj_… | |
source_session_id | sess_… | |
tier | 0–4 | Restorable only at the same tier |
include_memory | bool | |
size_gib | number | Deduplicated, compressed — what is billed |
logical_size_gib | number | Uncompressed filesystem size |
parent_snapshot_id | snap_…, nullable | Dedupe chain |
region | string | Copies create new snapshots in the destination |
state | enum | creating · uploading · ready · deleting · error |
expires_at | timestamp, nullable | From retention_days |
Store: regional Postgres; blocks in object storage.
Policy
| Field | Type | Notes |
|---|---|---|
id | pol_<base62> | |
project_id | proj_… | |
version | int | Monotonic; policies are versioned, never edited in place |
egress, cli_allowlist, tool_allowlist, secret_scope | object | |
digest | string | Hash of the compiled artifact the data plane enforces |
Store: global Postgres; compiled artifacts cached regionally by digest.
BrowserProfile
| Field | Type | Notes |
|---|---|---|
id | bprof_<base62> | |
project_id | proj_… | |
end_user_id | eu_…, nullable | Strongly recommended — a profile is one identity |
region | string | Profiles do not cross regions |
size_bytes | int | |
last_used_at | timestamp |
Encrypted at rest with a per-organization key. Contains live session cookies, so it is treated as a credential.
Store: global Postgres for metadata; data in regional object storage.
UsageEvent
| Field | Type | Notes |
|---|---|---|
session_id | sess_… | |
meter | string | tier2.session_s, cpu_ms, egress_gb, … |
window_start | timestamp | Minute-aligned |
quantity | number | |
organization_id, project_id, end_user_id, region, tier | — | Denormalised for aggregation |
source | enum | node · proxy · storage · control |
Dedupe key: (session_id, meter, window_start). Store: Kafka, then ClickHouse.
RatedUsage
| Field | Type | Notes |
|---|---|---|
organization_id, project_id, end_user_id | — | |
meter, quantity | — | |
window_start | timestamp | Hour-aligned after rollup |
unit_price_minor, amount_minor, currency | — | |
price_list_id, price_list_version | — | Rating is reproducible from these |
Store: ClickHouse, with daily rollups to Postgres for invoicing.
Invoice
| Field | Type | Notes |
|---|---|---|
id | inv_<base62> | |
organization_id | org_… | |
period_start, period_end | date | |
lines | InvoiceLine[] | Per meter, optionally per project or end user |
subtotal_minor, credits_applied_minor, tax_minor, total_minor | int | |
status | enum | draft · finalized · paid · past_due · void |
finalized_at | timestamp, nullable | Immutable from this point |
Store: global Postgres; PDFs in object storage.
AuditEntry
| Field | Type | Notes |
|---|---|---|
id | aud_<base62> | |
organization_id | org_… | |
actor | object | Member, API key, or platform operator |
action | string | api_key.created, policy.updated, session.force_terminated, … |
target | object | Type and ID |
before, after | object, nullable | Redacted diff for mutations |
prev_hash, hash | string | Hash chain — tampering is detectable |
Append-only, seven-year retention. Store: global Postgres plus an object-storage archive.
Conventions across every entity
- Soft delete where billing depends on it. Volumes, snapshots and sessions keep a tombstone so a past invoice can still be explained.
metadataandlabelsare customer-owned, limited to 16 keys and 512 bytes per value.metadatais for the customer's own reference;labelsparticipate in placement and reporting.- Timestamps are RFC 3339 in UTC, always with millisecond precision.
- Money is integer minor units plus a currency code. No floats anywhere in a billing path.
- Digests, not names, are the identity for templates and policies. Names are pointers that move; what actually ran is recorded by digest.