Sessions

Parameters

Response200 OK

dataarray of objectsRequired

data[].branchstring or null

data[].clientsarray of objects

data[].clients[].clientstringRequired

the daemon's label: mcp:<pid>, cli, browser

data[].clients[].open_streamsintegerRequired

data[].clients[].servicestringRequired

data[].clients[].streams_last_minintegerRequired

data[].clients[].waitingintegerRequired

streams held while the service is not ready

data[].created_atstring (date-time)Required

data[].diagnostic_countsarray of objects

per service; the records come through the diagnostics stream

data[].diagnostic_counts[].digeststringRequired

over a salt only the worker holds and the records: changes when they do

data[].diagnostic_counts[].errorsintegerRequired

data[].diagnostic_counts[].generationintegerRequired

data[].diagnostic_counts[].servicestringRequired

data[].diagnostic_counts[].warningsintegerRequired

data[].dotfilesobject or null

the owner's dotfiles as dev up decided them; null when the owner set none

data[].dotfiles.detailstring or null

data[].dotfiles.nextstring or null

data[].dotfiles.reasonstring or null

One of policy_off, host_not_allowed, vendor, egress_ceiling, egress_denied, agent_session

data[].dotfiles.repostring or null

data[].dotfiles.statestringRequired

One of granted, skipped, unset

data[].epochintegerRequired

data[].expires_atstring (date-time) or null

while live: the stop of the policy's lifecycle.max_lifetime_secs, whatever the activity, fixed at create and at a start; null is no limit. paused: when its checkpoint expires and the session ends

data[].exposearray of objectsRequired

data[].expose[].kindstringRequired

internal: reached only by worker-side services through the guest; never bound locally, never a tunnel stream or an SSH forwardOne of http, tcp, internal

data[].expose[].namestringRequired

data[].expose[].portintegerRequired

data[].expose[].targetintegerRequired

data[].from_sessionstring or null

source checkpoint: the lost session this one resumed

data[].generationinteger

data[].healthobject

the worst service's

data[].health.detailstring

data[].health.nextstring

data[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

data[].health.statestringRequired

One of healthy, degraded, failed

data[].idstringRequired

data[].idle_expires_atstring (date-time) or null

data[].labelstringRequired

data[].last_activity_atstring (date-time)Required

data[].last_checkpoint_atstring (date-time) or null

writer cloud: the last checkpoint, so a person sees what a lost host could cost

data[].last_pushobject

dev.sessions.get, writer cloud: the newest push to the session's branch; absent before the first

data[].last_push.atstring (date-time)Required

data[].last_push.change_request_urlstring or nullRequired

data[].last_push.newstringRequired

the commit it pushed

data[].last_push.referencestringRequired

data[].latencyarray of objects

data[].latency[].atstring

added by the cli when it merges the daemon's hopsOne of worker, this_machine

data[].latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

data[].latency[].last_msintegerRequired

data[].latency[].overbooleanRequired

data[].latency[].p50_msintegerRequired

data[].latency[].p95_msintegerRequired

data[].latency[].samplesintegerRequired

data[].latency[].target_msinteger or null

data[].needs_openinteger

needs nobody answered or dismissed yet: the session needs its person (dev.sessions.needs.list)

data[].ownerstring

data[].parametersarray of objects

the template's parameters as resolved at create, in the template's order; empty for a template without any

data[].parameters[].mutablebooleanRequired

data[].parameters[].namestringRequired

data[].parameters[].valuestringRequired

data[].pausingboolean

stopping: the stop keeps the session, which becomes paused once its checkpoint is stored

data[].phasestring

One of creating, placing, syncing, preparing, starting, ready

data[].policyobject

the policy version the session started with and what it allows

data[].policy.clipboardstring

One of allow, deny

data[].policy.downloadstring

One of allow, deny

data[].policy.lifecycleobject

the limits the session started under

data[].policy.lifecycle.auto_stopstring

what an idle stop, the budget's hard stop and max_lifetime_secs do to a cloud-writer session: pause keeps it with its checkpoint for dev.sessions.start, end ends it; a local writer always endsOne of pause, end

data[].policy.lifecycle.idle_max_secsinteger

at least idle_min_secs; idle_secs and a person's idle_secs lie between; a template that names an idle over it is refused at dev.sessions.up (422 template_invalid, finding idle_over_policy with its next), the 60 min default is pulled down

data[].policy.lifecycle.idle_min_secsinteger

data[].policy.lifecycle.idle_secsinteger or null

the idle stop when the person names none; null is the template's (60 min unless it says)

data[].policy.lifecycle.lifetime_warning_secsinteger

shorter than max_lifetime_secs

data[].policy.lifecycle.max_lifetime_secsinteger or null

from create to stop, whatever the activity; null, the default, is no limit; ciresk dev policy preset no-local-checkout suggests 86400

data[].policy.lifecycle.max_session_cpus_milliinteger or null

the largest cpu reservation, in thousandths of a cpu; null is the worker's own limit (422 session_too_large)

data[].policy.lifecycle.max_session_memory_bytesinteger or null

the largest memory reservation one template may declare; null is the worker's own limit (422 session_too_large)

data[].policy.lifecycle.sessions_per_orginteger

live sessions of the organisation, never above the installation's own ceiling (409 org_session_limit)

data[].policy.lifecycle.sessions_per_personinteger

live sessions one person and their agents hold; at most sessions_per_org (409 person_session_limit)

data[].policy.local_syncstring

One of allow, deny

data[].policy.port_forwardstring

One of allow, deny

data[].policy.sharingstring

One of false, view, use

data[].policy.sshstring

One of allow, deny

data[].policy.ssh_execstring

One of allow, deny

data[].policy.uploadstring

One of allow, deny

data[].policy.versioninteger

data[].presetstring or null

the preset the session was created with

data[].queueobject

data[].queue.per_principalintegerRequired

data[].queue.queuedarray of objectsRequired

data[].queue.queued[].clientstringRequired

data[].queue.queued[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

data[].queue.queued[].opstringRequired

One of exec, reset, restart, login, checkpoint

data[].queue.queued[].positionintegerRequired

0 while running

data[].queue.queued[].principalstringRequired

the stream's verified principal

data[].queue.queued[].waiting_msintegerRequired

data[].queue.runningarray of objectsRequired

data[].queue.running[].clientstringRequired

data[].queue.running[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

data[].queue.running[].opstringRequired

One of exec, reset, restart, login, checkpoint

data[].queue.running[].positionintegerRequired

0 while running

data[].queue.running[].principalstringRequired

the stream's verified principal

data[].queue.running[].waiting_msintegerRequired

data[].queue.slotsintegerRequired

data[].refused_pathsobject

data[].refused_paths.pathsarray of strings

data[].refused_paths.totalinteger

data[].relay_urlstring (uri)

data[].requesterstring

data[].requester_agentstring or null

the agent that opened the session as records name it: the verified agent and the harness its Ciresk-Agent header named; display only, null for a person acting themselves and for a session opened before

data[].resourcesobject

dev.sessions.get only: the session's cpu, memory and disk now, against the template's resources, and one sample a minute for the last hour, oldest first. cpu and memory are the services' metrics together, disk the bytes the session's directory holds; a value the worker does not report is null now and left out of a sample, never 0. the hops now are the session's latency

data[].resources.cpu_milliinteger or null

thousandths of a cpu

data[].resources.disk_bytesinteger or null

data[].resources.historyarray of objectsRequired

data[].resources.history[].atstring (date-time)Required

data[].resources.history[].cpu_milliinteger

data[].resources.history[].disk_bytesinteger

data[].resources.history[].latencyarray of objects

data[].resources.history[].memory_bytesinteger

data[].resources.limitsobjectRequired

data[].resources.limits.cpus_milliintegerRequired

data[].resources.limits.disk_bytesintegerRequired

data[].resources.limits.memory_bytesintegerRequired

data[].resources.limits.memory_max_bytesintegerRequired

data[].resources.memory_bytesinteger or null

data[].resources.sampled_atstring (date-time) or null

data[].rolestring

the caller's role; left out for a session dev.sessions.list with scope org shows to an audit reader who is neither its owner nor a memberOne of owner, use, view

data[].rootstring or null

data[].seedobject or null

data[].seed.generationintegerRequired

data[].seed.rootstring or null

data[].seed.stalebooleanRequired

a path under data.inputs changed since; next: ciresk dev reset --rebuild

data[].seed.taken_atstring (date-time)Required

data[].seed.volumesarray of stringsRequired

data[].servicesarray of objectsRequired

data[].services[].close_reasonstring or null

One of idle, oom, crashed, requested, kill

data[].services[].detailstring or null

data[].services[].healthobjectRequired

; every non-healthy state carries the exact next command

data[].services[].health.detailstring

data[].services[].health.nextstring

data[].services[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

data[].services[].health.statestringRequired

One of healthy, degraded, failed

data[].services[].metricsobject or null

data[].services[].metrics.baseline_rss_bytesinteger or null

data[].services[].metrics.cache_bytesintegerRequired

data[].services[].metrics.cpu_milliintegerRequired

data[].services[].metrics.fdsintegerRequired

data[].services[].metrics.hmr_p50_msinteger or null

data[].services[].metrics.inotify_watchesintegerRequired

data[].services[].metrics.io_bytesinteger

bytes the container's processes read and wrote (cgroup io.stat), sampled while it starts

data[].services[].metrics.rss_bytesintegerRequired

data[].services[].metrics.sampled_atstring (date-time)Required

data[].services[].namestringRequired

data[].services[].restartsintegerRequired

data[].services[].servinginteger or null

the generation this service serves

data[].services[].started_atstring (date-time)

when the running process started; how long a start or a prepare step has taken

data[].services[].statestringRequired

One of waiting, starting, ready, completed, failed, stopped, not_started

data[].sourcestring

One of worktree, trunk, branch, checkpoint

data[].ssh_host_keystring or null

the session's openssh host key line

data[].statestringRequired

paused: stopped with its checkpoint and kept; dev.sessions.start places it againOne of pending, starting, ready, degraded, disconnected, lost, stopping, paused, stopped, failed

data[].state_reasonstring or null

why the session is in its state. pending: no_capacity, worker_starting or no_worker, or agent_exit_unavailable while no worker that runs the agent's own exit asks for it; lost: worker_lost; stopping, paused and stopped: requested, idle, max_lifetime, budget, kill, access_changed, recreated, checkpoint_expired (a paused session's checkpoint expired, dev), or stopped when the holder stopped with no reason; failed: the worker's failure code, template_digest_mismatch, start_failed, services_failed or an infrastructure code such as disk_full or toolchain_unavailable. a service that never gets ready leaves the session degraded with no reason (ciresk dev up answers the CLI error service_not_ready)

data[].switchobject or null

data[].switch.fromstring or null

data[].switch.phasestring

One of applying, preparing, restarting

data[].switch.tostring or null

data[].templatestringRequired

data[].template_digeststring

data[].timingsobject

milliseconds from create, derived from the session's events

data[].timings.create_msinteger

data[].timings.lease_msinteger

data[].timings.prepare_msinteger

data[].timings.ready_msinteger

data[].timings.sync_msinteger

data[].tree_idstring

data[].unpushed_filesinteger or null

writer cloud: files changed since the trunk tree, until forge pushes them

data[].viewobject

whether the session's view hides any path; never which

data[].view.policy_versioninteger

data[].view.restrictedboolean

data[].web_gatewayboolean

dev.sessions.get only: whether the installation serves sessions in the browser (a preview domain is configured); the console offers no browser button without it

data[].weightobject

data[].weight.cpus_milliintegerRequired

data[].weight.disk_bytesintegerRequired

data[].weight.memory_bytesintegerRequired

data[].weight.memory_max_bytesintegerRequired

data[].workerstring or null

data[].worker_releasestring or null

the release the holding worker registered with (its software_version label), so a rollout is visible

data[].workersstring

only on a pending session whose state_reason is no_worker because the organisation runs on its own workers: nothing of the cell starts one, so a client says to start one of the organisation's enrolled workers; absent otherwiseOne of customer

data[].workspaceobject or null

data[].workspace.bytes_materialisedintegerRequired

data[].workspace.files_materialisedintegerRequired

data[].workspace.files_totalintegerRequired

data[].workspace.recent_waitsarray of stringsRequired

data[].workspace.wait_p95_msintegerRequired

data[].workspace.waits_last_minintegerRequired

data[].writerstringRequired

One of local, cloud

has_morebooleanRequired

next_cursorstring or null

Errors

• 400an error
• 401an error
• 403not_allowed: scope org without dev:audit.read, or from an agent

Request body

branchstring or null

source worktree: the branch the worktree is on, whose writer row it takes; source branch: the ref whose newest ci run's tree it starts from (required); never with trunk or checkpoint

device_public_keystring

ed25519 public key, base64url; part of the session key, granted on 201 only; source worktree only

from_sessionstring or null

source checkpoint: the ended cloud-writer session (lost, stopped or failed, not killed) of the same repository whose last checkpoint root and branch it continues, ending a lost one as stopped with state_reason resumed; only that session's owner may resume it (403 not_allowed otherwise, 409 no_checkpoint when it is running, killed or has no checkpoint, 409 already_resumed when another session continued it, 422 validation_failed for another repository's session; dev)

headstring or null

the commit at HEAD

idle_secsinteger

the person's idle stop for this session; within the policy's lifecycle bounds (422 idle_out_of_bounds), else the policy's lifecycle.idle_secs, else the template's, pulled into the bounds

labelstringRequired

lazyboolean

materialise file content on first read

local_portsmap of integer

per http port of the template the client's machine refuses to bind with nothing listening (a Windows excluded port range), the stable fallback it serves instead: keys are the template's port numbers; the compile makes the fallback the session's port and every {origin:p}, and aliases it to the in-pod port in the pod; a key that is no http port of the template, or a fallback the template already uses, is 422 template_invalid with the finding local_port_unknown or local_port_taken; absent or empty when no port moved

parametersmap of string

values of the template's parameters by name, as strings its declaration types: over the defaults and the preset's; never a secret

prepare_locksmap of string

per shared prepare step, the client's lock of the step's inputs in the tree it pushes: keys are step names; the worker mounts the prebuilt layer of exactly that lock when it holds one; a hint, since a wrong lock only misses

presetstring or null

a preset of the template, whose values apply before parameters

recreateboolean

remote_fingerprintstringRequired

rootstring or null

sourcestring

trunk: a remote session from the repository's trunk generation, no local tree; branch: a remote session from the tree of ci's newest finished run on branch; checkpoint: a cloud-writer session continued from an ended one's last checkpoint, on its branchOne of worktree, trunk, branch, checkpoint

templatestringRequired

template_b64string

the dev file's bytes as committed in the tree

template_digeststring

template_pathstring

tree_idstring

ci-v1.0.7 per-worktree identity

writerstringRequired

local with source worktree, cloud with source trunk, branch or checkpointOne of local, cloud

Response200 OK

branchstring or null

clientsarray of objects

clients[].clientstringRequired

the daemon's label: mcp:<pid>, cli, browser

clients[].open_streamsintegerRequired

clients[].servicestringRequired

clients[].streams_last_minintegerRequired

clients[].waitingintegerRequired

streams held while the service is not ready

created_atstring (date-time)Required

diagnostic_countsarray of objects

per service; the records come through the diagnostics stream

diagnostic_counts[].digeststringRequired

over a salt only the worker holds and the records: changes when they do

diagnostic_counts[].errorsintegerRequired

diagnostic_counts[].generationintegerRequired

diagnostic_counts[].servicestringRequired

diagnostic_counts[].warningsintegerRequired

dotfilesobject or null

the owner's dotfiles as dev up decided them; null when the owner set none

dotfiles.detailstring or null

dotfiles.nextstring or null

dotfiles.reasonstring or null

One of policy_off, host_not_allowed, vendor, egress_ceiling, egress_denied, agent_session

dotfiles.repostring or null

dotfiles.statestringRequired

One of granted, skipped, unset

epochintegerRequired

expires_atstring (date-time) or null

while live: the stop of the policy's lifecycle.max_lifetime_secs, whatever the activity, fixed at create and at a start; null is no limit. paused: when its checkpoint expires and the session ends

exposearray of objectsRequired

expose[].kindstringRequired

internal: reached only by worker-side services through the guest; never bound locally, never a tunnel stream or an SSH forwardOne of http, tcp, internal

expose[].namestringRequired

expose[].portintegerRequired

expose[].targetintegerRequired

from_sessionstring or null

source checkpoint: the lost session this one resumed

generationinteger

healthobject

the worst service's

health.detailstring

health.nextstring

health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

health.statestringRequired

One of healthy, degraded, failed

idstringRequired

idle_expires_atstring (date-time) or null

labelstringRequired

last_activity_atstring (date-time)Required

last_checkpoint_atstring (date-time) or null

writer cloud: the last checkpoint, so a person sees what a lost host could cost

last_pushobject

dev.sessions.get, writer cloud: the newest push to the session's branch; absent before the first

last_push.atstring (date-time)Required

last_push.change_request_urlstring or nullRequired

last_push.newstringRequired

the commit it pushed

last_push.referencestringRequired

latencyarray of objects

latency[].atstring

added by the cli when it merges the daemon's hopsOne of worker, this_machine

latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

latency[].last_msintegerRequired

latency[].overbooleanRequired

latency[].p50_msintegerRequired

latency[].p95_msintegerRequired

latency[].samplesintegerRequired

latency[].target_msinteger or null

needs_openinteger

needs nobody answered or dismissed yet: the session needs its person (dev.sessions.needs.list)

ownerstring

parametersarray of objects

the template's parameters as resolved at create, in the template's order; empty for a template without any

parameters[].mutablebooleanRequired

parameters[].namestringRequired

parameters[].valuestringRequired

pausingboolean

stopping: the stop keeps the session, which becomes paused once its checkpoint is stored

phasestring

One of creating, placing, syncing, preparing, starting, ready

policyobject

the policy version the session started with and what it allows

policy.clipboardstring

One of allow, deny

policy.downloadstring

One of allow, deny

policy.lifecycleobject

the limits the session started under

policy.lifecycle.auto_stopstring

what an idle stop, the budget's hard stop and max_lifetime_secs do to a cloud-writer session: pause keeps it with its checkpoint for dev.sessions.start, end ends it; a local writer always endsOne of pause, end

policy.lifecycle.idle_max_secsinteger

at least idle_min_secs; idle_secs and a person's idle_secs lie between; a template that names an idle over it is refused at dev.sessions.up (422 template_invalid, finding idle_over_policy with its next), the 60 min default is pulled down

policy.lifecycle.idle_min_secsinteger

policy.lifecycle.idle_secsinteger or null

the idle stop when the person names none; null is the template's (60 min unless it says)

policy.lifecycle.lifetime_warning_secsinteger

shorter than max_lifetime_secs

policy.lifecycle.max_lifetime_secsinteger or null

from create to stop, whatever the activity; null, the default, is no limit; ciresk dev policy preset no-local-checkout suggests 86400

policy.lifecycle.max_session_cpus_milliinteger or null

the largest cpu reservation, in thousandths of a cpu; null is the worker's own limit (422 session_too_large)

policy.lifecycle.max_session_memory_bytesinteger or null

the largest memory reservation one template may declare; null is the worker's own limit (422 session_too_large)

policy.lifecycle.sessions_per_orginteger

live sessions of the organisation, never above the installation's own ceiling (409 org_session_limit)

policy.lifecycle.sessions_per_personinteger

live sessions one person and their agents hold; at most sessions_per_org (409 person_session_limit)

policy.local_syncstring

One of allow, deny

policy.port_forwardstring

One of allow, deny

policy.sharingstring

One of false, view, use

policy.sshstring

One of allow, deny

policy.ssh_execstring

One of allow, deny

policy.uploadstring

One of allow, deny

policy.versioninteger

presetstring or null

the preset the session was created with

queueobject

queue.per_principalintegerRequired

queue.queuedarray of objectsRequired

queue.queued[].clientstringRequired

queue.queued[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.queued[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.queued[].positionintegerRequired

0 while running

queue.queued[].principalstringRequired

the stream's verified principal

queue.queued[].waiting_msintegerRequired

queue.runningarray of objectsRequired

queue.running[].clientstringRequired

queue.running[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.running[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.running[].positionintegerRequired

0 while running

queue.running[].principalstringRequired

the stream's verified principal

queue.running[].waiting_msintegerRequired

queue.slotsintegerRequired

refused_pathsobject

refused_paths.pathsarray of strings

refused_paths.totalinteger

relay_urlstring (uri)

requesterstring

requester_agentstring or null

the agent that opened the session as records name it: the verified agent and the harness its Ciresk-Agent header named; display only, null for a person acting themselves and for a session opened before

resourcesobject

dev.sessions.get only: the session's cpu, memory and disk now, against the template's resources, and one sample a minute for the last hour, oldest first. cpu and memory are the services' metrics together, disk the bytes the session's directory holds; a value the worker does not report is null now and left out of a sample, never 0. the hops now are the session's latency

resources.cpu_milliinteger or null

thousandths of a cpu

resources.disk_bytesinteger or null

resources.historyarray of objectsRequired

resources.history[].atstring (date-time)Required

resources.history[].cpu_milliinteger

resources.history[].disk_bytesinteger

resources.history[].latencyarray of objects

resources.history[].latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

resources.history[].latency[].p50_msintegerRequired

resources.history[].memory_bytesinteger

resources.limitsobjectRequired

resources.limits.cpus_milliintegerRequired

resources.limits.disk_bytesintegerRequired

resources.limits.memory_bytesintegerRequired

resources.limits.memory_max_bytesintegerRequired

resources.memory_bytesinteger or null

resources.sampled_atstring (date-time) or null

rolestring

the caller's role; left out for a session dev.sessions.list with scope org shows to an audit reader who is neither its owner nor a memberOne of owner, use, view

rootstring or null

seedobject or null

seed.generationintegerRequired

seed.rootstring or null

seed.stalebooleanRequired

a path under data.inputs changed since; next: ciresk dev reset --rebuild

seed.taken_atstring (date-time)Required

seed.volumesarray of stringsRequired

servicesarray of objectsRequired

services[].close_reasonstring or null

One of idle, oom, crashed, requested, kill

services[].detailstring or null

services[].healthobjectRequired

; every non-healthy state carries the exact next command

services[].health.detailstring

services[].health.nextstring

services[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

services[].health.statestringRequired

One of healthy, degraded, failed

services[].metricsobject or null

services[].metrics.baseline_rss_bytesinteger or null

services[].metrics.cache_bytesintegerRequired

services[].metrics.cpu_milliintegerRequired

services[].metrics.fdsintegerRequired

services[].metrics.hmr_p50_msinteger or null

services[].metrics.inotify_watchesintegerRequired

services[].metrics.io_bytesinteger

bytes the container's processes read and wrote (cgroup io.stat), sampled while it starts

services[].metrics.rss_bytesintegerRequired

services[].metrics.sampled_atstring (date-time)Required

services[].namestringRequired

services[].restartsintegerRequired

services[].servinginteger or null

the generation this service serves

services[].started_atstring (date-time)

when the running process started; how long a start or a prepare step has taken

services[].statestringRequired

One of waiting, starting, ready, completed, failed, stopped, not_started

sourcestring

One of worktree, trunk, branch, checkpoint

ssh_host_keystring or null

the session's openssh host key line

statestringRequired

paused: stopped with its checkpoint and kept; dev.sessions.start places it againOne of pending, starting, ready, degraded, disconnected, lost, stopping, paused, stopped, failed

state_reasonstring or null

why the session is in its state. pending: no_capacity, worker_starting or no_worker, or agent_exit_unavailable while no worker that runs the agent's own exit asks for it; lost: worker_lost; stopping, paused and stopped: requested, idle, max_lifetime, budget, kill, access_changed, recreated, checkpoint_expired (a paused session's checkpoint expired, dev), or stopped when the holder stopped with no reason; failed: the worker's failure code, template_digest_mismatch, start_failed, services_failed or an infrastructure code such as disk_full or toolchain_unavailable. a service that never gets ready leaves the session degraded with no reason (ciresk dev up answers the CLI error service_not_ready)

switchobject or null

switch.fromstring or null

switch.phasestring

One of applying, preparing, restarting

switch.tostring or null

templatestringRequired

template_digeststring

timingsobject

milliseconds from create, derived from the session's events

timings.create_msinteger

timings.lease_msinteger

timings.prepare_msinteger

timings.ready_msinteger

timings.sync_msinteger

tree_idstring

unpushed_filesinteger or null

writer cloud: files changed since the trunk tree, until forge pushes them

viewobject

whether the session's view hides any path; never which

view.policy_versioninteger

view.restrictedboolean

web_gatewayboolean

dev.sessions.get only: whether the installation serves sessions in the browser (a preview domain is configured); the console offers no browser button without it

weightobject

weight.cpus_milliintegerRequired

weight.disk_bytesintegerRequired

weight.memory_bytesintegerRequired

weight.memory_max_bytesintegerRequired

workerstring or null

worker_releasestring or null

the release the holding worker registered with (its software_version label), so a rollout is visible

workersstring

only on a pending session whose state_reason is no_worker because the organisation runs on its own workers: nothing of the cell starts one, so a client says to start one of the organisation's enrolled workers; absent otherwiseOne of customer

workspaceobject or null

workspace.bytes_materialisedintegerRequired

workspace.files_materialisedintegerRequired

workspace.files_totalintegerRequired

workspace.recent_waitsarray of stringsRequired

workspace.wait_p95_msintegerRequired

workspace.waits_last_minintegerRequired

writerstringRequired

One of local, cloud

Errors

• 401an error
• 402product_not_licensed, licence_not_yet_valid, licence_expired, licence_ceiling_reached: the licence port refuses new work for the organisation (product dev, next: the platform console's billing page); during CIRESK_DEV_LICENSE_GRACE_UNTIL an organisation without a dev plan is not refused, and an organisation's live session is always returned
• 403not_allowed: this worktree's session has another owner, or source checkpoint names a session the caller does not own (no id, no hint); budget_exceeded: the policy's budget.person_day_units or budget.org_month_units has less than 5 minutes of this session left (scope person_day or org_month, limit_units, used_units, resets_at, next: ciresk dev usage); template_not_published: the policy's templates is published and this template name and dev-file digest are not the active version of the most specific promotion for the repository, or a remote session names a template with no version promoted for its repository, under any policy (next: ciresk dev templates publish <template>; promoted {version_id, template_digest, repository} when another version is active); policy_local_sync_denied: the organisation's policy local_sync is deny and the request syncs a worktree (no source, or source worktree), next: ciresk dev up --remote <template>
• 409writer_conflict (members holder), template_mismatch, org_session_limit and person_session_limit (the policy's lifecycle.sessions_per_org and sessions_per_person, with limit and next: ciresk dev status --all), no_checkpoint (from_session is still running, was killed, is not a cloud writer or has no last checkpoint), already_resumed (another session resumed from_session already; resumed_by names it, dev), org_erasing (the organisation's dev data is being erased), parameter_immutable (the live session runs another value of an immutable parameter the request names; parameters lists them, next: ciresk dev up --recreate), parameters_changed (only mutable parameters the request names differ; parameters lists them, next: ciresk dev up --recreate)
• 422template_invalid (members findings; idle_over_policy when the template's idle is over the policy's lifecycle.idle_max_secs), egress_denied (denied lists the refused host:port, a row with no ports on 443; reason vendor: a required row names a model or tool vendor, an ip literal or a wildcard that may reach one, where an optional one is dropped; reason org_policy: the organisation's egress.session does not cover a required row, next: ciresk dev policy show; reason agent_policy: the same for egress.agent in a session an agent principal starts, where unset is empty; no reason: the installation's egress.yaml does not allow it for product dev-session, the product the worker's session proxy decides under, so a required row passes only where that proxy lets it out; and its amendment of 2026-10-25), template_file_missing (a remote session's promoted version was published before dev-api kept the dev file; next: ciresk dev templates publish <template>), idle_out_of_bounds (idle_secs outside the policy's lifecycle.idle_min_secs and idle_max_secs, both in the problem, next: ciresk dev policy show), session_too_large (the template's memory or cpu reservation over lifecycle.max_session_memory_bytes or max_session_cpus_milli), branch_not_in_ci (source branch: ci has no finished run on a tree for that repository and ref, a delta-only run does not count; next: ciresk ci run check), pull_secret_not_granted (a service's pull.secret is not among the organisation's secrets granted to this session, secret names it; next: ciresk dev secrets set <name> with the registry among its hosts), parameter_invalid (members findings: a preset or parameter the template does not declare, or a value its type refuses, each with its path)
• 503licence_unavailable: the licence source does not answer and the organisation's last answer is a day old, after the grace (retry_after); cell_session_limit: the cell runs its ceiling of live sessions across organisations (CIRESK_DEV_CELL_SESSION_LIMIT), with limit, retry_after_ms and next; source branch only: ci_not_configured (this installation's dev api has no ci cell), ci_unavailable (the ci cell could not be asked about the branch; retry with backoff)

Parameters

Response200 OK

branchstring or null

clientsarray of objects

clients[].clientstringRequired

the daemon's label: mcp:<pid>, cli, browser

clients[].open_streamsintegerRequired

clients[].servicestringRequired

clients[].streams_last_minintegerRequired

clients[].waitingintegerRequired

streams held while the service is not ready

created_atstring (date-time)Required

diagnostic_countsarray of objects

per service; the records come through the diagnostics stream

diagnostic_counts[].digeststringRequired

over a salt only the worker holds and the records: changes when they do

diagnostic_counts[].errorsintegerRequired

diagnostic_counts[].generationintegerRequired

diagnostic_counts[].servicestringRequired

diagnostic_counts[].warningsintegerRequired

dotfilesobject or null

the owner's dotfiles as dev up decided them; null when the owner set none

dotfiles.detailstring or null

dotfiles.nextstring or null

dotfiles.reasonstring or null

One of policy_off, host_not_allowed, vendor, egress_ceiling, egress_denied, agent_session

dotfiles.repostring or null

dotfiles.statestringRequired

One of granted, skipped, unset

epochintegerRequired

expires_atstring (date-time) or null

while live: the stop of the policy's lifecycle.max_lifetime_secs, whatever the activity, fixed at create and at a start; null is no limit. paused: when its checkpoint expires and the session ends

exposearray of objectsRequired

expose[].kindstringRequired

internal: reached only by worker-side services through the guest; never bound locally, never a tunnel stream or an SSH forwardOne of http, tcp, internal

expose[].namestringRequired

expose[].portintegerRequired

expose[].targetintegerRequired

from_sessionstring or null

source checkpoint: the lost session this one resumed

generationinteger

healthobject

the worst service's

health.detailstring

health.nextstring

health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

health.statestringRequired

One of healthy, degraded, failed

idstringRequired

idle_expires_atstring (date-time) or null

labelstringRequired

last_activity_atstring (date-time)Required

last_checkpoint_atstring (date-time) or null

writer cloud: the last checkpoint, so a person sees what a lost host could cost

last_pushobject

dev.sessions.get, writer cloud: the newest push to the session's branch; absent before the first

last_push.atstring (date-time)Required

last_push.change_request_urlstring or nullRequired

last_push.newstringRequired

the commit it pushed

last_push.referencestringRequired

latencyarray of objects

latency[].atstring

added by the cli when it merges the daemon's hopsOne of worker, this_machine

latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

latency[].last_msintegerRequired

latency[].overbooleanRequired

latency[].p50_msintegerRequired

latency[].p95_msintegerRequired

latency[].samplesintegerRequired

latency[].target_msinteger or null

needs_openinteger

needs nobody answered or dismissed yet: the session needs its person (dev.sessions.needs.list)

ownerstring

parametersarray of objects

the template's parameters as resolved at create, in the template's order; empty for a template without any

parameters[].mutablebooleanRequired

parameters[].namestringRequired

parameters[].valuestringRequired

pausingboolean

stopping: the stop keeps the session, which becomes paused once its checkpoint is stored

phasestring

One of creating, placing, syncing, preparing, starting, ready

policyobject

the policy version the session started with and what it allows

policy.clipboardstring

One of allow, deny

policy.downloadstring

One of allow, deny

policy.lifecycleobject

the limits the session started under

policy.lifecycle.auto_stopstring

what an idle stop, the budget's hard stop and max_lifetime_secs do to a cloud-writer session: pause keeps it with its checkpoint for dev.sessions.start, end ends it; a local writer always endsOne of pause, end

policy.lifecycle.idle_max_secsinteger

at least idle_min_secs; idle_secs and a person's idle_secs lie between; a template that names an idle over it is refused at dev.sessions.up (422 template_invalid, finding idle_over_policy with its next), the 60 min default is pulled down

policy.lifecycle.idle_min_secsinteger

policy.lifecycle.idle_secsinteger or null

the idle stop when the person names none; null is the template's (60 min unless it says)

policy.lifecycle.lifetime_warning_secsinteger

shorter than max_lifetime_secs

policy.lifecycle.max_lifetime_secsinteger or null

from create to stop, whatever the activity; null, the default, is no limit; ciresk dev policy preset no-local-checkout suggests 86400

policy.lifecycle.max_session_cpus_milliinteger or null

the largest cpu reservation, in thousandths of a cpu; null is the worker's own limit (422 session_too_large)

policy.lifecycle.max_session_memory_bytesinteger or null

the largest memory reservation one template may declare; null is the worker's own limit (422 session_too_large)

policy.lifecycle.sessions_per_orginteger

live sessions of the organisation, never above the installation's own ceiling (409 org_session_limit)

policy.lifecycle.sessions_per_personinteger

live sessions one person and their agents hold; at most sessions_per_org (409 person_session_limit)

policy.local_syncstring

One of allow, deny

policy.port_forwardstring

One of allow, deny

policy.sharingstring

One of false, view, use

policy.sshstring

One of allow, deny

policy.ssh_execstring

One of allow, deny

policy.uploadstring

One of allow, deny

policy.versioninteger

presetstring or null

the preset the session was created with

queueobject

queue.per_principalintegerRequired

queue.queuedarray of objectsRequired

queue.queued[].clientstringRequired

queue.queued[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.queued[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.queued[].positionintegerRequired

0 while running

queue.queued[].principalstringRequired

the stream's verified principal

queue.queued[].waiting_msintegerRequired

queue.runningarray of objectsRequired

queue.running[].clientstringRequired

queue.running[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.running[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.running[].positionintegerRequired

0 while running

queue.running[].principalstringRequired

the stream's verified principal

queue.running[].waiting_msintegerRequired

queue.slotsintegerRequired

refused_pathsobject

refused_paths.pathsarray of strings

refused_paths.totalinteger

relay_urlstring (uri)

requesterstring

requester_agentstring or null

the agent that opened the session as records name it: the verified agent and the harness its Ciresk-Agent header named; display only, null for a person acting themselves and for a session opened before

resourcesobject

dev.sessions.get only: the session's cpu, memory and disk now, against the template's resources, and one sample a minute for the last hour, oldest first. cpu and memory are the services' metrics together, disk the bytes the session's directory holds; a value the worker does not report is null now and left out of a sample, never 0. the hops now are the session's latency

resources.cpu_milliinteger or null

thousandths of a cpu

resources.disk_bytesinteger or null

resources.historyarray of objectsRequired

resources.history[].atstring (date-time)Required

resources.history[].cpu_milliinteger

resources.history[].disk_bytesinteger

resources.history[].latencyarray of objects

resources.history[].latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

resources.history[].latency[].p50_msintegerRequired

resources.history[].memory_bytesinteger

resources.limitsobjectRequired

resources.limits.cpus_milliintegerRequired

resources.limits.disk_bytesintegerRequired

resources.limits.memory_bytesintegerRequired

resources.limits.memory_max_bytesintegerRequired

resources.memory_bytesinteger or null

resources.sampled_atstring (date-time) or null

rolestring

the caller's role; left out for a session dev.sessions.list with scope org shows to an audit reader who is neither its owner nor a memberOne of owner, use, view

rootstring or null

seedobject or null

seed.generationintegerRequired

seed.rootstring or null

seed.stalebooleanRequired

a path under data.inputs changed since; next: ciresk dev reset --rebuild

seed.taken_atstring (date-time)Required

seed.volumesarray of stringsRequired

servicesarray of objectsRequired

services[].close_reasonstring or null

One of idle, oom, crashed, requested, kill

services[].detailstring or null

services[].healthobjectRequired

; every non-healthy state carries the exact next command

services[].health.detailstring

services[].health.nextstring

services[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

services[].health.statestringRequired

One of healthy, degraded, failed

services[].metricsobject or null

services[].metrics.baseline_rss_bytesinteger or null

services[].metrics.cache_bytesintegerRequired

services[].metrics.cpu_milliintegerRequired

services[].metrics.fdsintegerRequired

services[].metrics.hmr_p50_msinteger or null

services[].metrics.inotify_watchesintegerRequired

services[].metrics.io_bytesinteger

bytes the container's processes read and wrote (cgroup io.stat), sampled while it starts

services[].metrics.rss_bytesintegerRequired

services[].metrics.sampled_atstring (date-time)Required

services[].namestringRequired

services[].restartsintegerRequired

services[].servinginteger or null

the generation this service serves

services[].started_atstring (date-time)

when the running process started; how long a start or a prepare step has taken

services[].statestringRequired

One of waiting, starting, ready, completed, failed, stopped, not_started

sourcestring

One of worktree, trunk, branch, checkpoint

ssh_host_keystring or null

the session's openssh host key line

statestringRequired

paused: stopped with its checkpoint and kept; dev.sessions.start places it againOne of pending, starting, ready, degraded, disconnected, lost, stopping, paused, stopped, failed

state_reasonstring or null

why the session is in its state. pending: no_capacity, worker_starting or no_worker, or agent_exit_unavailable while no worker that runs the agent's own exit asks for it; lost: worker_lost; stopping, paused and stopped: requested, idle, max_lifetime, budget, kill, access_changed, recreated, checkpoint_expired (a paused session's checkpoint expired, dev), or stopped when the holder stopped with no reason; failed: the worker's failure code, template_digest_mismatch, start_failed, services_failed or an infrastructure code such as disk_full or toolchain_unavailable. a service that never gets ready leaves the session degraded with no reason (ciresk dev up answers the CLI error service_not_ready)

switchobject or null

switch.fromstring or null

switch.phasestring

One of applying, preparing, restarting

switch.tostring or null

templatestringRequired

template_digeststring

timingsobject

milliseconds from create, derived from the session's events

timings.create_msinteger

timings.lease_msinteger

timings.prepare_msinteger

timings.ready_msinteger

timings.sync_msinteger

tree_idstring

unpushed_filesinteger or null

writer cloud: files changed since the trunk tree, until forge pushes them

viewobject

whether the session's view hides any path; never which

view.policy_versioninteger

view.restrictedboolean

web_gatewayboolean

dev.sessions.get only: whether the installation serves sessions in the browser (a preview domain is configured); the console offers no browser button without it

weightobject

weight.cpus_milliintegerRequired

weight.disk_bytesintegerRequired

weight.memory_bytesintegerRequired

weight.memory_max_bytesintegerRequired

workerstring or null

worker_releasestring or null

the release the holding worker registered with (its software_version label), so a rollout is visible

workersstring

only on a pending session whose state_reason is no_worker because the organisation runs on its own workers: nothing of the cell starts one, so a client says to start one of the organisation's enrolled workers; absent otherwiseOne of customer

workspaceobject or null

workspace.bytes_materialisedintegerRequired

workspace.files_materialisedintegerRequired

workspace.files_totalintegerRequired

workspace.recent_waitsarray of stringsRequired

workspace.wait_p95_msintegerRequired

workspace.waits_last_minintegerRequired

writerstringRequired

One of local, cloud

ticketobject or null

a dev-api-signed assertion (ed25519, kid), at most 30 s, renewed every 20 s with the credential, owner and grant re-checked; verified by the relay and again by the worker per stream

ticket.epochintegerRequired

ticket.expires_atstring (date-time)Required

ticket.kindsarray of stringsRequired

stream kinds and capabilities, minted from the caller's role and the policy

ticket.relay_urlstring (uri)Required

ticket.ssh_host_keystring or null

the epoch's openssh host key once the worker reported it; a renewal refreshes known_hosts

ticket.syncbooleanRequired

true only for the creating device

ticket.ticketstringRequired

ticket.ticket_idstringRequired

Errors

• 404an error

Parameters

Request body

branchstring or null

idle_secsinteger

within the current policy's lifecycle bounds (422 idle_out_of_bounds)

Response200 OK

branchstring or null

clientsarray of objects

clients[].clientstringRequired

the daemon's label: mcp:<pid>, cli, browser

clients[].open_streamsintegerRequired

clients[].servicestringRequired

clients[].streams_last_minintegerRequired

clients[].waitingintegerRequired

streams held while the service is not ready

created_atstring (date-time)Required

diagnostic_countsarray of objects

per service; the records come through the diagnostics stream

diagnostic_counts[].digeststringRequired

over a salt only the worker holds and the records: changes when they do

diagnostic_counts[].errorsintegerRequired

diagnostic_counts[].generationintegerRequired

diagnostic_counts[].servicestringRequired

diagnostic_counts[].warningsintegerRequired

dotfilesobject or null

the owner's dotfiles as dev up decided them; null when the owner set none

dotfiles.detailstring or null

dotfiles.nextstring or null

dotfiles.reasonstring or null

One of policy_off, host_not_allowed, vendor, egress_ceiling, egress_denied, agent_session

dotfiles.repostring or null

dotfiles.statestringRequired

One of granted, skipped, unset

epochintegerRequired

expires_atstring (date-time) or null

while live: the stop of the policy's lifecycle.max_lifetime_secs, whatever the activity, fixed at create and at a start; null is no limit. paused: when its checkpoint expires and the session ends

exposearray of objectsRequired

expose[].kindstringRequired

internal: reached only by worker-side services through the guest; never bound locally, never a tunnel stream or an SSH forwardOne of http, tcp, internal

expose[].namestringRequired

expose[].portintegerRequired

expose[].targetintegerRequired

from_sessionstring or null

source checkpoint: the lost session this one resumed

generationinteger

healthobject

the worst service's

health.detailstring

health.nextstring

health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

health.statestringRequired

One of healthy, degraded, failed

idstringRequired

idle_expires_atstring (date-time) or null

labelstringRequired

last_activity_atstring (date-time)Required

last_checkpoint_atstring (date-time) or null

writer cloud: the last checkpoint, so a person sees what a lost host could cost

last_pushobject

dev.sessions.get, writer cloud: the newest push to the session's branch; absent before the first

last_push.atstring (date-time)Required

last_push.change_request_urlstring or nullRequired

last_push.newstringRequired

the commit it pushed

last_push.referencestringRequired

latencyarray of objects

latency[].atstring

added by the cli when it merges the daemon's hopsOne of worker, this_machine

latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

latency[].last_msintegerRequired

latency[].overbooleanRequired

latency[].p50_msintegerRequired

latency[].p95_msintegerRequired

latency[].samplesintegerRequired

latency[].target_msinteger or null

needs_openinteger

needs nobody answered or dismissed yet: the session needs its person (dev.sessions.needs.list)

ownerstring

parametersarray of objects

the template's parameters as resolved at create, in the template's order; empty for a template without any

parameters[].mutablebooleanRequired

parameters[].namestringRequired

parameters[].valuestringRequired

pausingboolean

stopping: the stop keeps the session, which becomes paused once its checkpoint is stored

phasestring

One of creating, placing, syncing, preparing, starting, ready

policyobject

the policy version the session started with and what it allows

policy.clipboardstring

One of allow, deny

policy.downloadstring

One of allow, deny

policy.lifecycleobject

the limits the session started under

policy.lifecycle.auto_stopstring

what an idle stop, the budget's hard stop and max_lifetime_secs do to a cloud-writer session: pause keeps it with its checkpoint for dev.sessions.start, end ends it; a local writer always endsOne of pause, end

policy.lifecycle.idle_max_secsinteger

at least idle_min_secs; idle_secs and a person's idle_secs lie between; a template that names an idle over it is refused at dev.sessions.up (422 template_invalid, finding idle_over_policy with its next), the 60 min default is pulled down

policy.lifecycle.idle_min_secsinteger

policy.lifecycle.idle_secsinteger or null

the idle stop when the person names none; null is the template's (60 min unless it says)

policy.lifecycle.lifetime_warning_secsinteger

shorter than max_lifetime_secs

policy.lifecycle.max_lifetime_secsinteger or null

from create to stop, whatever the activity; null, the default, is no limit; ciresk dev policy preset no-local-checkout suggests 86400

policy.lifecycle.max_session_cpus_milliinteger or null

the largest cpu reservation, in thousandths of a cpu; null is the worker's own limit (422 session_too_large)

policy.lifecycle.max_session_memory_bytesinteger or null

the largest memory reservation one template may declare; null is the worker's own limit (422 session_too_large)

policy.lifecycle.sessions_per_orginteger

live sessions of the organisation, never above the installation's own ceiling (409 org_session_limit)

policy.lifecycle.sessions_per_personinteger

live sessions one person and their agents hold; at most sessions_per_org (409 person_session_limit)

policy.local_syncstring

One of allow, deny

policy.port_forwardstring

One of allow, deny

policy.sharingstring

One of false, view, use

policy.sshstring

One of allow, deny

policy.ssh_execstring

One of allow, deny

policy.uploadstring

One of allow, deny

policy.versioninteger

presetstring or null

the preset the session was created with

queueobject

queue.per_principalintegerRequired

queue.queuedarray of objectsRequired

queue.queued[].clientstringRequired

queue.queued[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.queued[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.queued[].positionintegerRequired

0 while running

queue.queued[].principalstringRequired

the stream's verified principal

queue.queued[].waiting_msintegerRequired

queue.runningarray of objectsRequired

queue.running[].clientstringRequired

queue.running[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.running[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.running[].positionintegerRequired

0 while running

queue.running[].principalstringRequired

the stream's verified principal

queue.running[].waiting_msintegerRequired

queue.slotsintegerRequired

refused_pathsobject

refused_paths.pathsarray of strings

refused_paths.totalinteger

relay_urlstring (uri)

requesterstring

requester_agentstring or null

the agent that opened the session as records name it: the verified agent and the harness its Ciresk-Agent header named; display only, null for a person acting themselves and for a session opened before

resourcesobject

dev.sessions.get only: the session's cpu, memory and disk now, against the template's resources, and one sample a minute for the last hour, oldest first. cpu and memory are the services' metrics together, disk the bytes the session's directory holds; a value the worker does not report is null now and left out of a sample, never 0. the hops now are the session's latency

resources.cpu_milliinteger or null

thousandths of a cpu

resources.disk_bytesinteger or null

resources.historyarray of objectsRequired

resources.history[].atstring (date-time)Required

resources.history[].cpu_milliinteger

resources.history[].disk_bytesinteger

resources.history[].latencyarray of objects

resources.history[].latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

resources.history[].latency[].p50_msintegerRequired

resources.history[].memory_bytesinteger

resources.limitsobjectRequired

resources.limits.cpus_milliintegerRequired

resources.limits.disk_bytesintegerRequired

resources.limits.memory_bytesintegerRequired

resources.limits.memory_max_bytesintegerRequired

resources.memory_bytesinteger or null

resources.sampled_atstring (date-time) or null

rolestring

the caller's role; left out for a session dev.sessions.list with scope org shows to an audit reader who is neither its owner nor a memberOne of owner, use, view

rootstring or null

seedobject or null

seed.generationintegerRequired

seed.rootstring or null

seed.stalebooleanRequired

a path under data.inputs changed since; next: ciresk dev reset --rebuild

seed.taken_atstring (date-time)Required

seed.volumesarray of stringsRequired

servicesarray of objectsRequired

services[].close_reasonstring or null

One of idle, oom, crashed, requested, kill

services[].detailstring or null

services[].healthobjectRequired

; every non-healthy state carries the exact next command

services[].health.detailstring

services[].health.nextstring

services[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

services[].health.statestringRequired

One of healthy, degraded, failed

services[].metricsobject or null

services[].metrics.baseline_rss_bytesinteger or null

services[].metrics.cache_bytesintegerRequired

services[].metrics.cpu_milliintegerRequired

services[].metrics.fdsintegerRequired

services[].metrics.hmr_p50_msinteger or null

services[].metrics.inotify_watchesintegerRequired

services[].metrics.io_bytesinteger

bytes the container's processes read and wrote (cgroup io.stat), sampled while it starts

services[].metrics.rss_bytesintegerRequired

services[].metrics.sampled_atstring (date-time)Required

services[].namestringRequired

services[].restartsintegerRequired

services[].servinginteger or null

the generation this service serves

services[].started_atstring (date-time)

when the running process started; how long a start or a prepare step has taken

services[].statestringRequired

One of waiting, starting, ready, completed, failed, stopped, not_started

sourcestring

One of worktree, trunk, branch, checkpoint

ssh_host_keystring or null

the session's openssh host key line

statestringRequired

paused: stopped with its checkpoint and kept; dev.sessions.start places it againOne of pending, starting, ready, degraded, disconnected, lost, stopping, paused, stopped, failed

state_reasonstring or null

why the session is in its state. pending: no_capacity, worker_starting or no_worker, or agent_exit_unavailable while no worker that runs the agent's own exit asks for it; lost: worker_lost; stopping, paused and stopped: requested, idle, max_lifetime, budget, kill, access_changed, recreated, checkpoint_expired (a paused session's checkpoint expired, dev), or stopped when the holder stopped with no reason; failed: the worker's failure code, template_digest_mismatch, start_failed, services_failed or an infrastructure code such as disk_full or toolchain_unavailable. a service that never gets ready leaves the session degraded with no reason (ciresk dev up answers the CLI error service_not_ready)

switchobject or null

switch.fromstring or null

switch.phasestring

One of applying, preparing, restarting

switch.tostring or null

templatestringRequired

template_digeststring

timingsobject

milliseconds from create, derived from the session's events

timings.create_msinteger

timings.lease_msinteger

timings.prepare_msinteger

timings.ready_msinteger

timings.sync_msinteger

tree_idstring

unpushed_filesinteger or null

writer cloud: files changed since the trunk tree, until forge pushes them

viewobject

whether the session's view hides any path; never which

view.policy_versioninteger

view.restrictedboolean

web_gatewayboolean

dev.sessions.get only: whether the installation serves sessions in the browser (a preview domain is configured); the console offers no browser button without it

weightobject

weight.cpus_milliintegerRequired

weight.disk_bytesintegerRequired

weight.memory_bytesintegerRequired

weight.memory_max_bytesintegerRequired

workerstring or null

worker_releasestring or null

the release the holding worker registered with (its software_version label), so a rollout is visible

workersstring

only on a pending session whose state_reason is no_worker because the organisation runs on its own workers: nothing of the cell starts one, so a client says to start one of the organisation's enrolled workers; absent otherwiseOne of customer

workspaceobject or null

workspace.bytes_materialisedintegerRequired

workspace.files_materialisedintegerRequired

workspace.files_totalintegerRequired

workspace.recent_waitsarray of stringsRequired

workspace.wait_p95_msintegerRequired

workspace.waits_last_minintegerRequired

writerstringRequired

One of local, cloud

Errors

• 409writer_conflict, stale_epoch, branch_fixed (a remote session writes refs/heads/ciresk/<session_id> for its life), session_not_running (the session has stopped)
• 422idle_out_of_bounds: idle_secs outside the current policy's lifecycle bounds

Parameters

Response200 OK

dataarray of objectsRequired

data[].actorstringRequired

data[].atstring (date-time)Required

data[].classstringRequired

One of inbound, run

data[].epochintegerRequired

data[].kindstringRequired

session.lifetime_warning is only in journals from before need.raised {kind: expiring} replaced itOne of session.created, session.stop_requested, session.killed, writer.moved, grant.added, grant.revoked, session.leased, session.disconnected, session.reconnected, session.lost, service.changed, service.serving, service.diagnostics, service.health, service.restarted, session.ready, session.degraded, session.applied, identity.logged_in, identity.revoked, session.stopped, session.failed, member.added, member.revoked and 27 more

data[].payloadobjectRequired

data[].schema_versionintegerRequired

data[].seqintegerRequired

data[].session_idstringRequired

data[].worker_seqinteger or null

has_morebooleanRequired

next_cursorstring or null

Parameters

Request body

reasonstring

Response200 OK

branchstring or null

clientsarray of objects

clients[].clientstringRequired

the daemon's label: mcp:<pid>, cli, browser

clients[].open_streamsintegerRequired

clients[].servicestringRequired

clients[].streams_last_minintegerRequired

clients[].waitingintegerRequired

streams held while the service is not ready

created_atstring (date-time)Required

diagnostic_countsarray of objects

per service; the records come through the diagnostics stream

diagnostic_counts[].digeststringRequired

over a salt only the worker holds and the records: changes when they do

diagnostic_counts[].errorsintegerRequired

diagnostic_counts[].generationintegerRequired

diagnostic_counts[].servicestringRequired

diagnostic_counts[].warningsintegerRequired

dotfilesobject or null

the owner's dotfiles as dev up decided them; null when the owner set none

dotfiles.detailstring or null

dotfiles.nextstring or null

dotfiles.reasonstring or null

One of policy_off, host_not_allowed, vendor, egress_ceiling, egress_denied, agent_session

dotfiles.repostring or null

dotfiles.statestringRequired

One of granted, skipped, unset

epochintegerRequired

expires_atstring (date-time) or null

while live: the stop of the policy's lifecycle.max_lifetime_secs, whatever the activity, fixed at create and at a start; null is no limit. paused: when its checkpoint expires and the session ends

exposearray of objectsRequired

expose[].kindstringRequired

internal: reached only by worker-side services through the guest; never bound locally, never a tunnel stream or an SSH forwardOne of http, tcp, internal

expose[].namestringRequired

expose[].portintegerRequired

expose[].targetintegerRequired

from_sessionstring or null

source checkpoint: the lost session this one resumed

generationinteger

healthobject

the worst service's

health.detailstring

health.nextstring

health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

health.statestringRequired

One of healthy, degraded, failed

idstringRequired

idle_expires_atstring (date-time) or null

labelstringRequired

last_activity_atstring (date-time)Required

last_checkpoint_atstring (date-time) or null

writer cloud: the last checkpoint, so a person sees what a lost host could cost

last_pushobject

dev.sessions.get, writer cloud: the newest push to the session's branch; absent before the first

last_push.atstring (date-time)Required

last_push.change_request_urlstring or nullRequired

last_push.newstringRequired

the commit it pushed

last_push.referencestringRequired

latencyarray of objects

latency[].atstring

added by the cli when it merges the daemon's hopsOne of worker, this_machine

latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

latency[].last_msintegerRequired

latency[].overbooleanRequired

latency[].p50_msintegerRequired

latency[].p95_msintegerRequired

latency[].samplesintegerRequired

latency[].target_msinteger or null

needs_openinteger

needs nobody answered or dismissed yet: the session needs its person (dev.sessions.needs.list)

ownerstring

parametersarray of objects

the template's parameters as resolved at create, in the template's order; empty for a template without any

parameters[].mutablebooleanRequired

parameters[].namestringRequired

parameters[].valuestringRequired

pausingboolean

stopping: the stop keeps the session, which becomes paused once its checkpoint is stored

phasestring

One of creating, placing, syncing, preparing, starting, ready

policyobject

the policy version the session started with and what it allows

policy.clipboardstring

One of allow, deny

policy.downloadstring

One of allow, deny

policy.lifecycleobject

the limits the session started under

policy.lifecycle.auto_stopstring

what an idle stop, the budget's hard stop and max_lifetime_secs do to a cloud-writer session: pause keeps it with its checkpoint for dev.sessions.start, end ends it; a local writer always endsOne of pause, end

policy.lifecycle.idle_max_secsinteger

at least idle_min_secs; idle_secs and a person's idle_secs lie between; a template that names an idle over it is refused at dev.sessions.up (422 template_invalid, finding idle_over_policy with its next), the 60 min default is pulled down

policy.lifecycle.idle_min_secsinteger

policy.lifecycle.idle_secsinteger or null

the idle stop when the person names none; null is the template's (60 min unless it says)

policy.lifecycle.lifetime_warning_secsinteger

shorter than max_lifetime_secs

policy.lifecycle.max_lifetime_secsinteger or null

from create to stop, whatever the activity; null, the default, is no limit; ciresk dev policy preset no-local-checkout suggests 86400

policy.lifecycle.max_session_cpus_milliinteger or null

the largest cpu reservation, in thousandths of a cpu; null is the worker's own limit (422 session_too_large)

policy.lifecycle.max_session_memory_bytesinteger or null

the largest memory reservation one template may declare; null is the worker's own limit (422 session_too_large)

policy.lifecycle.sessions_per_orginteger

live sessions of the organisation, never above the installation's own ceiling (409 org_session_limit)

policy.lifecycle.sessions_per_personinteger

live sessions one person and their agents hold; at most sessions_per_org (409 person_session_limit)

policy.local_syncstring

One of allow, deny

policy.port_forwardstring

One of allow, deny

policy.sharingstring

One of false, view, use

policy.sshstring

One of allow, deny

policy.ssh_execstring

One of allow, deny

policy.uploadstring

One of allow, deny

policy.versioninteger

presetstring or null

the preset the session was created with

queueobject

queue.per_principalintegerRequired

queue.queuedarray of objectsRequired

queue.queued[].clientstringRequired

queue.queued[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.queued[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.queued[].positionintegerRequired

0 while running

queue.queued[].principalstringRequired

the stream's verified principal

queue.queued[].waiting_msintegerRequired

queue.runningarray of objectsRequired

queue.running[].clientstringRequired

queue.running[].exec_idstring

a running exec's id, which dev exec --cancel takes; absent for other operations and while queued

queue.running[].opstringRequired

One of exec, reset, restart, login, checkpoint

queue.running[].positionintegerRequired

0 while running

queue.running[].principalstringRequired

the stream's verified principal

queue.running[].waiting_msintegerRequired

queue.slotsintegerRequired

refused_pathsobject

refused_paths.pathsarray of strings

refused_paths.totalinteger

relay_urlstring (uri)

requesterstring

requester_agentstring or null

the agent that opened the session as records name it: the verified agent and the harness its Ciresk-Agent header named; display only, null for a person acting themselves and for a session opened before

resourcesobject

dev.sessions.get only: the session's cpu, memory and disk now, against the template's resources, and one sample a minute for the last hour, oldest first. cpu and memory are the services' metrics together, disk the bytes the session's directory holds; a value the worker does not report is null now and left out of a sample, never 0. the hops now are the session's latency

resources.cpu_milliinteger or null

thousandths of a cpu

resources.disk_bytesinteger or null

resources.historyarray of objectsRequired

resources.history[].atstring (date-time)Required

resources.history[].cpu_milliinteger

resources.history[].disk_bytesinteger

resources.history[].latencyarray of objects

resources.history[].latency[].hopstringRequired

One of sync, build, reload, tunnel, browser, fetch, queue, search, exec

resources.history[].latency[].p50_msintegerRequired

resources.history[].memory_bytesinteger

resources.limitsobjectRequired

resources.limits.cpus_milliintegerRequired

resources.limits.disk_bytesintegerRequired

resources.limits.memory_bytesintegerRequired

resources.limits.memory_max_bytesintegerRequired

resources.memory_bytesinteger or null

resources.sampled_atstring (date-time) or null

rolestring

the caller's role; left out for a session dev.sessions.list with scope org shows to an audit reader who is neither its owner nor a memberOne of owner, use, view

rootstring or null

seedobject or null

seed.generationintegerRequired

seed.rootstring or null

seed.stalebooleanRequired

a path under data.inputs changed since; next: ciresk dev reset --rebuild

seed.taken_atstring (date-time)Required

seed.volumesarray of stringsRequired

servicesarray of objectsRequired

services[].close_reasonstring or null

One of idle, oom, crashed, requested, kill

services[].detailstring or null

services[].healthobjectRequired

; every non-healthy state carries the exact next command

services[].health.detailstring

services[].health.nextstring

services[].health.reasonstring

One of memory_growth, hmr_slow, disk, watch_limit, hung, crash_loop

services[].health.statestringRequired

One of healthy, degraded, failed

services[].metricsobject or null

services[].metrics.baseline_rss_bytesinteger or null

services[].metrics.cache_bytesintegerRequired

services[].metrics.cpu_milliintegerRequired

services[].metrics.fdsintegerRequired

services[].metrics.hmr_p50_msinteger or null

services[].metrics.inotify_watchesintegerRequired

services[].metrics.io_bytesinteger

bytes the container's processes read and wrote (cgroup io.stat), sampled while it starts

services[].metrics.rss_bytesintegerRequired

services[].metrics.sampled_atstring (date-time)Required

services[].namestringRequired

services[].restartsintegerRequired

services[].servinginteger or null

the generation this service serves

services[].started_atstring (date-time)

when the running process started; how long a start or a prepare step has taken

services[].statestringRequired

One of waiting, starting, ready, completed, failed, stopped, not_started

sourcestring

One of worktree, trunk, branch, checkpoint

ssh_host_keystring or null

the session's openssh host key line

statestringRequired

paused: stopped with its checkpoint and kept; dev.sessions.start places it againOne of pending, starting, ready, degraded, disconnected, lost, stopping, paused, stopped, failed

state_reasonstring or null

why the session is in its state. pending: no_capacity, worker_starting or no_worker, or agent_exit_unavailable while no worker that runs the agent's own exit asks for it; lost: worker_lost; stopping, paused and stopped: requested, idle, max_lifetime, budget, kill, access_changed, recreated, checkpoint_expired (a paused session's checkpoint expired, dev), or stopped when the holder stopped with no reason; failed: the worker's failure code, template_digest_mismatch, start_failed, services_failed or an infrastructure code such as disk_full or toolchain_unavailable. a service that never gets ready leaves the session degraded with no reason (ciresk dev up answers the CLI error service_not_ready)

switchobject or null

switch.fromstring or null

switch.phasestring

One of applying, preparing, restarting

switch.tostring or null

templatestringRequired

template_digeststring

timingsobject

milliseconds from create, derived from the session's events

timings.create_msinteger

timings.lease_msinteger

timings.prepare_msinteger

timings.ready_msinteger

timings.sync_msinteger

tree_idstring

unpushed_filesinteger or null

writer cloud: files changed since the trunk tree, until forge pushes them

viewobject

whether the session's view hides any path; never which

view.policy_versioninteger

view.restrictedboolean

web_gatewayboolean

dev.sessions.get only: whether the installation serves sessions in the browser (a preview domain is configured); the console offers no browser button without it

weightobject

weight.cpus_milliintegerRequired

weight.disk_bytesintegerRequired

weight.memory_bytesintegerRequired

weight.memory_max_bytesintegerRequired

workerstring or null

worker_releasestring or null

the release the holding worker registered with (its software_version label), so a rollout is visible

workersstring

only on a pending session whose state_reason is no_worker because the organisation runs on its own workers: nothing of the cell starts one, so a client says to start one of the organisation's enrolled workers; absent otherwiseOne of customer

workspaceobject or null

workspace.bytes_materialisedintegerRequired

workspace.files_materialisedintegerRequired

workspace.files_totalintegerRequired

workspace.recent_waitsarray of stringsRequired

workspace.wait_p95_msintegerRequired

workspace.waits_last_minintegerRequired

writerstringRequired

One of local, cloud