Skip to content
EverrunsEverruns
Everruns Cloud is open in early access. Run agents without operating the platform.

get_session_sandbox

GET
/v1/sessions/{session_id}/sandbox
curl --request GET \
  --url https://app.everruns.com/api/v1/sessions/example/sandbox

Get the primary Sandbox a Session runs in: template, target, containment, and capabilities.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
session_id
required
string

Session ID

Responses

Section titled “ Responses ”

200

Section titled “200”

Resolved primary Session Sandbox

Media typeapplication/json

The primary Sandbox a Session is running in.

object
capabilities
required

What the Sandbox target can actually do.

Read this before assuming a shell behaves like Linux. Bashkit reports native_processes: false, which is why a build fails there; the answer is available before the first turn rather than after a confusing tool error.

object
native_processes
required

Whether commands can spawn operating-system processes.

boolean
network_enforced
required

Whether the target enforces the declared outbound network policy.

boolean
packages
required

Whether the runtime can install operating-system packages.

boolean
portable_checkpoint
required

Whether filesystem state has a portable checkpoint representation.

boolean
ports
required

Whether workloads can bind and expose network ports.

boolean
pty
required

Whether interactive pseudo-terminals are supported.

boolean
containment
required

What commands may touch, and who enforces it.

object
level
required

none, native, or isolated.

string
network
required

Outbound network policy: deny, allowlist, or allow.

string
current_checkpoint_id

Most recent checkpoint used to recover this logical Sandbox.

string | null
desired_state

Control-plane lifecycle intent and latest observed physical state.

string | null
durability
required

checkpointed, provider_snapshot, or none. Declared per target, so a session on somebody else’s machine is never reported as recoverable.

string
generation

Physical incarnation fence. Increments whenever compute is replaced.

integer | null format: int64
last_activity_at

Last recorded runtime activity used by lifecycle policy.

string | null format: date-time
name

Agent template binding selected for this Session (inline for one-offs).

string | null
observed_state

Latest lifecycle state observed from the physical provider resource.

string | null
resolved_from
required

How this view was produced. capabilities means it was derived from the Session’s effective capability set rather than a stored Sandbox spec.

string
role

primary for the implicit shell/files binding.

string | null
sandbox_id

Durable logical primary Sandbox id. Absent for legacy capability-derived sessions.

string | null
sandbox_template_revision_id

Reusable Sandbox Template revision pinned into this Sandbox.

string | null
source_capability

Capability that supplied the compute, for operators tracing a surprise.

string | null
spec
One of:

Immutable resolved specification pinned when the Session was created.

object
bootstrap
required

Pinned initialization commands.

object
commands

Ordered commands replayed when creating or recovering physical compute.

Array<string>
containment
required

Fully resolved containment contract.

object
escalation

Whether the runtime may widen containment after Session creation.

string
Allowed values: never approval auto
filesystem

Filesystem mutation boundary for command execution.

object
writable_roots

Absolute roots the runtime may mutate; empty means provider default.

Array<string>
level
required

Isolation mechanism the provider must supply.

string
Allowed values: none native isolated
network
One of:
object
mode
required
string
Allowed values: deny
durability
required

Fully resolved recovery guarantee.

string
Allowed values: checkpointed provider_snapshot none
lifecycle
required

Pinned lifecycle policy.

object
idle_action

Action Everruns requests after the idle interval.

string
Allowed values: checkpoint_and_stop stop keep_running
idle_after_seconds

Inactivity interval before applying idle_action.

integer format: int64
target
required

Exact target pinned for the Session.

object
connection_id

Credential/transport binding for a registered machine target.

string | null
kind
required

Provider-neutral target class.

string
Allowed values: host machine vfs container managed
options

Provider-owned, non-secret configuration. Credentials are references, never values in this object.

object
provider

Concrete adapter for target kinds with more than one implementation.

string | null
template_revision_id

Reusable revision from which this complete snapshot was copied.

string | null
target
One of:

Target, absent when the session has no compute at all and only reads and writes files. That is a real configuration, not a misconfiguration.

object
connection_id

Registered connection used by a machine target.

string | null
kind
required

Shape of the target: host, machine, vfs, container, managed.

string
provider

Concrete provider, when the kind has one (bashkit, daytona, …).

string | null
Example
{
  "capabilities": {
    "native_processes": false,
    "network_enforced": true,
    "packages": false,
    "portable_checkpoint": true,
    "ports": false,
    "pty": false
  },
  "containment": {
    "level": "isolated",
    "network": "deny"
  },
  "durability": "checkpointed",
  "resolved_from": "capabilities",
  "source_capability": "bashkit_shell",
  "target": {
    "kind": "vfs",
    "provider": "bashkit"
  }
}

404

Section titled “404”

Session not found