Schemas

Omit for a clean browser

With a profile, defaults to write and cannot be clean; without a profile, it can only be clean (or omitted).

owner: manages members, API keys and the webhook, plus everything a member can do; member: day-to-day operations.

false = the Agent cannot register schedules or keep-awake

Keys issued by the platform operator have no name.

The first few characters of the key (temper_sk_...), for identifying it.

Who created it (member email; null for keys issued by the platform operator).

Action category. send, pay, delete and change_permission are high-risk categories that rules cannot allow; they always require approval.

A one-sentence summary shown to the end user.

Grant scope, from narrowest to widest: once < task < session < time_limited < permanent. Note: in a decision request (DecisionRequest.scope.kind) the time-limited scope is written until; here (max_scope, and the scope of approvals and grants) it is called time_limited.

expired: nobody decided before it expired; counts as denied.

The scope given on approval; null in other states.

How the decision arrived - a signed callback from your backend, an API key, or a team member in the console.

For expired requests, this is expires_at.

Present only when approved.

Offset of the first byte of this chunk

Decoded as UTF-8

The first sequence number the control plane received (greater than 1 if earlier lines on the host were lost).

SHA-256 of the last line (the chain head).

The chain no longer links up from this number on; null if intact.

Every chain links up.

Which hash chain (one per VM).

Sequence number within the chain, starting at 1.

Source, for example egress (outbound request), gateway (request made with a credential), browser (browser action); unknown if the record has none. Approval decisions are not separate records here: they appear on the record of the action they gated.

The parsed raw line (with seq and prev); fields vary by source.

Opaque pagination position.

Connectors of a single provider; unknown connectors, or a mix of two providers, give 400.

The page of yours to return to after authorization; must be an absolute http(s) URL.

write = load the signed-in state and save it on release (one at a time per profile); read = load only; clean = a clean browser.

Signed-in state version loaded when the lease was granted

releasing = a write lease released through the REST API is waiting for the host to send back the signed-in state (at most 60 seconds); it always ends up released.

Whether the signed-in state was saved or discarded when the write lease ended; null for other leases and for leases not yet settled (active, releasing).

If the end user is currently taking over (all of the Agent's browser commands are rejected), when the takeover began; null when not taken over.

Signed-in state version; increases by 1 each time a write lease saves successfully

The viewer page for the end user to open; single use. Do not log it.

The URL expires after 10 minutes.

base64 for binary content.

The OAuth scopes the provider actually granted.

Account: the email address for Google, the team for Slack.

error: the provider rejected the token refresh (most likely the user revoked access at the provider); the user must authorize again.

The reason for the most recent refresh failure.

The provider's consent page; send the end user there.

The link expires after 10 minutes.

More than 500 connections; the list is incomplete.

Empty string for connection.created and connection.revoked; for connection.error, the environment that triggered the refresh.

connection.created: provider, connectors, account, replaced (the id of the old connection it replaced, or null); connection.revoked: provider; connection.error: error.

temper_cs_..., shown only this once.

Expires at this time if idle (pushed back on each use, up to 7 days after sign-in).

The PKCE verifier for the challenge sent at start.

Which team to choose when the member belongs to several.

Keys issued by the platform operator have no name.

The first few characters of the key (temper_sk_...), for identifying it.

Who created it (member email; null for keys issued by the platform operator).

temper_sk_..., shown only in this response.

Your own id for the end user

If omitted, the developer's default version is used. Whether the version has been uploaded is not checked.

All optional; defaults are 2 vCPUs, a 4096 MiB memory limit, 1024 MiB base memory and a 10 GiB disk.

Idle thresholds (seconds); 0 = this tier is never applied automatically, otherwise 60–7776000 (90 days). Both thresholds count from the last activity: by default an environment is suspended after 6 hours idle and stopped after 7 days idle, so keep stop_after_secs larger than suspend_after_secs. With suspension turned off (0) the environment is never stopped either.

Environment variables, at most 100 and 32 KiB in total. Names are letters, digits and _, not starting with a digit, up to 128 characters. The platform's proxy and certificate variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO, in any case), HOME, USER, LOGNAME and names starting with TEMPER_ are reserved. Values are up to 4096 bytes, without single quotes or control characters other than tab.

Files by name, at most 20 and 256 KiB in total (decoded). Names are letters, digits, ., _ and -, not starting with . or -, up to 128 characters.

Environment-level secrets by name (an environment can have at most 100; so can the developer level), created in the same transaction as the environment (same fields and rules as PUT /v1/environments/{id}/secrets/{name}). If any is invalid, nothing is created. Their placeholders exist before the VM first starts.

The environment's own egress allowlist (same as allow in PUT /v1/environments/{id}/egress). Omitted = use the developer-level list.

Template version as name:version (see createTemplateVersion); it must be ready. Omitted or null = the platform's default runtime. An environment stays on its template version; changing it means moving the environment to a new VM, like an Agent upgrade.

Base version as name:version (one of your own, and ready). Omitted or null = the platform's default runtime (Debian 13 with systemd).

Build steps, run in order. All copy contents together are limited to 4 MiB (decoded).

The command environments with this template run when they have no Agent package: a string (run with /bin/sh -c) or an argv array, started in the last workdir. With an Agent package, the package's /opt/agent/bin/start runs instead. Without either, the environment simply waits for exec.

RFC 3339, from 1 minute ago to 366 days ahead

Required when approving; ignored when denying.

Null if never set.

Symbolic links are not followed

Octal permission bits, for example 644, 755

The path given in the request (unchanged)

More than 10000 entries; the rest were cut off

The template version the environment runs (name:version); null = the platform's default runtime.

Resource specification.

Desired state (changed through the API).

Actual state (reported back by the host).

The most recent activity (the VM using CPU, a wake, keep-awake, a scheduled wakeup). Idle tiers are measured from this time.

Which monthly limit was exceeded (a human-readable reason, for example environment egress_gib 1.20 >= 1); null if none. An environment over its limit is suspended, and resume, wake and exec return 409 limit_exceeded until the limit is raised or deleted, or the next month begins (see setLimit).

Environment variables, at most 100 and 32 KiB in total. Names are letters, digits and _, not starting with a digit, up to 128 characters. The platform's proxy and certificate variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO, in any case), HOME, USER, LOGNAME and names starting with TEMPER_ are reserved. Values are up to 4096 bytes, without single quotes or control characters other than tab.

Files by name, at most 20 and 256 KiB in total (decoded). Names are letters, digits, ., _ and -, not starting with . or -, up to 128 characters.

true = the environment has no list of its own and uses the developer-level one.

Increasing cursor (for pagination); shared across all environments, so not contiguous

Event kind, for example created, desired_<state>, running, idle_suspend, keep_awake, agent_upgrade, agent_schedule_set, limit_exceeded, audit_chain_broken.

Event details; fields vary by kind. Actions registered by the Agent itself carry source: agent.

The after for the next page; null when this page is not full.

Where the rules come from: the environment's own policy, the developer default, or the built-in behavior (empty rules).

Machine-readable code: bad_request(400), unauthorized(401), forbidden(403), not_found(404), method_not_allowed(405), payload_too_large(413), unsupported_media_type(415), invalid_body(422), internal(500); 409: environment_exists, idempotency_key_reused, invalid_state_transition, environment_destroyed, environment_failed, version_exists, template_not_ready, template_in_use, template_building, rollout_in_progress, not_latest_rollout, profile_exists, profile_in_use, profile_locked, lease_not_active, no_oauth_client, already_decided, limit_exceeded, export_too_large, not_taken_over, member_exists, last_owner, choose_developer; 403: session_required, reauth_required; 400: invalid_code; 429: rate_limited; 503: login_unavailable; approval decisions additionally use 400 invalid_decision / missing_scope / invalid_scope, 401 invalid_signature, 403 scope_too_wide; 429: wakeup_limit_reached, lease_limit_reached, too_many_processes; 503: host_unavailable, guest_unavailable, environment_not_placed, environment_not_running, exec_failed, exec_timeout, file_operation_failed, provider_error (the OAuth provider returned an error). Other status codes for requests rejected before reaching the endpoint are reported as http_error.

With environment_exists and idempotency_key_reused, the id of the existing environment.

Executed as is, for example ["python3", "-c", "print(1)"].

Run with bash -lc, for example ls -la | head.

Extra environment variables. Names consist of letters, digits and underscores and do not start with a digit; variables already set in agent.env or the Agent package's env cannot be overridden.

Working directory (a path inside the runtime unit); defaults to the agent user's home directory.

Standard input for the process (closed afterwards); if omitted, stdin is /dev/null.

Exit code on normal exit; null if killed by a signal

The signal that killed the process (signal number)

Killed for exceeding timeout_secs

At most 1 MiB, decoded as UTF-8

Measured from when the control plane received the request (including waking and connecting)

Action category. send, pay, delete and change_permission are high-risk categories that rules cannot allow; they always require approval.

The scope the grant covers ("once" leaves no grant).

The task / session id.

Expiry time for time_limited.

0 or 60–7776000.

0 or 60–7776000.

0 or 60–7776000.

0 or 60–7776000.

Until this time the environment will not be suspended by the idle tiers.

Null when using an API key.

Present only with a session: every team this account can access.

Lowercase.

owner: manages members, API keys and the webhook, plus everything a member can do; member: day-to-day operations.

Registered by you; null if not registered.

Whether the platform test app is configured (used when you have not registered your own app).

The callback URL to register with the provider.

Offset of the first byte of this chunk

Decoded as UTF-8 (invalid bytes replaced with U+FFFD)

A built-in connector (gmail, calendar, slack, browser) or secret:NAME for a developer secret.

Action category. send, pay, delete and change_permission are high-risk categories that rules cannot allow; they always require approval.

Task-scoped grants apply only when this matches.

Session-scoped grants apply only when this matches.

rule: an allow rule matched. grant: an existing grant covers it (grant_id). deny_rule: a deny rule matched (deny wins over everything). ask_rule: an ask rule matched (ask wins over allow). high_risk: no ask rule, but send / pay / delete / change_permission always need approval. no_rule: nothing matched, so it is denied. infrastructure_credential: the connector is an infrastructure secret, which skips the action policy.

Grant scope, from narrowest to widest: once < task < session < time_limited < permanent. Note: in a decision request (DecisionRequest.scope.kind) the time-limited scope is written until; here (max_scope, and the scope of approvals and grants) it is called time_limited.

Indexes (from 0) of the rules in the effective policy that match this connector and category.

Where the effective rules come from.

Connector (credential id), for example gmail, calendar, slack, or secret:<NAME> for requests made with a developer secret. A trailing * matches by prefix: secret:* covers every developer secret.

Action category. send, pay, delete and change_permission are high-risk categories that rules cannot allow; they always require approval.

Only allowed on ask: the widest grant the end user can give. Defaults to permanent.

The argv actually executed (command is turned into /bin/bash -lc ...)

Start time (Unix seconds, not RFC 3339)

Present only once the process has exited

Total bytes output so far (stdout and stderr combined); continue reading from here next time

Offset of the oldest byte still retained in the VM (anything earlier has been dropped)

stdin can still be written

Exit code on normal exit; null if killed by a signal

The signal that killed the process (signal number); the field is absent otherwise

The process state when output reading began

The since for the next call

The process was seen to exit during this read

An exact domain or *.example.com. For an environment, null reverts to the developer-level list; for the developer level, null clears the list.

The real value, at most 8192 bytes, with no newlines. Never returned by any endpoint afterwards.

The value is sent only to these exact domains (lowercase, without scheme, port or wildcards).

Allowlist of path prefixes (starting with /); omitted or empty = no restriction.

The request header that receives the real value, default authorization. Cannot be host, cookie or content-length.

Header value = prefix + real value. Defaults to Bearer when header is authorization, and to empty for custom headers. No newlines.

standard: a key the Agent uses on the end user's behalf. Requests that use it go through the action policy as connector secret:NAME (GET/HEAD/OPTIONS count as read, other methods as write). infrastructure: your own infrastructure credential, for example the token your Agent uses to connect back to your backend. It is still sent only to hosts and paths and every use is audited, but requests that use it skip the action policy. A request that also carries a standard or built-in credential is judged by that credential.

Whether a write lease saves the signed-in state; omitted or null means true. Only meaningful for write leases.

Memory limit

Base memory, no more than memory_mib

256 to memory_mib

Why it was rolled back (for an automatic rollback, the failed environments and errors; for a manual one, manual)

Why it was rolled back (for an automatic rollback, the failed environments and errors; for a manual one, manual)

The original version (restored on rollback)

Not running when switched, so only the version was changed (effective at next start) without waiting for it to become healthy

Entered failed, or was not healthy within 10 minutes

Name chosen by the registrant; the same key overwrites

Standard 5 fields (minute hour day month weekday)

IANA time zone; present together with cron

Next occurrence (computed by the control plane)

Set only for environment-level secrets; null for developer-level ones.

standard: a key the Agent uses on the end user's behalf. Requests that use it go through the action policy as connector secret:NAME (GET/HEAD/OPTIONS count as read, other methods as write). infrastructure: your own infrastructure credential, for example the token your Agent uses to connect back to your backend. It is still sent only to hosts and paths and every use is audited, but requests that use it skip the action policy. A request that also carries a standard or built-in credential is judged by that credential.

The last time the credential gateway substituted this value.

Omit for developer-level.

active_hours: hours the VM was running; cpu_hours: CPU time (hours); memory_gib_hours: VMM memory GiB × hours; storage_gib_hours: actual data disk usage GiB × hours; egress_gib: egress traffic in GiB; browser_hours: browser lease hours.

active_hours: hours the VM was running; cpu_hours: CPU time (hours); memory_gib_hours: VMM memory GiB × hours; storage_gib_hours: actual data disk usage GiB × hours; egress_gib: egress traffic in GiB; browser_hours: browser lease hours.

The new whsec_... (shown only this once); null if the secret was not rotated.

Maximum run time, after which the process is killed; 0 = no limit

You will write stdin later through attach; otherwise stdin is /dev/null

Number of environments switched at the same time per batch

Roll back automatically when failures exceed this number

Developer id.

owner: manages members, API keys and the webhook, plus everything a member can do; member: day-to-day operations.

Absolute file path (no .., not ending in /); parent directories are created.

base64 for binary content.

Octal permissions, default 0644.

The base version (name:version); null = the platform's default runtime.

building until the build finishes, then ready (environments can use it) or failed (see error and log).

Why the build failed.

Layers on top of the default runtime, including the base version's; 0 until the version is ready.

The command environments with this template run when they have no Agent package: a string (run with /bin/sh -c) or an argv array, started in the last workdir. With an Agent package, the package's /opt/agent/bin/start runs instead. Without either, the environment simply waits for exec.

The last 64 KiB of the build log: each step's command and its output.

building until the build finishes, then ready (environments can use it) or failed (see error and log).

null means developer-level (the total across all environments).

active_hours: hours the VM was running; cpu_hours: CPU time (hours); memory_gib_hours: VMM memory GiB × hours; storage_gib_hours: actual data disk usage GiB × hours; egress_gib: egress traffic in GiB; browser_hours: browser lease hours.

Used this month (UTC).

When the old secret expires after a rotation; null if there is no old secret still valid.

environment.<event>.

Event details; fields vary by event. Agent-related events carry source: agent; environment.limit_exceeded is {reason}.

Not lower than the current percentage

The path given in the request (unchanged)

Number of bytes written