Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

feat: onResume option on connect/resume (#1800)

Babis Chalios1980d6bf5b46
diff --git a/.changeset/on-resume-reboot.md b/.changeset/on-resume-reboot.md
new file mode 100644
index 000000000..7cf9fa2d5
--- /dev/null
+++ b/.changeset/on-resume-reboot.md
@@ -0,0 +1,6 @@
+---
+'e2b': minor
+'@e2b/python-sdk': minor
+---
+
+Add `onResume` / `on_resume` to `Sandbox.connect()`: `'reboot'` resumes a paused sandbox from its disk state alone, leaving the memory snapshot untouched, for the case where restoring that memory wedges the guest. `'restore'` stays the default. Where filesystem-only resume is not enabled, a `'reboot'` that would actually drop memory is rejected with an error rather than silently restoring it.
diff --git a/packages/js-sdk/src/api/schema.gen.ts b/packages/js-sdk/src/api/schema.gen.ts
index a72a37aa1..5bccee804 100644
--- a/packages/js-sdk/src/api/schema.gen.ts
+++ b/packages/js-sdk/src/api/schema.gen.ts
@@ -524,7 +524,7 @@ export interface paths {
};
cookie?: never;
};
- requestBody: {
+ requestBody?: {
content: {
"application/json": components["schemas"]["ResumedSandbox"];
};
@@ -2200,6 +2200,8 @@ export interface components {
step?: string;
};
ConnectSandbox: {
+ /** @description Defaults to true. When false and the sandbox is paused, resume from disk state only: the sandbox cold-boots fresh and any memory in the snapshot is ignored, never modified or deleted. Disk state has crash-recovery semantics — writes not flushed before the pause may be lost. A no-op for snapshots that contain no memory. Rejected with an error in environments where this capability is not enabled, never silently downgraded to a memory restore. */
+ memory?: boolean;
/**
* Format: int32
* @description Timeout in seconds from the current time after which the sandbox should expire
@@ -2383,6 +2385,8 @@ export interface components {
* @description Automatically pauses the sandbox after the timeout
*/
autoPause?: boolean;
+ /** @description Defaults to true. When false, resume from disk state only: the sandbox cold-boots fresh and any memory in the snapshot is ignored, never modified or deleted. Disk state has crash-recovery semantics — writes not flushed before the pause may be lost. A no-op for snapshots that contain no memory. Rejected with an error in environments where this capability is not enabled, never silently downgraded to a memory restore. */
+ memory?: boolean;
/**
* Format: int32
* @description Time to live for the sandbox in seconds.
@@ -2609,9 +2613,11 @@ export interface components {
/** @description List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules. */
denyOut?: string[];
egressProxy?: components["schemas"]["SandboxEgressProxyConfig"];
+ /** @description Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not verified, so self-signed ones work. The envd port (49983) cannot be listed. */
+ httpsPorts?: number[];
/** @description Specify host mask which will be used for all sandbox requests */
maskRequestHost?: string;
- /** @description Per-domain transform rules applied to matching egress HTTP/HTTPS requests. Keys are domains (e.g. "api.example.com", "example.com"). A domain listed here is not automatically allowed - use allowOut to permit the traffic. */
+ /** @description Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination. */
rules?: {
[key: string]: components["schemas"]["SandboxNetworkRule"][];
};
@@ -2636,7 +2642,7 @@ export interface components {
/** @description List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules. */
denyOut?: string[];
egressProxy?: components["schemas"]["SandboxEgressProxyConfig"];
- /** @description Per-domain transform rules. Replaces all existing rules when provided. */
+ /** @description Per-domain transform rules applied to matching outbound HTTPS requests. Replaces all existing rules when provided. Keys may be exact DNS names or a single leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination. */
rules?: {
[key: string]: components["schemas"]["SandboxNetworkRule"][];
};
diff --git a/packages/js-sdk/src/index.ts b/packages/js-sdk/src/index.ts
index a803efcda..8d1e15c28 100644
--- a/packages/js-sdk/src/index.ts
+++ b/packages/js-sdk/src/index.ts
@@ -60,6 +60,7 @@ export type {
SandboxOpts,
SandboxApiOpts,
SandboxConnectOpts,
+ SandboxOnResume,
SandboxForkOpts,
SandboxMetricsOpts,
SandboxPauseOpts,
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index 2a4ba298f..be60ab1fb 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -662,6 +662,16 @@ export interface SandboxOpts extends ConnectionOpts {
lifecycle?: SandboxLifecycle
}
+/**
+ * How a paused sandbox comes back.
+ *
+ * `'restore'` restores the memory snapshot, so processes and open connections
+ * survive the pause. `'reboot'` ignores any memory in the snapshot and
+ * cold-boots from disk state alone — the rescue path for a snapshot whose
+ * memory image wedges the guest.
+ */
+export type SandboxOnResume = 'restore' | 'reboot'
+
/**
* Options for connecting to a Sandbox.
*/
@@ -674,6 +684,17 @@ export type SandboxConnectOpts = ConnectionOpts & {
* @default 300_000 // 5 minutes
*/
timeoutMs?: number
+
+ /**
+ * How to bring a paused sandbox back: `'restore'` (the default) restores the
+ * memory snapshot; `'reboot'` cold-boots from disk state, so writes not
+ * flushed before the pause may be lost. Rejected where filesystem-only resume
+ * is not enabled; a no-op for a snapshot without memory or a sandbox that is
+ * already running.
+ *
+ * @default 'restore'
+ */
+ onResume?: SandboxOnResume
}
/**
@@ -1796,6 +1817,7 @@ export class SandboxApi extends ClientFactory {
},
body: {
timeout: timeoutToSeconds(timeoutMs),
+ memory: apiOpts?.onResume === 'reboot' ? false : undefined,
},
signal: config.getSignal(apiOpts?.requestTimeoutMs, apiOpts?.signal),
})
diff --git a/packages/js-sdk/tests/sandbox/onResumeRequest.test.ts b/packages/js-sdk/tests/sandbox/onResumeRequest.test.ts
new file mode 100644
index 000000000..f62a4dd35
--- /dev/null
+++ b/packages/js-sdk/tests/sandbox/onResumeRequest.test.ts
@@ -0,0 +1,80 @@
+import { afterAll, afterEach, beforeAll, expect, test } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+import { Sandbox } from '../../src'
+import { TEST_API_KEY, apiUrl } from '../setup'
+
+let lastConnectBody: Record<string, unknown> | undefined
+
+const server = setupServer(
+ http.post(apiUrl('/sandboxes/:sandboxID/connect'), async ({ request }) => {
+ lastConnectBody = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json({
+ sandboxID: 'test-sandbox-id',
+ templateID: 'base',
+ envdVersion: '0.2.4',
+ })
+ })
+)
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+
+afterAll(() => server.close())
+
+afterEach(() => {
+ lastConnectBody = undefined
+ server.resetHandlers()
+})
+
+test('Sandbox.connect omits memory when onResume is not given', async () => {
+ await Sandbox.connect('test-sandbox-id', { apiKey: TEST_API_KEY })
+
+ expect(lastConnectBody).toBeDefined()
+ expect(lastConnectBody).not.toHaveProperty('memory')
+})
+
+test("Sandbox.connect omits memory for onResume: 'restore'", async () => {
+ // 'restore' is the API's own default, so it must travel as an absent field
+ // rather than memory: true — the two are not interchangeable on the wire.
+ await Sandbox.connect('test-sandbox-id', {
+ apiKey: TEST_API_KEY,
+ onResume: 'restore',
+ })
+
+ expect(lastConnectBody).not.toHaveProperty('memory')
+})
+
+test("Sandbox.connect sends memory: false for onResume: 'reboot'", async () => {
+ await Sandbox.connect('test-sandbox-id', {
+ apiKey: TEST_API_KEY,
+ onResume: 'reboot',
+ })
+
+ expect(lastConnectBody?.memory).toBe(false)
+})
+
+test('sandbox.connect carries onResume on the instance form too', async () => {
+ const sandbox = await Sandbox.connect('test-sandbox-id', {
+ apiKey: TEST_API_KEY,
+ })
+ lastConnectBody = undefined
+
+ await sandbox.connect({ onResume: 'reboot' })
+ expect(lastConnectBody?.memory).toBe(false)
+
+ await sandbox.connect()
+ expect(lastConnectBody).not.toHaveProperty('memory')
+})
+
+test('an untyped onResume value never sends memory: false', async () => {
+ // Untyped callers can pass anything; only the 'reboot' literal opts into a
+ // cold boot, so an unrecognized value must fall back to a memory restore.
+ await Sandbox.connect('test-sandbox-id', {
+ apiKey: TEST_API_KEY,
+ // @ts-expect-error 'Reboot' is not a valid onResume value
+ onResume: 'Reboot',
+ })
+
+ expect(lastConnectBody).not.toHaveProperty('memory')
+})
diff --git a/packages/python-sdk/e2b/__init__.py b/packages/python-sdk/e2b/__init__.py
index 1d3cac9f4..03ab1bcbc 100644
--- a/packages/python-sdk/e2b/__init__.py
+++ b/packages/python-sdk/e2b/__init__.py
@@ -100,6 +100,7 @@ from .sandbox.sandbox_api import (
SandboxNetworkTransformContext,
SandboxNetworkTransformResolver,
SandboxNetworkUpdate,
+ SandboxOnResume,
SandboxListOrder,
SandboxQuery,
SandboxState,
@@ -233,6 +234,7 @@ __all__ = [
"SandboxNetworkUpdate",
"SandboxLifecycle",
"SandboxOnTimeout",
+ "SandboxOnResume",
"ALL_TRAFFIC",
# IAM
"SandboxIamOpts",
diff --git a/packages/python-sdk/e2b/api/client/models/connect_sandbox.py b/packages/python-sdk/e2b/api/client/models/connect_sandbox.py
index de7a8f8c1..f71f62641 100644
--- a/packages/python-sdk/e2b/api/client/models/connect_sandbox.py
+++ b/packages/python-sdk/e2b/api/client/models/connect_sandbox.py
@@ -1,9 +1,11 @@
from collections.abc import Mapping
-from typing import Any, TypeVar
+from typing import Any, TypeVar, Union
from attrs import define as _attrs_define
from attrs import field as _attrs_field
+from ..types import UNSET, Unset
+
T = TypeVar("T", bound="ConnectSandbox")
@@ -12,14 +14,22 @@ class ConnectSandbox:
"""
Attributes:
timeout (int): Timeout in seconds from the current time after which the sandbox should expire
+ memory (Union[Unset, bool]): Defaults to true. When false and the sandbox is paused, resume from disk state
+ only: the sandbox cold-boots fresh and any memory in the snapshot is ignored, never modified or deleted. Disk
+ state has crash-recovery semantics — writes not flushed before the pause may be lost. A no-op for snapshots that
+ contain no memory. Rejected with an error in environments where this capability is not enabled, never silently
+ downgraded to a memory restore.
"""
timeout: int
+ memory: Union[Unset, bool] = UNSET
additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
def to_dict(self) -> dict[str, Any]:
timeout = self.timeout
+ memory = self.memory
+
field_dict: dict[str, Any] = {}
field_dict.update(self.additional_properties)
field_dict.update(
@@ -27,6 +37,8 @@ class ConnectSandbox:
"timeout": timeout,
}
)
+ if memory is not UNSET:
+ field_dict["memory"] = memory
return field_dict
@@ -35,8 +47,11 @@ class ConnectSandbox:
d = dict(src_dict)
timeout = d.pop("timeout")
+ memory = d.pop("memory", UNSET)
+
connect_sandbox = cls(
timeout=timeout,
+ memory=memory,
)
connect_sandbox.additional_properties = d
diff --git a/packages/python-sdk/e2b/api/client/models/resumed_sandbox.py b/packages/python-sdk/e2b/api/client/models/resumed_sandbox.py
index 915e6ab67..f9e53a0e0 100644
--- a/packages/python-sdk/e2b/api/client/models/resumed_sandbox.py
+++ b/packages/python-sdk/e2b/api/client/models/resumed_sandbox.py
@@ -15,10 +15,16 @@ class ResumedSandbox:
Attributes:
timeout (Union[Unset, int]): Time to live for the sandbox in seconds. Default: 15.
auto_pause (Union[Unset, bool]): Automatically pauses the sandbox after the timeout
+ memory (Union[Unset, bool]): Defaults to true. When false, resume from disk state only: the sandbox cold-boots
+ fresh and any memory in the snapshot is ignored, never modified or deleted. Disk state has crash-recovery
+ semantics — writes not flushed before the pause may be lost. A no-op for snapshots that contain no memory.
+ Rejected with an error in environments where this capability is not enabled, never silently downgraded to a
+ memory restore.
"""
timeout: Union[Unset, int] = 15
auto_pause: Union[Unset, bool] = UNSET
+ memory: Union[Unset, bool] = UNSET
additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
def to_dict(self) -> dict[str, Any]:
@@ -26,6 +32,8 @@ class ResumedSandbox:
auto_pause = self.auto_pause
+ memory = self.memory
+
field_dict: dict[str, Any] = {}
field_dict.update(self.additional_properties)
field_dict.update({})
@@ -33,6 +41,8 @@ class ResumedSandbox:
field_dict["timeout"] = timeout
if auto_pause is not UNSET:
field_dict["autoPause"] = auto_pause
+ if memory is not UNSET:
+ field_dict["memory"] = memory
return field_dict
@@ -43,9 +53,12 @@ class ResumedSandbox:
auto_pause = d.pop("autoPause", UNSET)
+ memory = d.pop("memory", UNSET)
+
resumed_sandbox = cls(
timeout=timeout,
auto_pause=auto_pause,
+ memory=memory,
)
resumed_sandbox.additional_properties = d
diff --git a/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py b/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py
index 970666efe..108a93b2d 100644
--- a/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py
+++ b/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py
@@ -31,9 +31,16 @@ class SandboxNetworkConfig:
TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use
remote DNS (ATYP=domain).
mask_request_host (Union[Unset, str]): Specify host mask which will be used for all sandbox requests
- rules (Union[Unset, SandboxNetworkConfigRules]): Per-domain transform rules applied to matching egress
- HTTP/HTTPS requests. Keys are domains (e.g. "api.example.com", "example.com"). A domain listed here is not
- automatically allowed - use allowOut to permit the traffic.
+ https_ports (Union[Unset, list[int]]): Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how
+ the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not
+ verified, so self-signed ones work. The envd port (49983) cannot be listed.
+ rules (Union[Unset, SandboxNetworkConfigRules]): Per-domain transform rules applied to matching outbound HTTPS
+ requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example,
+ "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the
+ apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard
+ suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose
+ transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access;
+ configure allowOut separately to permit the destination.
"""
allow_public_traffic: Union[Unset, bool] = True
@@ -41,6 +48,7 @@ class SandboxNetworkConfig:
deny_out: Union[Unset, list[str]] = UNSET
egress_proxy: Union["SandboxEgressProxyConfigType0", None, Unset] = UNSET
mask_request_host: Union[Unset, str] = UNSET
+ https_ports: Union[Unset, list[int]] = UNSET
rules: Union[Unset, "SandboxNetworkConfigRules"] = UNSET
additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
@@ -69,6 +77,10 @@ class SandboxNetworkConfig:
mask_request_host = self.mask_request_host
+ https_ports: Union[Unset, list[int]] = UNSET
+ if not isinstance(self.https_ports, Unset):
+ https_ports = self.https_ports
+
rules: Union[Unset, dict[str, Any]] = UNSET
if not isinstance(self.rules, Unset):
rules = self.rules.to_dict()
@@ -86,6 +98,8 @@ class SandboxNetworkConfig:
field_dict["egressProxy"] = egress_proxy
if mask_request_host is not UNSET:
field_dict["maskRequestHost"] = mask_request_host
+ if https_ports is not UNSET:
+ field_dict["httpsPorts"] = https_ports
if rules is not UNSET:
field_dict["rules"] = rules
@@ -128,6 +142,8 @@ class SandboxNetworkConfig:
mask_request_host = d.pop("maskRequestHost", UNSET)
+ https_ports = cast(list[int], d.pop("httpsPorts", UNSET))
+
_rules = d.pop("rules", UNSET)
rules: Union[Unset, SandboxNetworkConfigRules]
if isinstance(_rules, Unset):
@@ -141,6 +157,7 @@ class SandboxNetworkConfig:
deny_out=deny_out,
egress_proxy=egress_proxy,
mask_request_host=mask_request_host,
+ https_ports=https_ports,
rules=rules,
)
diff --git a/packages/python-sdk/e2b/api/client/models/sandbox_network_config_rules.py b/packages/python-sdk/e2b/api/client/models/sandbox_network_config_rules.py
index aeece3851..e887c7b60 100644
--- a/packages/python-sdk/e2b/api/client/models/sandbox_network_config_rules.py
+++ b/packages/python-sdk/e2b/api/client/models/sandbox_network_config_rules.py
@@ -13,8 +13,12 @@ T = TypeVar("T", bound="SandboxNetworkConfigRules")
@_attrs_define
class SandboxNetworkConfigRules:
- """Per-domain transform rules applied to matching egress HTTP/HTTPS requests. Keys are domains (e.g. "api.example.com",
- "example.com"). A domain listed here is not automatically allowed - use allowOut to permit the traffic.
+ """Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example,
+ "api.example.com") or a leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write.
+ Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence,
+ followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as
+ "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules
+ do not grant network access; configure allowOut separately to permit the destination.
"""
diff --git a/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config.py b/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config.py
index 1a47ddc7f..3ea8371d8 100644
--- a/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config.py
+++ b/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config.py
@@ -32,8 +32,13 @@ class SandboxNetworkUpdateConfig:
egress_proxy (Union['SandboxEgressProxyConfigType0', None, Unset]): SOCKS5 proxy for sandbox egress. Outbound
TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use
remote DNS (ATYP=domain).
- rules (Union[Unset, SandboxNetworkUpdateConfigRules]): Per-domain transform rules. Replaces all existing rules
- when provided.
+ rules (Union[Unset, SandboxNetworkUpdateConfigRules]): Per-domain transform rules applied to matching outbound
+ HTTPS requests. Replaces all existing rules when provided. Keys may be exact DNS names or a single leading
+ wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at
+ any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest
+ matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and
+ may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant
+ network access; configure allowOut separately to permit the destination.
allow_internet_access (Union[Unset, bool]): Allow sandbox to access the internet. When set to false, it behaves
the same as specifying denyOut to 0.0.0.0/0 in the network config.
"""
diff --git a/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config_rules.py b/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config_rules.py
index 58d268a27..0079742a8 100644
--- a/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config_rules.py
+++ b/packages/python-sdk/e2b/api/client/models/sandbox_network_update_config_rules.py
@@ -13,7 +13,14 @@ T = TypeVar("T", bound="SandboxNetworkUpdateConfigRules")
@_attrs_define
class SandboxNetworkUpdateConfigRules:
- """Per-domain transform rules. Replaces all existing rules when provided."""
+ """Per-domain transform rules applied to matching outbound HTTPS requests. Replaces all existing rules when provided.
+ Keys may be exact DNS names or a single leading wildcard (for example, "*.example.com"), and are normalized to
+ lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact
+ rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged.
+ Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the
+ sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination.
+
+ """
additional_properties: dict[str, list["SandboxNetworkRule"]] = _attrs_field(
init=False, factory=dict
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index 14a2c1f2e..f8302eadc 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -570,6 +570,17 @@ class SandboxInfoLifecycle(TypedDict):
"""
+SandboxOnResume = Literal["restore", "reboot"]
+"""
+How a paused sandbox comes back.
+
+``"restore"`` restores the memory snapshot, so processes and open connections
+survive the pause. ``"reboot"`` ignores any memory in the snapshot and
+cold-boots from disk state alone — the rescue path for a snapshot whose memory
+image wedges the guest.
+"""
+
+
def _resolve_network_selector(
selector: Optional[SandboxNetworkSelector],
rules: Mapping[str, List[SandboxNetworkRule]],
diff --git a/packages/python-sdk/e2b/sandbox_async/main.py b/packages/python-sdk/e2b/sandbox_async/main.py
index df3b16387..7b1d7253d 100644
--- a/packages/python-sdk/e2b/sandbox_async/main.py
+++ b/packages/python-sdk/e2b/sandbox_async/main.py
@@ -29,6 +29,7 @@ from e2b.sandbox.sandbox_api import (
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
+ SandboxOnResume,
SnapshotInfo,
)
from e2b.sandbox.utils import class_method_variant
@@ -266,6 +267,8 @@ class AsyncSandbox(SandboxApi):
async def connect(
self,
timeout: Optional[int] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
"""
@@ -276,6 +279,10 @@ class AsyncSandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -295,6 +302,8 @@ class AsyncSandbox(SandboxApi):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> "AsyncSandbox":
"""
@@ -307,6 +316,10 @@ class AsyncSandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -324,6 +337,8 @@ class AsyncSandbox(SandboxApi):
async def connect(
self,
timeout: Optional[int] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
"""
@@ -334,6 +349,10 @@ class AsyncSandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -352,6 +371,7 @@ class AsyncSandbox(SandboxApi):
await SandboxApi._cls_connect(
sandbox_id=self.sandbox_id,
timeout=timeout,
+ on_resume=on_resume,
**self.connection_config.get_api_params(**opts),
)
@@ -1010,6 +1030,8 @@ class AsyncSandbox(SandboxApi):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
params = cls._resolve_api_params(**opts)
@@ -1023,6 +1045,7 @@ class AsyncSandbox(SandboxApi):
sandbox = await SandboxApi._cls_connect(
sandbox_id=sandbox_id,
timeout=timeout,
+ on_resume=on_resume,
logger=logger,
**params,
)
diff --git a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
index b6a208d6a..b4171327f 100644
--- a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
@@ -56,6 +56,7 @@ from e2b.sandbox.sandbox_api import (
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
+ SandboxOnResume,
SandboxQuery,
SnapshotInfo,
build_iam_config,
@@ -526,6 +527,8 @@ class SandboxApi(SandboxBase):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> SandboxCreateResponse:
timeout = timeout or SandboxBase.default_sandbox_timeout
@@ -537,7 +540,10 @@ class SandboxApi(SandboxBase):
res = await post_sandboxes_sandbox_id_connect.asyncio_detailed(
sandbox_id,
client=api_client,
- body=ConnectSandbox(timeout=timeout),
+ body=ConnectSandbox(
+ timeout=timeout,
+ memory=False if on_resume == "reboot" else UNSET,
+ ),
)
if res.status_code == 404:
diff --git a/packages/python-sdk/e2b/sandbox_sync/main.py b/packages/python-sdk/e2b/sandbox_sync/main.py
index 9c5d40f0d..80b4ff1e9 100644
--- a/packages/python-sdk/e2b/sandbox_sync/main.py
+++ b/packages/python-sdk/e2b/sandbox_sync/main.py
@@ -28,6 +28,7 @@ from e2b.sandbox.sandbox_api import (
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
+ SandboxOnResume,
SnapshotInfo,
)
from e2b.sandbox.utils import class_method_variant
@@ -260,6 +261,8 @@ class Sandbox(SandboxApi):
def connect(
self,
timeout: Optional[int] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
"""
@@ -270,6 +273,10 @@ class Sandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -290,6 +297,8 @@ class Sandbox(SandboxApi):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> "Sandbox":
"""
@@ -302,6 +311,10 @@ class Sandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**.
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -319,6 +332,8 @@ class Sandbox(SandboxApi):
def connect(
self,
timeout: Optional[int] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
"""
@@ -329,6 +344,10 @@ class Sandbox(SandboxApi):
:param timeout: Timeout for the sandbox in **seconds**.
For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
+ :param on_resume: `"restore"` (the default) restores the memory snapshot; `"reboot"`
+ cold-boots from disk state, so writes not flushed before the pause may be lost.
+ Rejected where filesystem-only resume is not enabled; a no-op for a snapshot
+ without memory or a sandbox that is already running.
:return: A running sandbox instance
@example
@@ -347,6 +366,7 @@ class Sandbox(SandboxApi):
SandboxApi._cls_connect(
sandbox_id=self.sandbox_id,
timeout=timeout,
+ on_resume=on_resume,
**self.connection_config.get_api_params(**opts),
)
@@ -1006,6 +1026,8 @@ class Sandbox(SandboxApi):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> Self:
params = cls._resolve_api_params(**opts)
@@ -1019,6 +1041,7 @@ class Sandbox(SandboxApi):
sandbox = SandboxApi._cls_connect(
sandbox_id=sandbox_id,
timeout=timeout,
+ on_resume=on_resume,
logger=logger,
**params,
)
diff --git a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
index ff8dc4a3e..d0d9d1656 100644
--- a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
@@ -55,6 +55,7 @@ from e2b.sandbox.sandbox_api import (
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
+ SandboxOnResume,
SandboxQuery,
SnapshotInfo,
build_iam_config,
@@ -341,6 +342,8 @@ class SandboxApi(SandboxBase):
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
+ *,
+ on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> SandboxCreateResponse:
timeout = timeout or SandboxBase.default_sandbox_timeout
@@ -351,7 +354,10 @@ class SandboxApi(SandboxBase):
res = post_sandboxes_sandbox_id_connect.sync_detailed(
sandbox_id,
client=api_client,
- body=ConnectSandbox(timeout=timeout),
+ body=ConnectSandbox(
+ timeout=timeout,
+ memory=False if on_resume == "reboot" else UNSET,
+ ),
)
if res.status_code == 404:
diff --git a/packages/python-sdk/tests/shared/sandbox/test_on_resume_request.py b/packages/python-sdk/tests/shared/sandbox/test_on_resume_request.py
new file mode 100644
index 000000000..7338ab3d2
--- /dev/null
+++ b/packages/python-sdk/tests/shared/sandbox/test_on_resume_request.py
@@ -0,0 +1,146 @@
+import inspect
+from types import SimpleNamespace
+from typing import Any, Dict, Optional, cast
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from e2b import AsyncSandbox, Sandbox
+from e2b.api.client.api.sandboxes import post_sandboxes_sandbox_id_connect
+from e2b.api.client.models import Sandbox as SandboxModel
+from e2b.sandbox_async.sandbox_api import SandboxApi as AsyncSandboxApi
+from e2b.sandbox_sync.sandbox_api import SandboxApi as SyncSandboxApi
+
+SANDBOX_ID = "sbx-test"
+
+
+def _connected_sandbox():
+ return SimpleNamespace(
+ status_code=200,
+ parsed=SandboxModel(
+ client_id="client-id",
+ envd_version="0.2.4",
+ sandbox_id=SANDBOX_ID,
+ template_id="template-id",
+ ),
+ )
+
+
+def _sync_request_body(monkeypatch, api_key: str, **kwargs) -> Dict[str, Any]:
+ request = Mock(return_value=_connected_sandbox())
+ monkeypatch.setattr(post_sandboxes_sandbox_id_connect, "sync_detailed", request)
+
+ Sandbox.connect(SANDBOX_ID, api_key=api_key, **kwargs)
+
+ return request.call_args.kwargs["body"].to_dict()
+
+
+async def _async_request_body(monkeypatch, api_key: str, **kwargs) -> Dict[str, Any]:
+ request = AsyncMock(return_value=_connected_sandbox())
+ monkeypatch.setattr(post_sandboxes_sandbox_id_connect, "asyncio_detailed", request)
+
+ await AsyncSandbox.connect(SANDBOX_ID, api_key=api_key, **kwargs)
+
+ return request.call_args.kwargs["body"].to_dict()
+
+
+# `None` expects memory to be absent from the payload: "restore" is the API's
+# own default, so it travels as an omitted field rather than memory: True.
+MEMORY_CASES = [
+ pytest.param({}, None, id="default"),
+ pytest.param({"on_resume": "restore"}, None, id="explicit-restore"),
+ pytest.param({"on_resume": "reboot"}, False, id="reboot"),
+ # Untyped callers can pass anything; only the "reboot" literal opts into a
+ # cold boot, so an unrecognized value must fall back to a memory restore.
+ pytest.param(cast(Any, {"on_resume": "Reboot"}), None, id="unrecognized-value"),
+]
+
+
[email protected]("kwargs, memory", MEMORY_CASES)
+def test_connect_sends_memory_only_for_reboot(
+ monkeypatch, test_api_key, kwargs, memory: Optional[bool]
+):
+ body = _sync_request_body(monkeypatch, test_api_key, **kwargs)
+
+ if memory is None:
+ assert "memory" not in body
+ else:
+ assert body["memory"] is memory
+
+
[email protected]("kwargs, memory", MEMORY_CASES)
+async def test_async_connect_sends_memory_only_for_reboot(
+ monkeypatch, test_api_key, kwargs, memory: Optional[bool]
+):
+ body = await _async_request_body(monkeypatch, test_api_key, **kwargs)
+
+ if memory is None:
+ assert "memory" not in body
+ else:
+ assert body["memory"] is memory
+
+
+def test_instance_connect_carries_on_resume(monkeypatch, test_api_key):
+ request = Mock(return_value=_connected_sandbox())
+ monkeypatch.setattr(post_sandboxes_sandbox_id_connect, "sync_detailed", request)
+
+ sandbox = Sandbox.connect(SANDBOX_ID, api_key=test_api_key)
+
+ sandbox.connect(on_resume="reboot")
+ assert request.call_args.kwargs["body"].to_dict()["memory"] is False
+
+ sandbox.connect()
+ assert "memory" not in request.call_args.kwargs["body"].to_dict()
+
+
+async def test_async_instance_connect_carries_on_resume(monkeypatch, test_api_key):
+ request = AsyncMock(return_value=_connected_sandbox())
+ monkeypatch.setattr(post_sandboxes_sandbox_id_connect, "asyncio_detailed", request)
+
+ sandbox = await AsyncSandbox.connect(SANDBOX_ID, api_key=test_api_key)
+
+ await sandbox.connect(on_resume="reboot")
+ assert request.call_args.kwargs["body"].to_dict()["memory"] is False
+
+ await sandbox.connect()
+ assert "memory" not in request.call_args.kwargs["body"].to_dict()
+
+
+# `class_method_variant` wraps the instance method with `functools.wraps`, so
+# `inspect.signature(Sandbox.connect)` resolves to `(self, timeout, *, on_resume)`
+# and never sees the static-by-id chain.
+KEYWORD_ONLY_FORMS = [
+ pytest.param(Sandbox, "_cls_connect_sandbox", id="sync-by-id"),
+ pytest.param(AsyncSandbox, "_cls_connect_sandbox", id="async-by-id"),
+ pytest.param(SyncSandboxApi, "_cls_connect", id="sync-api"),
+ pytest.param(AsyncSandboxApi, "_cls_connect", id="async-api"),
+]
+
+
[email protected]("owner, attr", KEYWORD_ONLY_FORMS)
+def test_on_resume_is_keyword_only(owner, attr):
+ # An optional parameter must not extend the positional chain, or
+ # `connect(sandbox_id, 300, logger, "reboot")` becomes a valid call.
+ signature = inspect.signature(getattr(owner, attr))
+
+ assert signature.parameters["on_resume"].kind is inspect.Parameter.KEYWORD_ONLY
+ for pre_existing in ("timeout", "logger"):
+ assert (
+ signature.parameters[pre_existing].kind
+ is not inspect.Parameter.KEYWORD_ONLY
+ )
+
+ with pytest.raises(TypeError):
+ signature.bind(SANDBOX_ID, 300, None, "reboot")
+
+ assert signature.bind(SANDBOX_ID, on_resume="reboot").arguments["on_resume"] == (
+ "reboot"
+ )
+
+
[email protected]("sandbox", [Sandbox, AsyncSandbox], ids=["sync", "async"])
+def test_on_resume_is_keyword_only_on_the_instance_form(sandbox):
+ signature = inspect.signature(sandbox.connect)
+
+ assert signature.parameters["on_resume"].kind is inspect.Parameter.KEYWORD_ONLY
+ assert signature.parameters["timeout"].kind is not inspect.Parameter.KEYWORD_ONLY
diff --git a/spec/envd/envd.yaml b/spec/envd/envd.yaml
index a6c050009..d385e6d58 100644
--- a/spec/envd/envd.yaml
+++ b/spec/envd/envd.yaml
@@ -96,14 +96,43 @@ paths:
what this call caused.
Best-effort by design: a workload that will not quiesce within the budget is
- reported as unconfirmed rather than failing the call, and cgroups that reject the
- write are counted in failed, because neither an unfreezable customer task nor a
- cgroup disappearing mid-sweep may block their pause.
+ reported as unconfirmed rather than failing the call, cgroups that reject the write
+ are counted in failed, and cgroups the guest removed while the sweep was working on
+ them are counted in vanished. None of the three may block a pause, which is why all
+ three are counts in the body rather than an error.
Whether this endpoint waits is the caller's choice, expressed by supplying
maxWaitMs: see that parameter.
x-internal: true
parameters:
+ - name: mode
+ in: query
+ required: false
+ description: |
+ Which cgroups to freeze. "hierarchy" freezes the complement of envd's own
+ ancestor chain, so cgroups the customer created anywhere in the tree are
+ covered; "legacy" freezes only the user and pty cgroups envd itself creates.
+ Omitted means legacy, which is what an orchestrator predating this parameter
+ gets.
+
+ The mode is chosen by the caller because the feature flag that selects it is
+ evaluated there — envd has no access to it. FreezeResult echoes the mode back
+ so the caller can confirm envd honoured the request rather than inferring it
+ from the flag's value: an envd too old to know about modes reports legacy
+ while the flag reads on.
+ schema:
+ type: string
+ enum: [legacy, hierarchy]
+ - name: maxCgroups
+ in: query
+ required: false
+ description: |
+ Bounds how many cgroups a hierarchy sweep may visit. A safety guard against a
+ pathological or hostile hierarchy rather than a performance knob — the guest is
+ the threat model. Omitted or non-positive means envd's own default. Ignored in
+ legacy mode.
+ schema:
+ type: integer
- name: maxWaitMs
in: query
required: false
@@ -522,6 +551,22 @@ components:
type: object
description: Per-call statistics from a pre-pause workload freeze
properties:
+ mode:
+ type: string
+ enum: [legacy, hierarchy]
+ description: Which sweep actually ran. Echoed back rather than inferred from the flag, so a caller can tell that envd honoured what it asked for
+ visited:
+ type: integer
+ description: Cgroups the walk examined, whether or not it froze them. The input for sizing the bound; meaningless in legacy mode
+ allowlisted:
+ type: integer
+ description: Cgroups skipped because the resume path depends on them (systemd, journald, envd's port forwarding). Reported because the allowlist is expected to grow, and a distro that routes journald differently changes this count
+ truncated:
+ type: boolean
+ description: True when the walk stopped because it hit the bound rather than because it ran out of tree, so coverage is incomplete
+ preFrozen:
+ type: integer
+ description: Cgroups the guest itself had already frozen before the sweep ran (docker pause writes cgroup.freeze). Not written to and deliberately left frozen by the resume thaw, so the guest's own suspension survives the snapshot
requested:
type: integer
description: Cgroups this call wrote cgroup.freeze to
@@ -533,7 +578,10 @@ components:
description: Cgroups still reading "frozen 0" when the budget expired; their tasks may still be running, so a snapshot taken now can capture a live workload
failed:
type: integer
- description: Cgroups whose freeze write or state read errored (expected for a threaded cgroup, and for one removed mid-sweep)
+ description: Cgroups that errored for a reason that is not simply being gone - the write was refused, or the state could not be read. A cgroup the hierarchy walk discovered that merely went away is counted vanished instead; one of envd's own static cgroups that goes away is counted here, by design
+ vanished:
+ type: integer
+ description: Cgroups the hierarchy walk enumerated that the guest then removed before the sweep finished with them - envd's own static cgroups are excluded and report failed instead. A race rather than a failure, and a claim about the cgroup only - tasks migrated out of it before its removal can still be running. Like failed it spans both phases, so it does not reconcile against requested on its own - one removed during the settle poll was counted in requested, one removed before its write never was
unobservable:
type: integer
description: Cgroups whose freeze state cannot be read because this guest has no cgroup manager; the write was accepted but nothing can be read back, so these are neither frozen nor notFrozen
diff --git a/spec/infra-ref b/spec/infra-ref
index 40c51438b..564edb1f3 100644
--- a/spec/infra-ref
+++ b/spec/infra-ref
@@ -1 +1 @@
-e19a12b8fc5d318c6e88a8edba0a94d1f153a841
+8a3f69da6f822c2de2b310dd1076d2c309eef919
diff --git a/spec/openapi.yml b/spec/openapi.yml
index 6ddde58ad..7018094d2 100644
--- a/spec/openapi.yml
+++ b/spec/openapi.yml
@@ -12,14 +12,6 @@ components:
type: apiKey
in: header
name: X-API-Key
- AccessTokenAuth:
- type: http
- scheme: bearer
- bearerFormat: access_token
- description: |
- **Deprecated.** Access token authentication is deprecated and will be
- removed in a future release. Use API key authentication (`X-API-Key`)
- instead.
# AuthProviderBearerAuth / AuthProviderTeamAuth: B before T in the name
# so Bearer is validated before Team.
AuthProviderBearerAuth:
@@ -36,12 +28,31 @@ components:
type: apiKey
in: header
name: X-Admin-Token
+ AdminJWTAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
AdminTeamAuth:
type: apiKey
in: header
name: X-Team-ID
parameters:
+ clusterID:
+ name: clusterID
+ in: path
+ required: true
+ schema:
+ type: string
+ format: uuid
+ description: Identifier of the cluster
+ rigID:
+ name: rigID
+ in: path
+ required: true
+ schema:
+ type: string
+ description: Rig identifier (e.g. "default")
templateID:
name: templateID
in: path
@@ -78,12 +89,6 @@ components:
required: true
schema:
type: string
- accessTokenID:
- name: accessTokenID
- in: path
- required: true
- schema:
- type: string
snapshotID:
name: snapshotID
in: path
@@ -176,12 +181,6 @@ components:
application/json:
schema:
$ref: "#/components/schemas/Error"
- "410":
- description: Gone
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/Error"
"429":
description: Too many requests
content:
@@ -194,6 +193,12 @@ components:
application/json:
schema:
$ref: "#/components/schemas/Error"
+ "501":
+ description: Not implemented by this deployment
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
"502":
description: Backend error
content:
@@ -214,6 +219,103 @@ components:
$ref: "#/components/schemas/Error"
schemas:
+ Rig:
+ description: An orchestrator node pool backed by one cloud scaling group
+ required:
+ - id
+ - provider
+ - resourceID
+ - capacityDesired
+ - capacityCurrent
+ properties:
+ id:
+ type: string
+ description: Rig identifier (e.g. "default")
+ provider:
+ type: string
+ description: Cloud provider backing the rig ("aws" or "gcp")
+ resourceID:
+ type: string
+ description: Canonical cloud resource ID of the scaling group backing the rig (ARN on AWS, self-link on GCP)
+ capacityDesired:
+ type: integer
+ format: int32
+ description: Desired number of instances in the rig
+ capacityMin:
+ type: integer
+ format: int32
+ description: >
+ Minimum capacity enforced on the rig's scaling group. Omitted when
+ nothing enforces bounds (GCP MIG without an active autoscaler).
+ capacityMax:
+ type: integer
+ format: int32
+ description: >
+ Maximum capacity enforced on the rig's scaling group. Omitted when
+ nothing enforces bounds (GCP MIG without an active autoscaler).
+ capacityCurrent:
+ type: integer
+ format: int32
+ description: Number of instances currently attached to the rig
+
+ RigCapacityChange:
+ description: Desired capacity to set on the rig's scaling group
+ required:
+ - desired
+ properties:
+ desired:
+ type: integer
+ format: int32
+ minimum: 0
+ description: Absolute desired number of instances in the rig
+
+ RigInstance:
+ description: An instance attached to a rig's scaling group
+ required:
+ - id
+ - transitioning
+ - terminating
+ properties:
+ id:
+ type: string
+ description: Provider instance ID (EC2 instance ID on AWS, instance name on GCP), also the node ID the orchestrator reports
+ createdAt:
+ type: string
+ format: date-time
+ description: When the provider created the instance. Omitted while the instance is transitioning.
+ transitioning:
+ type: boolean
+ description: The provider is creating, deleting, recreating or otherwise mutating the instance
+ terminating:
+ type: boolean
+ description: The instance is on its way out of the group and can never become healthy again
+
+ RigError:
+ description: >
+ Scaling error on the rig's scaling group, e.g. a failed instance
+ creation due to resource exhaustion
+ required:
+ - timestamp
+ - code
+ - message
+ properties:
+ timestamp:
+ type: string
+ format: date-time
+ description: When the error occurred
+ code:
+ type: string
+ description: Provider-specific error code (e.g. ZONE_RESOURCE_POOL_EXHAUSTED, Failed)
+ message:
+ type: string
+ description: Human-readable error message
+ instance:
+ type: string
+ description: Instance the error relates to, if any
+ action:
+ type: string
+ description: Action being performed when the error occurred (e.g. CREATING)
+
Team:
required:
- teamID
@@ -356,12 +458,27 @@ components:
maskRequestHost:
type: string
description: Specify host mask which will be used for all sandbox requests
+ httpsPorts:
+ type: array
+ description: Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not verified, so self-signed ones work. The envd port (49983) cannot be listed.
+ maxItems: 128
+ uniqueItems: true
+ items:
+ type: integer
+ format: uint32
+ minimum: 1
+ maximum: 65535
rules:
type: object
description: >
- Per-domain transform rules applied to matching egress HTTP/HTTPS requests.
- Keys are domains (e.g. "api.example.com", "example.com").
- A domain listed here is not automatically allowed - use allowOut to permit the traffic.
+ Per-domain transform rules applied to matching outbound HTTPS requests.
+ Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard
+ (for example, "*.example.com"), and are normalized to lowercase on write.
+ Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid.
+ Exact rules take precedence, followed by the longest matching wildcard suffix, and
+ matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may
+ expose transformed credentials to every matching destination the sandbox contacts.
+ Rules do not grant network access; configure allowOut separately to permit the destination.
additionalProperties:
type: array
items:
@@ -385,7 +502,15 @@ components:
$ref: "#/components/schemas/SandboxEgressProxyConfig"
rules:
type: object
- description: Per-domain transform rules. Replaces all existing rules when provided.
+ description: >
+ Per-domain transform rules applied to matching outbound HTTPS requests. Replaces all
+ existing rules when provided. Keys may be exact DNS names or a single leading wildcard
+ (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match
+ subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take
+ precedence, followed by the longest matching wildcard suffix, and matching rule sets are
+ not merged. Broad wildcards such as "*.com" are allowed and may expose transformed
+ credentials to every matching destination the sandbox contacts. Rules do not grant
+ network access; configure allowOut separately to permit the destination.
additionalProperties:
type: array
items:
@@ -854,6 +979,15 @@ components:
type: boolean
deprecated: true
description: Automatically pauses the sandbox after the timeout
+ memory:
+ type: boolean
+ description: >-
+ Defaults to true. When false, resume from disk state only: the sandbox cold-boots fresh and
+ any memory in the snapshot is ignored, never modified or deleted. Disk
+ state has crash-recovery semantics — writes not flushed before the pause
+ may be lost. A no-op for snapshots that contain no memory. Rejected with
+ an error in environments where this capability is not enabled, never
+ silently downgraded to a memory restore.
ConnectSandbox:
type: object
@@ -865,6 +999,15 @@ components:
type: integer
format: int32
minimum: 0
+ memory:
+ type: boolean
+ description: >-
+ Defaults to true. When false and the sandbox is paused, resume from disk state only: the
+ sandbox cold-boots fresh and any memory in the snapshot is ignored, never
+ modified or deleted. Disk state has crash-recovery semantics — writes not
+ flushed before the pause may be lost. A no-op for snapshots that contain
+ no memory. Rejected with an error in environments where this capability
+ is not enabled, never silently downgraded to a memory restore.
SandboxTimeoutRequest:
type: object
@@ -1859,39 +2002,6 @@ components:
format: uint64
description: Number of sandbox create fails
- CreatedAccessToken:
- required:
- - id
- - name
- - token
- - mask
- - createdAt
- properties:
- id:
- type: string
- format: uuid
- description: Identifier of the access token
- name:
- type: string
- description: Name of the access token
- token:
- type: string
- description: The fully created access token
- mask:
- $ref: "#/components/schemas/IdentifierMaskingDetails"
- createdAt:
- type: string
- format: date-time
- description: Timestamp of access token creation
-
- NewAccessToken:
- required:
- - name
- properties:
- name:
- type: string
- description: Name of the access token
-
TeamAPIKey:
required:
- id
@@ -2198,7 +2308,6 @@ tags:
- name: templates
- name: sandboxes
- name: auth
- - name: access-tokens
- name: api-keys
- name: tags
- name: volumes
@@ -2221,7 +2330,6 @@ paths:
description: List all teams
tags: [auth]
security:
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
responses:
"200":
@@ -2248,6 +2356,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/teamID"
- in: query
@@ -2293,6 +2403,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/teamID"
- in: query
@@ -2344,6 +2456,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- name: metadata
in: query
@@ -2376,6 +2490,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -2411,6 +2527,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- name: metadata
in: query
@@ -2481,6 +2599,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- name: sandbox_ids
in: query
@@ -2519,6 +2639,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
- in: query
@@ -2561,6 +2683,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
- in: query
@@ -2620,6 +2744,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
responses:
@@ -2646,6 +2772,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
responses:
@@ -2669,6 +2797,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
- in: query
@@ -2716,6 +2846,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
requestBody:
@@ -2748,10 +2880,12 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
requestBody:
- required: true
+ required: false
content:
application/json:
schema:
@@ -2796,6 +2930,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
requestBody:
@@ -2837,6 +2973,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
requestBody:
@@ -2883,6 +3021,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
tags: [sandboxes]
requestBody:
content:
@@ -2911,6 +3051,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
tags: [sandboxes]
requestBody:
required: true
@@ -2942,6 +3084,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
tags: [sandboxes]
requestBody:
content:
@@ -2969,6 +3113,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/sandboxID"
requestBody:
@@ -3004,6 +3150,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- name: sandboxID
in: query
@@ -3047,6 +3195,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -3077,11 +3227,12 @@ paths:
tags: [templates]
security:
- ApiKeyAuth: []
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- in: query
required: false
@@ -3122,6 +3273,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -3149,12 +3302,13 @@ paths:
description: Get an upload link for a tar file containing build layer files
tags: [templates]
security:
- - AccessTokenAuth: []
- ApiKeyAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
- in: path
@@ -3188,11 +3342,12 @@ paths:
tags: [templates]
security:
- ApiKeyAuth: []
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- in: query
required: false
@@ -3219,7 +3374,6 @@ paths:
deprecated: true
tags: [templates]
security:
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
requestBody:
@@ -3254,6 +3408,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
- $ref: "#/components/parameters/paginationNextToken"
@@ -3278,7 +3434,6 @@ paths:
deprecated: true
tags: [templates]
security:
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
parameters:
@@ -3307,11 +3462,12 @@ paths:
tags: [templates]
security:
- ApiKeyAuth: []
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
responses:
@@ -3328,11 +3484,12 @@ paths:
tags: [templates]
security:
- ApiKeyAuth: []
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
requestBody:
@@ -3358,7 +3515,6 @@ paths:
deprecated: true
tags: [templates]
security:
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
parameters:
@@ -3383,6 +3539,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
- $ref: "#/components/parameters/buildID"
@@ -3407,11 +3565,12 @@ paths:
tags: [templates]
security:
- ApiKeyAuth: []
- - AccessTokenAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
requestBody:
@@ -3440,12 +3599,13 @@ paths:
description: Get template build info
tags: [templates]
security:
- - AccessTokenAuth: []
- ApiKeyAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
- $ref: "#/components/parameters/buildID"
@@ -3490,12 +3650,13 @@ paths:
description: Get template build logs
tags: [templates]
security:
- - AccessTokenAuth: []
- ApiKeyAuth: []
- AuthProviderBearerAuth: []
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
- $ref: "#/components/parameters/buildID"
@@ -3553,6 +3714,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -3584,6 +3747,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -3613,6 +3778,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/templateID"
responses:
@@ -3644,6 +3811,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- name: alias
in: path
@@ -3674,6 +3843,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- in: query
name: clusterID
@@ -3703,6 +3873,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- $ref: "#/components/parameters/nodeID"
- in: query
@@ -3731,6 +3902,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- $ref: "#/components/parameters/nodeID"
requestBody:
@@ -3757,6 +3929,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- name: teamID
in: path
@@ -3788,6 +3961,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
responses:
"200":
description: Running sandbox counts keyed by team ID
@@ -3807,6 +3981,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- name: teamID
in: path
@@ -3836,6 +4011,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- name: teamID
in: path
@@ -3875,6 +4051,7 @@ paths:
tags: [admin]
security:
- AdminApiKeyAuth: []
+ - AdminJWTAuth: []
parameters:
- name: teamID
in: path
@@ -3896,53 +4073,6 @@ paths:
"500":
$ref: "#/components/responses/500"
- /access-tokens:
- post:
- summary: Create access token
- description: Create a new access token. Deprecated; use an API key (E2B_API_KEY) instead.
- deprecated: true
- tags: [access-tokens]
- security:
- - AuthProviderBearerAuth: []
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/NewAccessToken"
- responses:
- "201":
- description: Access token created successfully
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/CreatedAccessToken"
- "401":
- $ref: "#/components/responses/401"
- "410":
- $ref: "#/components/responses/410"
- "500":
- $ref: "#/components/responses/500"
-
- /access-tokens/{accessTokenID}:
- delete:
- summary: Delete access token
- description: Delete an access token
- tags: [access-tokens]
- security:
- - AuthProviderBearerAuth: []
- parameters:
- - $ref: "#/components/parameters/accessTokenID"
- responses:
- "204":
- description: Access token deleted successfully
- "401":
- $ref: "#/components/responses/401"
- "404":
- $ref: "#/components/responses/404"
- "500":
- $ref: "#/components/responses/500"
-
/api-keys:
get:
summary: List team API keys
@@ -3953,6 +4083,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
responses:
"200":
description: Successfully returned all team API keys
@@ -4001,6 +4133,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/apiKeyID"
requestBody:
@@ -4027,6 +4161,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/apiKeyID"
responses:
@@ -4050,6 +4186,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
responses:
"200":
description: Successfully listed all team volumes
@@ -4074,6 +4212,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -4105,6 +4245,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/volumeID"
responses:
@@ -4131,6 +4273,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/volumeID"
responses:
@@ -4154,6 +4298,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/paginationNextToken"
- $ref: "#/components/parameters/paginationLimit"
@@ -4198,6 +4344,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
requestBody:
required: true
content:
@@ -4241,6 +4389,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/secretID"
responses:
@@ -4279,6 +4429,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/secretID"
requestBody:
@@ -4323,6 +4475,8 @@ paths:
AuthProviderTeamAuth: []
- AdminApiKeyAuth: []
AdminTeamAuth: []
+ - AdminJWTAuth: []
+ AdminTeamAuth: []
parameters:
- $ref: "#/components/parameters/secretID"
responses:
@@ -4346,3 +4500,189 @@ paths:
$ref: "#/components/responses/502"
"504":
$ref: "#/components/responses/504"
+
+ /clusters/{clusterID}/rigs:
+ get:
+ summary: List rigs of a cluster
+ description: >
+ List the orchestrator node pools ("rigs") of a cluster with a snapshot
+ of their scaling groups. Forwarded to the cluster's edge service; a
+ cluster with no rig management configured returns an empty list, and
+ the local cluster answers 501.
+ tags: [admin]
+ security:
+ - AdminApiKeyAuth: []
+ - AdminJWTAuth: []
+ parameters:
+ - $ref: "#/components/parameters/clusterID"
+ responses:
+ "200":
+ description: Successfully returned the rigs of the cluster
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/Rig"
+ "401":
+ $ref: "#/components/responses/401"
+ "404":
+ $ref: "#/components/responses/404"
+ "500":
+ $ref: "#/components/responses/500"
+ "501":
+ $ref: "#/components/responses/501"
+
+ /clusters/{clusterID}/rigs/{rigID}/capacity:
+ put:
+ summary: Set the capacity of a rig
+ description: >
+ Set the desired instance count on the rig's scaling group. The value is
+ passed to the cloud provider unchanged; violations of the group's bounds
+ or conflicting concurrent operations surface as errors.
+ tags: [admin]
+ security:
+ - AdminApiKeyAuth: []
+ - AdminJWTAuth: []
+ parameters:
+ - $ref: "#/components/parameters/clusterID"
+ - $ref: "#/components/parameters/rigID"
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RigCapacityChange"
+ responses:
+ "202":
+ description: Capacity change accepted
+ "400":
+ $ref: "#/components/responses/400"
+ "401":
+ $ref: "#/components/responses/401"
+ "404":
+ $ref: "#/components/responses/404"
+ "409":
+ $ref: "#/components/responses/409"
+ "500":
+ $ref: "#/components/responses/500"
+ "501":
+ $ref: "#/components/responses/501"
+
+ /clusters/{clusterID}/rigs/instances/{instanceID}:
+ delete:
+ summary: Terminate an instance of a rig
+ description: >
+ Terminate an instance in whichever rig's scaling group it belongs to.
+ The caller chooses whether the rig shrinks or the instance is replaced.
+ tags: [admin]
+ security:
+ - AdminApiKeyAuth: []
+ - AdminJWTAuth: []
+ parameters:
+ - $ref: "#/components/parameters/clusterID"
+ - name: instanceID
+ in: path
+ required: true
+ schema:
+ type: string
+ description: Provider instance ID
+ - name: decrementDesired
+ in: query
+ required: true
+ schema:
+ type: boolean
+ description: >
+ When true, desired capacity is decremented (rig shrinks);
+ when false, the scaling group launches a replacement instance
+ responses:
+ "202":
+ description: Instance termination accepted
+ "400":
+ $ref: "#/components/responses/400"
+ "401":
+ $ref: "#/components/responses/401"
+ "404":
+ $ref: "#/components/responses/404"
+ "409":
+ $ref: "#/components/responses/409"
+ "500":
+ $ref: "#/components/responses/500"
+ "501":
+ $ref: "#/components/responses/501"
+
+ /clusters/{clusterID}/rigs/{rigID}/instances:
+ get:
+ summary: List the instances attached to a rig
+ description: >
+ List the instances attached to the rig's scaling group with their
+ creation time and transition state, sorted by instance ID.
+ tags: [admin]
+ security:
+ - AdminApiKeyAuth: []
+ - AdminJWTAuth: []
+ parameters:
+ - $ref: "#/components/parameters/clusterID"
+ - $ref: "#/components/parameters/rigID"
+ responses:
+ "200":
+ description: Successfully returned the instances of the rig
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/RigInstance"
+ "400":
+ $ref: "#/components/responses/400"
+ "401":
+ $ref: "#/components/responses/401"
+ "404":
+ $ref: "#/components/responses/404"
+ "500":
+ $ref: "#/components/responses/500"
+ "501":
+ $ref: "#/components/responses/501"
+
+ /clusters/{clusterID}/rigs/{rigID}/errors:
+ get:
+ summary: List recent scaling errors of a rig
+ description: >
+ List recent scaling errors on the rig's scaling group (e.g. failed
+ instance creations due to resource exhaustion), newest first.
+ tags: [admin]
+ security:
+ - AdminApiKeyAuth: []
+ - AdminJWTAuth: []
+ parameters:
+ - $ref: "#/components/parameters/clusterID"
+ - $ref: "#/components/parameters/rigID"
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ format: int32
+ minimum: 1
+ maximum: 50
+ default: 20
+ description: Maximum number of errors to return
+ responses:
+ "200":
+ description: Successfully returned the scaling errors of the rig
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/RigError"
+ "400":
+ $ref: "#/components/responses/400"
+ "401":
+ $ref: "#/components/responses/401"
+ "404":
+ $ref: "#/components/responses/404"
+ "500":
+ $ref: "#/components/responses/500"
+ "501":
+ $ref: "#/components/responses/501"