Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: crud for sandbox environment (#900)

Sujai Kumar Gupta1bf436e6b44a
diff --git a/.changeset/sandbox-environment-agent-ref.md b/.changeset/sandbox-environment-agent-ref.md
new file mode 100644
index 000000000..9139d8db0
--- /dev/null
+++ b/.changeset/sandbox-environment-agent-ref.md
@@ -0,0 +1,7 @@
+---
+'@truefoundry/trueforge': patch
+'@truefoundry/trueforge-core': patch
+'@truefoundry/trueforge-assistant-ui-runtime': patch
+---
+
+Add sandbox-environment CRUD (tables, PUT upsert, subject ownership, soft-delete). Versions land as `pending` for a future controller. AgentSpec `config.sandbox.environment_name` names a caller-owned env; name `default` is reserved; delete returns 409 while agents reference it. Turn create clones the env snapshot (when built) and applies resources, env vars, and networking.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 7048c2d18..9f0c1d3e0 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -1324,6 +1324,10 @@
"properties": {},
"type": "object"
},
+ "DeleteSandboxEnvironmentResponse": {
+ "properties": {},
+ "type": "object"
+ },
"DeleteScheduleResponse": {
"properties": {},
"type": "object"
@@ -1607,6 +1611,17 @@
],
"type": "object"
},
+ "GetSandboxEnvironmentResponse": {
+ "properties": {
+ "data": {
+ "$ref": "#/components/schemas/SandboxEnvironment"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"GetSandboxProviderCatalogResponse": {
"properties": {
"data": {
@@ -2426,6 +2441,24 @@
],
"type": "object"
},
+ "ListSandboxEnvironmentsResponse": {
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SandboxEnvironment"
+ },
+ "type": "array"
+ },
+ "pagination": {
+ "$ref": "#/components/schemas/TokenPagination"
+ }
+ },
+ "required": [
+ "data",
+ "pagination"
+ ],
+ "type": "object"
+ },
"ListScheduleRunsResponse": {
"properties": {
"data": {
@@ -3778,6 +3811,11 @@
"description": "Give the agent a sandbox. Required for skills and Code Mode.",
"type": "boolean"
},
+ "environment_name": {
+ "description": "Name of a configured sandbox environment to use. Must exist when set.",
+ "minLength": 1,
+ "type": "string"
+ },
"file_downloads": {
"default": true,
"description": "Allow downloading agent-produced files via the turn download endpoint. Default: true.",
@@ -3827,6 +3865,216 @@
],
"type": "object"
},
+ "SandboxEnvironment": {
+ "additionalProperties": false,
+ "properties": {
+ "created_at": {
+ "description": "ISO-8601 create time.",
+ "format": "date-time",
+ "type": "string"
+ },
+ "created_by_subject": {
+ "$ref": "#/components/schemas/CreatedBySubject"
+ },
+ "description": {
+ "description": "Human-readable description; empty when unset.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Immutable server-generated environment identifier.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "lifecycle_stage": {
+ "$ref": "#/components/schemas/SandboxEnvironmentLifecycleStage"
+ },
+ "manifest": {
+ "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "status": {
+ "$ref": "#/components/schemas/SandboxEnvironmentVersionStatus"
+ },
+ "status_reason": {
+ "description": "Failure detail when status is failed; null otherwise.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "ISO-8601 last update time.",
+ "format": "date-time",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "description",
+ "lifecycle_stage",
+ "status",
+ "status_reason",
+ "manifest",
+ "created_by_subject",
+ "created_at",
+ "updated_at"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentImage": {
+ "additionalProperties": false,
+ "properties": {
+ "build_script": {
+ "description": "Shell script used to build the snapshot.",
+ "example": "set -ex\npip install httpx\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "description": "Build a snapshot from a script.",
+ "enum": [
+ "build"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentLifecycleStage": {
+ "description": "Soft-delete lifecycle stage.",
+ "enum": [
+ "active",
+ "deleted"
+ ],
+ "type": "string"
+ },
+ "SandboxEnvironmentManifest": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Optional human-readable description.",
+ "maxLength": 1024,
+ "type": "string"
+ },
+ "environment_variables": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "image": {
+ "$ref": "#/components/schemas/SandboxEnvironmentImage"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "networking": {
+ "$ref": "#/components/schemas/SandboxEnvironmentNetworking"
+ },
+ "resources": {
+ "$ref": "#/components/schemas/SandboxEnvironmentResources"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentNetworking": {
+ "additionalProperties": false,
+ "properties": {
+ "domain_allow_list": {
+ "description": "Comma-separated allowed domains.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "network_block_all": {
+ "description": "Block all outbound network access. When true, domain_allow_list and secrets are not used.",
+ "type": "boolean"
+ },
+ "secrets": {
+ "description": "Network-scoped secrets.",
+ "items": {
+ "$ref": "#/components/schemas/SandboxEnvironmentSecret"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "SandboxEnvironmentResources": {
+ "additionalProperties": false,
+ "default": {
+ "cpu": 1,
+ "disk": 3,
+ "memory": 1
+ },
+ "properties": {
+ "cpu": {
+ "default": 1,
+ "description": "CPU allocation in cores.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "disk": {
+ "default": 3,
+ "description": "Disk allocation in GiB.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "memory": {
+ "default": 1,
+ "description": "Memory allocation in GiB.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "SandboxEnvironmentSecret": {
+ "additionalProperties": false,
+ "properties": {
+ "env": {
+ "description": "Environment variable name injected into the sandbox.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "hosts": {
+ "description": "Hosts this secret may be sent to.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "value": {
+ "description": "Secret value; GET responses use a redacted stand-in.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "env",
+ "value",
+ "hosts"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentVersionStatus": {
+ "description": "Readiness of the environment.",
+ "enum": [
+ "pending",
+ "active",
+ "failed"
+ ],
+ "type": "string"
+ },
"SandboxProviderManifest": {
"additionalProperties": false,
"properties": {
@@ -5801,6 +6049,18 @@
],
"type": "object"
},
+ "UpdateSandboxEnvironmentRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ }
+ },
+ "required": [
+ "manifest"
+ ],
+ "type": "object"
+ },
"UpdateSandboxProviderRequest": {
"additionalProperties": false,
"properties": {
@@ -8015,6 +8275,288 @@
"x-fern-sdk-method-name": "list"
}
},
+ "/api/v1/sandbox-environments": {
+ "get": {
+ "description": "List sandbox environments created by the authenticated subject, newest first.",
+ "parameters": [
+ {
+ "description": "Page size. Defaults to 25",
+ "in": "query",
+ "name": "limit",
+ "required": false,
+ "schema": {
+ "default": 25,
+ "description": "Page size. Defaults to 25",
+ "maximum": 25,
+ "minimum": 1,
+ "type": "integer"
+ }
+ },
+ {
+ "description": "Opaque token from a previous response `next_page_token`.",
+ "in": "query",
+ "name": "page_token",
+ "required": false,
+ "schema": {
+ "description": "Opaque token from a previous response `next_page_token`.",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListSandboxEnvironmentsResponse"
+ }
+ }
+ },
+ "description": "Paginated sandbox environments."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid query parameters or page token."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ }
+ },
+ "summary": "List sandbox environments",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-pagination": {
+ "cursor": "$request.page_token",
+ "next_cursor": "$response.pagination.next_page_token",
+ "results": "$response.data"
+ },
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "list"
+ },
+ "put": {
+ "description": "Create or replace by `manifest.name`. Requires a Daytona sandbox provider.",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateSandboxEnvironmentRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "The saved sandbox environment."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid request body, or missing secret value."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "409": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Name conflict or concurrent update."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "No Daytona sandbox provider configured."
+ }
+ },
+ "summary": "Create or update a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "create_or_update"
+ }
+ },
+ "/api/v1/sandbox-environments/{name}": {
+ "delete": {
+ "description": "Delete by name. Fails if any agent still references the environment.",
+ "parameters": [
+ {
+ "description": "Sandbox environment name.",
+ "in": "path",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ {
+ "description": "Sandbox environment name."
+ }
+ ]
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeleteSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment deleted."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment not found."
+ },
+ "409": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Environment is referenced by one or more agents."
+ }
+ },
+ "summary": "Delete a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "delete"
+ },
+ "get": {
+ "description": "Get a sandbox environment by name for the authenticated subject.",
+ "parameters": [
+ {
+ "description": "Sandbox environment name.",
+ "in": "path",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ {
+ "description": "Sandbox environment name."
+ }
+ ]
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "The sandbox environment."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment not found."
+ }
+ },
+ "summary": "Get a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "get"
+ }
+ },
"/api/v1/schedules": {
"get": {
"description": "List schedules for the tenant, newest first.",
diff --git a/docs/openapi.json b/docs/openapi.json
index 7048c2d18..9f0c1d3e0 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -1324,6 +1324,10 @@
"properties": {},
"type": "object"
},
+ "DeleteSandboxEnvironmentResponse": {
+ "properties": {},
+ "type": "object"
+ },
"DeleteScheduleResponse": {
"properties": {},
"type": "object"
@@ -1607,6 +1611,17 @@
],
"type": "object"
},
+ "GetSandboxEnvironmentResponse": {
+ "properties": {
+ "data": {
+ "$ref": "#/components/schemas/SandboxEnvironment"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"GetSandboxProviderCatalogResponse": {
"properties": {
"data": {
@@ -2426,6 +2441,24 @@
],
"type": "object"
},
+ "ListSandboxEnvironmentsResponse": {
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SandboxEnvironment"
+ },
+ "type": "array"
+ },
+ "pagination": {
+ "$ref": "#/components/schemas/TokenPagination"
+ }
+ },
+ "required": [
+ "data",
+ "pagination"
+ ],
+ "type": "object"
+ },
"ListScheduleRunsResponse": {
"properties": {
"data": {
@@ -3778,6 +3811,11 @@
"description": "Give the agent a sandbox. Required for skills and Code Mode.",
"type": "boolean"
},
+ "environment_name": {
+ "description": "Name of a configured sandbox environment to use. Must exist when set.",
+ "minLength": 1,
+ "type": "string"
+ },
"file_downloads": {
"default": true,
"description": "Allow downloading agent-produced files via the turn download endpoint. Default: true.",
@@ -3827,6 +3865,216 @@
],
"type": "object"
},
+ "SandboxEnvironment": {
+ "additionalProperties": false,
+ "properties": {
+ "created_at": {
+ "description": "ISO-8601 create time.",
+ "format": "date-time",
+ "type": "string"
+ },
+ "created_by_subject": {
+ "$ref": "#/components/schemas/CreatedBySubject"
+ },
+ "description": {
+ "description": "Human-readable description; empty when unset.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Immutable server-generated environment identifier.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "lifecycle_stage": {
+ "$ref": "#/components/schemas/SandboxEnvironmentLifecycleStage"
+ },
+ "manifest": {
+ "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "status": {
+ "$ref": "#/components/schemas/SandboxEnvironmentVersionStatus"
+ },
+ "status_reason": {
+ "description": "Failure detail when status is failed; null otherwise.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "ISO-8601 last update time.",
+ "format": "date-time",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "description",
+ "lifecycle_stage",
+ "status",
+ "status_reason",
+ "manifest",
+ "created_by_subject",
+ "created_at",
+ "updated_at"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentImage": {
+ "additionalProperties": false,
+ "properties": {
+ "build_script": {
+ "description": "Shell script used to build the snapshot.",
+ "example": "set -ex\npip install httpx\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "description": "Build a snapshot from a script.",
+ "enum": [
+ "build"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentLifecycleStage": {
+ "description": "Soft-delete lifecycle stage.",
+ "enum": [
+ "active",
+ "deleted"
+ ],
+ "type": "string"
+ },
+ "SandboxEnvironmentManifest": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Optional human-readable description.",
+ "maxLength": 1024,
+ "type": "string"
+ },
+ "environment_variables": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "image": {
+ "$ref": "#/components/schemas/SandboxEnvironmentImage"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "networking": {
+ "$ref": "#/components/schemas/SandboxEnvironmentNetworking"
+ },
+ "resources": {
+ "$ref": "#/components/schemas/SandboxEnvironmentResources"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentNetworking": {
+ "additionalProperties": false,
+ "properties": {
+ "domain_allow_list": {
+ "description": "Comma-separated allowed domains.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "network_block_all": {
+ "description": "Block all outbound network access. When true, domain_allow_list and secrets are not used.",
+ "type": "boolean"
+ },
+ "secrets": {
+ "description": "Network-scoped secrets.",
+ "items": {
+ "$ref": "#/components/schemas/SandboxEnvironmentSecret"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "SandboxEnvironmentResources": {
+ "additionalProperties": false,
+ "default": {
+ "cpu": 1,
+ "disk": 3,
+ "memory": 1
+ },
+ "properties": {
+ "cpu": {
+ "default": 1,
+ "description": "CPU allocation in cores.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "disk": {
+ "default": 3,
+ "description": "Disk allocation in GiB.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "memory": {
+ "default": 1,
+ "description": "Memory allocation in GiB.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "SandboxEnvironmentSecret": {
+ "additionalProperties": false,
+ "properties": {
+ "env": {
+ "description": "Environment variable name injected into the sandbox.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "hosts": {
+ "description": "Hosts this secret may be sent to.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "value": {
+ "description": "Secret value; GET responses use a redacted stand-in.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "env",
+ "value",
+ "hosts"
+ ],
+ "type": "object"
+ },
+ "SandboxEnvironmentVersionStatus": {
+ "description": "Readiness of the environment.",
+ "enum": [
+ "pending",
+ "active",
+ "failed"
+ ],
+ "type": "string"
+ },
"SandboxProviderManifest": {
"additionalProperties": false,
"properties": {
@@ -5801,6 +6049,18 @@
],
"type": "object"
},
+ "UpdateSandboxEnvironmentRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ }
+ },
+ "required": [
+ "manifest"
+ ],
+ "type": "object"
+ },
"UpdateSandboxProviderRequest": {
"additionalProperties": false,
"properties": {
@@ -8015,6 +8275,288 @@
"x-fern-sdk-method-name": "list"
}
},
+ "/api/v1/sandbox-environments": {
+ "get": {
+ "description": "List sandbox environments created by the authenticated subject, newest first.",
+ "parameters": [
+ {
+ "description": "Page size. Defaults to 25",
+ "in": "query",
+ "name": "limit",
+ "required": false,
+ "schema": {
+ "default": 25,
+ "description": "Page size. Defaults to 25",
+ "maximum": 25,
+ "minimum": 1,
+ "type": "integer"
+ }
+ },
+ {
+ "description": "Opaque token from a previous response `next_page_token`.",
+ "in": "query",
+ "name": "page_token",
+ "required": false,
+ "schema": {
+ "description": "Opaque token from a previous response `next_page_token`.",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListSandboxEnvironmentsResponse"
+ }
+ }
+ },
+ "description": "Paginated sandbox environments."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid query parameters or page token."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ }
+ },
+ "summary": "List sandbox environments",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-pagination": {
+ "cursor": "$request.page_token",
+ "next_cursor": "$response.pagination.next_page_token",
+ "results": "$response.data"
+ },
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "list"
+ },
+ "put": {
+ "description": "Create or replace by `manifest.name`. Requires a Daytona sandbox provider.",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateSandboxEnvironmentRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "The saved sandbox environment."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid request body, or missing secret value."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "409": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Name conflict or concurrent update."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "No Daytona sandbox provider configured."
+ }
+ },
+ "summary": "Create or update a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "create_or_update"
+ }
+ },
+ "/api/v1/sandbox-environments/{name}": {
+ "delete": {
+ "description": "Delete by name. Fails if any agent still references the environment.",
+ "parameters": [
+ {
+ "description": "Sandbox environment name.",
+ "in": "path",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ {
+ "description": "Sandbox environment name."
+ }
+ ]
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeleteSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment deleted."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment not found."
+ },
+ "409": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Environment is referenced by one or more agents."
+ }
+ },
+ "summary": "Delete a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "delete"
+ },
+ "get": {
+ "description": "Get a sandbox environment by name for the authenticated subject.",
+ "parameters": [
+ {
+ "description": "Sandbox environment name.",
+ "in": "path",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ {
+ "description": "Sandbox environment name."
+ }
+ ]
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSandboxEnvironmentResponse"
+ }
+ }
+ },
+ "description": "The sandbox environment."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unauthenticated."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Sandbox environment not found."
+ }
+ },
+ "summary": "Get a sandbox environment",
+ "tags": [
+ "Sandboxes"
+ ],
+ "x-fern-sdk-group-name": [
+ "sandboxEnvironments"
+ ],
+ "x-fern-sdk-method-name": "get"
+ }
+ },
"/api/v1/schedules": {
"get": {
"description": "List schedules for the tenant, newest first.",
diff --git a/packages/assistant-ui-runtime/src/server/types.ts b/packages/assistant-ui-runtime/src/server/types.ts
index cb22a511e..8777565be 100644
--- a/packages/assistant-ui-runtime/src/server/types.ts
+++ b/packages/assistant-ui-runtime/src/server/types.ts
@@ -123,6 +123,8 @@ export interface AgentCapabilityConfig {
export interface AgentSandboxConfig extends AgentCapabilityConfig {
fileDownloads?: boolean;
+ /** Name of a configured sandbox environment. */
+ environment_name?: string;
}
export interface AgentInputTokensCompactionTrigger {
diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
index 8aaa3c5d0..a17f2cd17 100644
--- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
@@ -166,6 +166,11 @@ const SandboxConfigSchema = z
.boolean()
.default(true)
.describe('Allow downloading agent-produced files via the turn download endpoint. Default: true.'),
+ environment_name: z
+ .string()
+ .min(1)
+ .optional()
+ .describe('Name of a configured sandbox environment to use. Must exist when set.'),
})
.openapi('SandboxConfig');
diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts
index 3ac1e3947..f8076ae54 100644
--- a/packages/trueforge-core/src/core/index.ts
+++ b/packages/trueforge-core/src/core/index.ts
@@ -166,7 +166,7 @@ export type { CodeModeClientInstall, CodeModeTransport } from './sandbox/codeMod
export { CodeModeErrorSourceSchema, CodeModeReplySchema, CodeModeRequestSchema } from './sandbox/codeMode/types';
export type { CodeModeErrorSource, CodeModeReply, CodeModeRequest } from './sandbox/codeMode/types';
export { DaytonaSandboxProvider } from './sandbox/provider/DaytonaProvider';
-export type { DaytonaSandboxProviderOptions } from './sandbox/provider/DaytonaProvider';
+export type { DaytonaSandboxProviderOptions, SandboxEnvironment } from './sandbox/provider/DaytonaProvider';
export { absolutizeRelativeExecEnv } from './sandbox/provider/execEnv';
export { ensureExecSuccess, shellEscape } from './sandbox/provider/Provider';
export type {
diff --git a/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts b/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
index 2332325c6..638cbeeb1 100644
--- a/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
+++ b/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
@@ -1,4 +1,4 @@
-import type { Sandbox, Snapshot } from '@daytona/sdk';
+import type { CreateSandboxFromSnapshotParams, Sandbox, Snapshot } from '@daytona/sdk';
import { Daytona, DaytonaError } from '@daytona/sdk';
import { context } from '@opentelemetry/api';
import { suppressTracing } from '@opentelemetry/core';
@@ -70,6 +70,39 @@ function httpUrlToWsUrl(url: string): string {
return parsed.toString();
}
+/**
+ * Daytona-only environment (subset of the host sandbox-environment manifest).
+ * Fresh create applies env vars + networking only; other fields are accepted unused for now.
+ * Daytona networking modes are mutually exclusive (`network_block_all` vs `domain_allow_list`).
+ */
+export interface SandboxEnvironment {
+ image?:
+ | {
+ type: 'build';
+ build_script?: string | undefined;
+ }
+ | undefined;
+ resources: {
+ cpu: number;
+ memory: number;
+ disk: number;
+ };
+ environment_variables?: Record<string, string> | undefined;
+ networking?:
+ | {
+ network_block_all?: boolean | undefined;
+ domain_allow_list?: string | undefined;
+ secrets?:
+ | {
+ env: string;
+ value: string;
+ hosts: string[];
+ }[]
+ | undefined;
+ }
+ | undefined;
+}
+
export interface DaytonaSandboxProviderOptions {
/** Caller-owned Daytona SDK client (credentials / lifetime). */
client: Daytona;
@@ -98,6 +131,8 @@ export interface DaytonaSandboxProviderOptions {
natsBridgePort?: number;
/** Defaults to 1 hour (same as the gateway's max agent execution time). */
previewUrlExpirySeconds?: number;
+ /** Optional sandbox environment; applied only on fresh create (not restore). */
+ environment?: SandboxEnvironment;
logger: Logger;
}
@@ -117,6 +152,7 @@ export class DaytonaSandboxProvider implements SandboxProvider {
private readonly previewUrlExpirySeconds: number;
private readonly apiKey: string;
private readonly apiUrl: string;
+ private readonly environment: DaytonaSandboxProviderOptions['environment'];
private readonly logger: Logger;
private readonly daytona: Daytona;
private static readonly cachedSandboxes = new Map<string, { sandbox: Sandbox; defaultTimeoutMs: number }>();
@@ -137,6 +173,7 @@ export class DaytonaSandboxProvider implements SandboxProvider {
this.fileMaxBytesForDownload = options.fileMaxBytesForDownload;
this.natsBridgePort = options.natsBridgePort ?? DEFAULT_SANDBOX_NATS_WS_PORT;
this.previewUrlExpirySeconds = options.previewUrlExpirySeconds ?? DEFAULT_PREVIEW_URL_EXPIRY_SECONDS;
+ this.environment = options.environment;
this.logger = options.logger.child({ module: 'DaytonaProvider' });
}
@@ -151,19 +188,28 @@ export class DaytonaSandboxProvider implements SandboxProvider {
const sandbox = sandboxId
? await this.restoreExistingSandbox(sandboxId)
- : await this.daytona.create({
- name: `${this.tenantName}.${randomUUID()}`,
- snapshot: this.buildRef,
- autoStopInterval: this.autoStopIntervalInMinutes,
- autoArchiveInterval: this.autoArchiveIntervalInMinutes,
- autoDeleteInterval: this.autoDeleteIntervalInMinutes,
- });
+ : await this.daytona.create(this.buildCreateParams());
const entry = { sandbox, defaultTimeoutMs: this.timeoutMs };
DaytonaSandboxProvider.cachedSandboxes.set(sandbox.name, entry);
return entry;
}
+ private buildCreateParams(): CreateSandboxFromSnapshotParams {
+ const environment = this.environment;
+ const networking = environment?.networking;
+ return {
+ name: `${this.tenantName}.${randomUUID()}`,
+ snapshot: this.buildRef,
+ autoStopInterval: this.autoStopIntervalInMinutes,
+ autoArchiveInterval: this.autoArchiveIntervalInMinutes,
+ autoDeleteInterval: this.autoDeleteIntervalInMinutes,
+ ...(environment?.environment_variables ? { envVars: environment.environment_variables } : {}),
+ ...(networking?.network_block_all ? { networkBlockAll: networking.network_block_all } : {}),
+ ...(networking?.domain_allow_list ? { domainAllowList: networking.domain_allow_list } : {}),
+ };
+ }
+
// Returns true iff the caller should retry: either we restarted a stopped sandbox, or the cache entry is missing and the retry will rebuild it via the cold path.
private static recoverSandboxIfStopped(sandboxId: string): Promise<boolean> {
const existing = DaytonaSandboxProvider.inFlightRecoveries.get(sandboxId);
diff --git a/packages/trueforge-core/tests/agent-session/testHelpers.ts b/packages/trueforge-core/tests/agent-session/testHelpers.ts
index fd1ddc88a..e69a3f52e 100644
--- a/packages/trueforge-core/tests/agent-session/testHelpers.ts
+++ b/packages/trueforge-core/tests/agent-session/testHelpers.ts
@@ -34,7 +34,7 @@ export function makeAgentSpec(
model?: { name: string };
config?: {
iteration_limit?: number;
- sandbox?: { enabled: boolean; file_downloads?: boolean };
+ sandbox?: { enabled: boolean; file_downloads?: boolean; environment_name?: string };
ask_user_questions?: { enabled?: boolean };
dynamic_sub_agents?: { enabled?: boolean };
generative_ui?: { enabled?: boolean };
diff --git a/packages/trueforge-sdk/package.json b/packages/trueforge-sdk/package.json
index eec4a5914..21cc2d885 100644
--- a/packages/trueforge-sdk/package.json
+++ b/packages/trueforge-sdk/package.json
@@ -99,6 +99,17 @@
},
"default": "./dist/cjs/api/resources/models/exports.js"
},
+ "./sandboxEnvironments": {
+ "import": {
+ "types": "./dist/esm/api/resources/sandboxEnvironments/exports.d.mts",
+ "default": "./dist/esm/api/resources/sandboxEnvironments/exports.mjs"
+ },
+ "require": {
+ "types": "./dist/cjs/api/resources/sandboxEnvironments/exports.d.ts",
+ "default": "./dist/cjs/api/resources/sandboxEnvironments/exports.js"
+ },
+ "default": "./dist/cjs/api/resources/sandboxEnvironments/exports.js"
+ },
"./schedules": {
"import": {
"types": "./dist/esm/api/resources/schedules/exports.d.mts",
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index cbb977225..2c4cad6ed 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -896,6 +896,275 @@ await client.models.list();
</dl>
+</dd>
+</dl>
+</details>
+
+## SandboxEnvironments
+<details><summary><code>client.sandboxEnvironments.<a href="/src/api/resources/sandboxEnvironments/client/Client.ts">list</a>({ ...params }) -> core.Page&lt;TrueForge.SandboxEnvironment, TrueForge.ListSandboxEnvironmentsResponse&gt;</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+List sandbox environments created by the authenticated subject, newest first.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+const pageableResponse = await client.sandboxEnvironments.list();
+for await (const item of pageableResponse) {
+ console.log(item);
+}
+
+// Or you can manually iterate page-by-page
+let page = await client.sandboxEnvironments.list();
+while (page.hasNextPage()) {
+ page = page.getNextPage();
+}
+
+// You can also access the underlying response
+const response = page.response;
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.ListSandboxEnvironmentsRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandboxEnvironments.<a href="/src/api/resources/sandboxEnvironments/client/Client.ts">createOrUpdate</a>({ ...params }) -> TrueForge.GetSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "name"
+ }
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.UpdateSandboxEnvironmentRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandboxEnvironments.<a href="/src/api/resources/sandboxEnvironments/client/Client.ts">get</a>(name) -> TrueForge.GetSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Get a sandbox environment by name for the authenticated subject.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.sandboxEnvironments.get("name");
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**name:** `string` — Sandbox environment name.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandboxEnvironments.<a href="/src/api/resources/sandboxEnvironments/client/Client.ts">delete</a>(name) -> TrueForge.DeleteSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Delete by name. Fails if any agent still references the environment.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.sandboxEnvironments.delete("name");
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**name:** `string` — Sandbox environment name.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/packages/trueforge-sdk/src/Client.ts b/packages/trueforge-sdk/src/Client.ts
index d8dab2878..757773d88 100644
--- a/packages/trueforge-sdk/src/Client.ts
+++ b/packages/trueforge-sdk/src/Client.ts
@@ -6,6 +6,7 @@ import { CatalogsClient } from "./api/resources/catalogs/client/Client.js";
import { InternalClient } from "./api/resources/internal/client/Client.js";
import { McpServersClient } from "./api/resources/mcpServers/client/Client.js";
import { ModelsClient } from "./api/resources/models/client/Client.js";
+import { SandboxEnvironmentsClient } from "./api/resources/sandboxEnvironments/client/Client.js";
import { SchedulesClient } from "./api/resources/schedules/client/Client.js";
import { ServerClient } from "./api/resources/server/client/Client.js";
import { SessionsClient } from "./api/resources/sessions/client/Client.js";
@@ -29,6 +30,7 @@ export class TrueForge {
protected _server: ServerClient | undefined;
protected _mcpServers: McpServersClient | undefined;
protected _models: ModelsClient | undefined;
+ protected _sandboxEnvironments: SandboxEnvironmentsClient | undefined;
protected _schedules: SchedulesClient | undefined;
protected _sessions: SessionsClient | undefined;
protected _skills: SkillsClient | undefined;
@@ -63,6 +65,10 @@ export class TrueForge {
return (this._models ??= new ModelsClient(this._options));
}
+ public get sandboxEnvironments(): SandboxEnvironmentsClient {
+ return (this._sandboxEnvironments ??= new SandboxEnvironmentsClient(this._options));
+ }
+
public get schedules(): SchedulesClient {
return (this._schedules ??= new SchedulesClient(this._options));
}
diff --git a/packages/trueforge-sdk/src/api/resources/index.ts b/packages/trueforge-sdk/src/api/resources/index.ts
index 000fb4979..bef7cbe19 100644
--- a/packages/trueforge-sdk/src/api/resources/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/index.ts
@@ -7,6 +7,8 @@ export * as internal from "./internal/index.js";
export * from "./mcpServers/client/requests/index.js";
export * as mcpServers from "./mcpServers/index.js";
export * as models from "./models/index.js";
+export * from "./sandboxEnvironments/client/requests/index.js";
+export * as sandboxEnvironments from "./sandboxEnvironments/index.js";
export * from "./schedules/client/requests/index.js";
export * as schedules from "./schedules/index.js";
export * as server from "./server/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts
new file mode 100644
index 000000000..d94dd9b52
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts
@@ -0,0 +1,489 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../BaseClient.js";
+import { mergeHeaders } from "../../../../core/headers.js";
+import * as core from "../../../../core/index.js";
+import { mergeAdditionalBodyParameters } from "../../../../core/requestBody.js";
+import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
+import * as errors from "../../../../errors/index.js";
+import * as serializers from "../../../../serialization/index.js";
+import * as TrueForge from "../../../index.js";
+
+export declare namespace SandboxEnvironmentsClient {
+ export type Options = BaseClientOptions;
+
+ export interface RequestOptions extends BaseRequestOptions {}
+}
+
+export class SandboxEnvironmentsClient {
+ protected readonly _options: NormalizedClientOptionsWithAuth<SandboxEnvironmentsClient.Options>;
+
+ constructor(options: SandboxEnvironmentsClient.Options) {
+ this._options = normalizeClientOptionsWithAuth(options);
+ }
+
+ /**
+ * List sandbox environments created by the authenticated subject, newest first.
+ *
+ * @param {TrueForge.ListSandboxEnvironmentsRequest} request
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.BadRequestError}
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.sandboxEnvironments.list()
+ */
+ public async list(
+ request: TrueForge.ListSandboxEnvironmentsRequest = {},
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.Page<TrueForge.SandboxEnvironment, TrueForge.ListSandboxEnvironmentsResponse>> {
+ const list = core.HttpResponsePromise.interceptFunction(
+ async (
+ request: TrueForge.ListSandboxEnvironmentsRequest,
+ ): Promise<core.WithRawResponse<TrueForge.ListSandboxEnvironmentsResponse>> => {
+ const { limit = 25, pageToken } = request;
+ const _queryParams: Record<string, unknown> = {
+ limit,
+ page_token: pageToken,
+ };
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "api/v1/sandbox-environments",
+ ),
+ method: "GET",
+ headers: _headers,
+ queryString: core.url
+ .queryBuilder()
+ .addMany(_queryParams)
+ .mergeAdditional(requestOptions?.queryParams)
+ .build(),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.ListSandboxEnvironmentsResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 400:
+ throw new TrueForge.BadRequestError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "GET",
+ "/api/v1/sandbox-environments",
+ );
+ },
+ );
+ const dataWithRawResponse = await list(request).withRawResponse();
+ return new core.Page<TrueForge.SandboxEnvironment, TrueForge.ListSandboxEnvironmentsResponse>({
+ response: dataWithRawResponse.data,
+ rawResponse: dataWithRawResponse.rawResponse,
+ hasNextPage: (response) =>
+ response?.pagination.nextPageToken != null &&
+ !(typeof response?.pagination.nextPageToken === "string" && response?.pagination.nextPageToken === ""),
+ getItems: (response) => response?.data ?? [],
+ loadPage: (response) => {
+ return list(core.setObjectProperty(request, "pageToken", response?.pagination.nextPageToken));
+ },
+ });
+ }
+
+ /**
+ * Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ *
+ * @param {TrueForge.UpdateSandboxEnvironmentRequest} request
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.BadRequestError}
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ConflictError}
+ * @throws {@link TrueForge.UnprocessableEntityError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.sandboxEnvironments.createOrUpdate({
+ * manifest: {
+ * name: "name"
+ * }
+ * })
+ */
+ public createOrUpdate(
+ request: TrueForge.UpdateSandboxEnvironmentRequest,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.GetSandboxEnvironmentResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__createOrUpdate(request, requestOptions));
+ }
+
+ private async __createOrUpdate(
+ request: TrueForge.UpdateSandboxEnvironmentRequest,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.GetSandboxEnvironmentResponse>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "api/v1/sandbox-environments",
+ ),
+ method: "PUT",
+ headers: _headers,
+ contentType: "application/json",
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ requestType: "json",
+ body: mergeAdditionalBodyParameters(
+ serializers.UpdateSandboxEnvironmentRequest.jsonOrThrow(request, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ omitUndefined: true,
+ }),
+ requestOptions?.additionalBodyParameters,
+ ),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.GetSandboxEnvironmentResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 400:
+ throw new TrueForge.BadRequestError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 409:
+ throw new TrueForge.ConflictError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 422:
+ throw new TrueForge.UnprocessableEntityError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/api/v1/sandbox-environments");
+ }
+
+ /**
+ * Get a sandbox environment by name for the authenticated subject.
+ *
+ * @param {string} name - Sandbox environment name.
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.NotFoundError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.sandboxEnvironments.get("name")
+ */
+ public get(
+ name: string,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.GetSandboxEnvironmentResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__get(name, requestOptions));
+ }
+
+ private async __get(
+ name: string,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.GetSandboxEnvironmentResponse>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ `api/v1/sandbox-environments/${core.url.encodePathParam(name)}`,
+ ),
+ method: "GET",
+ headers: _headers,
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.GetSandboxEnvironmentResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 404:
+ throw new TrueForge.NotFoundError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "GET",
+ "/api/v1/sandbox-environments/{name}",
+ );
+ }
+
+ /**
+ * Delete by name. Fails if any agent still references the environment.
+ *
+ * @param {string} name - Sandbox environment name.
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.NotFoundError}
+ * @throws {@link TrueForge.ConflictError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.sandboxEnvironments.delete("name")
+ */
+ public delete(
+ name: string,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.DeleteSandboxEnvironmentResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__delete(name, requestOptions));
+ }
+
+ private async __delete(
+ name: string,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.DeleteSandboxEnvironmentResponse>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ `api/v1/sandbox-environments/${core.url.encodePathParam(name)}`,
+ ),
+ method: "DELETE",
+ headers: _headers,
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.DeleteSandboxEnvironmentResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 404:
+ throw new TrueForge.NotFoundError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 409:
+ throw new TrueForge.ConflictError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "DELETE",
+ "/api/v1/sandbox-environments/{name}",
+ );
+ }
+}
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/index.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts
new file mode 100644
index 000000000..2efd1793b
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ * {}
+ */
+export interface ListSandboxEnvironmentsRequest {
+ /** Page size. Defaults to 25 */
+ limit?: number;
+ /** Opaque token from a previous response `next_page_token`. */
+ pageToken?: string;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
new file mode 100644
index 000000000..f24eb88bd
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
@@ -0,0 +1,15 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../index.js";
+
+/**
+ * @example
+ * {
+ * manifest: {
+ * name: "name"
+ * }
+ * }
+ */
+export interface UpdateSandboxEnvironmentRequest {
+ manifest: TrueForge.SandboxEnvironmentManifest;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/index.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/index.ts
new file mode 100644
index 000000000..bf9f82c2a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/index.ts
@@ -0,0 +1,2 @@
+export type { ListSandboxEnvironmentsRequest } from "./ListSandboxEnvironmentsRequest.js";
+export type { UpdateSandboxEnvironmentRequest } from "./UpdateSandboxEnvironmentRequest.js";
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/exports.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/exports.ts
new file mode 100644
index 000000000..fc58f1b3e
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/exports.ts
@@ -0,0 +1,4 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export { SandboxEnvironmentsClient } from "./client/Client.js";
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/index.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/api/types/DeleteSandboxEnvironmentResponse.ts b/packages/trueforge-sdk/src/api/types/DeleteSandboxEnvironmentResponse.ts
new file mode 100644
index 000000000..f9bb1fc09
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/DeleteSandboxEnvironmentResponse.ts
@@ -0,0 +1,3 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export type DeleteSandboxEnvironmentResponse = {};
diff --git a/packages/trueforge-sdk/src/api/types/GetSandboxEnvironmentResponse.ts b/packages/trueforge-sdk/src/api/types/GetSandboxEnvironmentResponse.ts
new file mode 100644
index 000000000..eaaa4d921
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/GetSandboxEnvironmentResponse.ts
@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface GetSandboxEnvironmentResponse {
+ data: TrueForge.SandboxEnvironment;
+}
diff --git a/packages/trueforge-sdk/src/api/types/ListSandboxEnvironmentsResponse.ts b/packages/trueforge-sdk/src/api/types/ListSandboxEnvironmentsResponse.ts
new file mode 100644
index 000000000..93b9b399e
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/ListSandboxEnvironmentsResponse.ts
@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface ListSandboxEnvironmentsResponse {
+ data: TrueForge.SandboxEnvironment[];
+ pagination: TrueForge.TokenPagination;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxConfig.ts b/packages/trueforge-sdk/src/api/types/SandboxConfig.ts
index ebd8ca110..aa7a0b848 100644
--- a/packages/trueforge-sdk/src/api/types/SandboxConfig.ts
+++ b/packages/trueforge-sdk/src/api/types/SandboxConfig.ts
@@ -3,6 +3,8 @@
export interface SandboxConfig {
/** Give the agent a sandbox. Required for skills and Code Mode. */
enabled: boolean;
+ /** Name of a configured sandbox environment to use. Must exist when set. */
+ environmentName?: string;
/** Allow downloading agent-produced files via the turn download endpoint. Default: true. */
fileDownloads?: boolean;
}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironment.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironment.ts
new file mode 100644
index 000000000..6d1b11b14
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironment.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface SandboxEnvironment {
+ /** ISO-8601 create time. */
+ createdAt: Date;
+ createdBySubject: TrueForge.CreatedBySubject;
+ /** Human-readable description; empty when unset. */
+ description: string;
+ /** Immutable server-generated environment identifier. */
+ id: string;
+ lifecycleStage: TrueForge.SandboxEnvironmentLifecycleStage;
+ manifest: TrueForge.SandboxEnvironmentManifest;
+ name: TrueForge.ResourceName;
+ status: TrueForge.SandboxEnvironmentVersionStatus;
+ /** Failure detail when status is failed; null otherwise. */
+ statusReason: string | null;
+ /** ISO-8601 last update time. */
+ updatedAt: Date;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentImage.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentImage.ts
new file mode 100644
index 000000000..238f15f31
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentImage.ts
@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface SandboxEnvironmentImage {
+ /** Shell script used to build the snapshot. */
+ buildScript?: string;
+ /** Build a snapshot from a script. */
+ type: "build";
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentLifecycleStage.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentLifecycleStage.ts
new file mode 100644
index 000000000..eb6f2e259
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentLifecycleStage.ts
@@ -0,0 +1,9 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/** Soft-delete lifecycle stage. */
+export const SandboxEnvironmentLifecycleStage = {
+ Active: "active",
+ Deleted: "deleted",
+} as const;
+export type SandboxEnvironmentLifecycleStage =
+ (typeof SandboxEnvironmentLifecycleStage)[keyof typeof SandboxEnvironmentLifecycleStage];
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifest.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifest.ts
new file mode 100644
index 000000000..0e9343436
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifest.ts
@@ -0,0 +1,13 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface SandboxEnvironmentManifest {
+ /** Optional human-readable description. */
+ description?: string;
+ environmentVariables?: Record<string, string>;
+ image?: TrueForge.SandboxEnvironmentImage;
+ name: TrueForge.ResourceName;
+ networking?: TrueForge.SandboxEnvironmentNetworking;
+ resources?: TrueForge.SandboxEnvironmentResources;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentNetworking.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentNetworking.ts
new file mode 100644
index 000000000..bf109f659
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentNetworking.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface SandboxEnvironmentNetworking {
+ /** Comma-separated allowed domains. */
+ domainAllowList?: string;
+ /** Block all outbound network access. When true, domain_allow_list and secrets are not used. */
+ networkBlockAll?: boolean;
+ /** Network-scoped secrets. */
+ secrets?: TrueForge.SandboxEnvironmentSecret[];
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentResources.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentResources.ts
new file mode 100644
index 000000000..e3204039c
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentResources.ts
@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface SandboxEnvironmentResources {
+ /** CPU allocation in cores. */
+ cpu?: number;
+ /** Disk allocation in GiB. */
+ disk?: number;
+ /** Memory allocation in GiB. */
+ memory?: number;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentSecret.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentSecret.ts
new file mode 100644
index 000000000..fba8846b2
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentSecret.ts
@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface SandboxEnvironmentSecret {
+ /** Environment variable name injected into the sandbox. */
+ env: string;
+ /** Hosts this secret may be sent to. */
+ hosts: string[];
+ /** Secret value; GET responses use a redacted stand-in. */
+ value: string;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts
new file mode 100644
index 000000000..15c0b430c
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts
@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/** Readiness of the environment. */
+export const SandboxEnvironmentVersionStatus = {
+ Pending: "pending",
+ Active: "active",
+ Failed: "failed",
+} as const;
+export type SandboxEnvironmentVersionStatus =
+ (typeof SandboxEnvironmentVersionStatus)[keyof typeof SandboxEnvironmentVersionStatus];
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index 733cc6cdb..d94cd0213 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -55,6 +55,7 @@ export * from "./CronExpression.js";
export * from "./CustomModelProvider.js";
export * from "./DaytonaSandboxProviderAuth.js";
export * from "./DeleteAgentResponse.js";
+export * from "./DeleteSandboxEnvironmentResponse.js";
export * from "./DeleteScheduleResponse.js";
export * from "./DynamicSubAgentsConfig.js";
export * from "./ExtendedChunkDeltaToolCall.js";
@@ -72,6 +73,7 @@ export * from "./GetMeResponse.js";
export * from "./GetMeSubject.js";
export * from "./GetModelProviderCatalogResponse.js";
export * from "./GetModelProviderResponse.js";
+export * from "./GetSandboxEnvironmentResponse.js";
export * from "./GetSandboxProviderCatalogResponse.js";
export * from "./GetSandboxProviderResponse.js";
export * from "./GetScheduleResponse.js";
@@ -98,6 +100,7 @@ export * from "./ListMcpServerToolsResponse.js";
export * from "./ListModelProvidersResponse.js";
export * from "./ListPermissionsData.js";
export * from "./ListPermissionsResponse.js";
+export * from "./ListSandboxEnvironmentsResponse.js";
export * from "./ListScheduleRunsResponse.js";
export * from "./ListSchedulesResponse.js";
export * from "./ListSessionEventsResponse.js";
@@ -162,6 +165,14 @@ export * from "./SandboxBuildStatus.js";
export * from "./SandboxCapability.js";
export * from "./SandboxConfig.js";
export * from "./SandboxCreatedEvent.js";
+export * from "./SandboxEnvironment.js";
+export * from "./SandboxEnvironmentImage.js";
+export * from "./SandboxEnvironmentLifecycleStage.js";
+export * from "./SandboxEnvironmentManifest.js";
+export * from "./SandboxEnvironmentNetworking.js";
+export * from "./SandboxEnvironmentResources.js";
+export * from "./SandboxEnvironmentSecret.js";
+export * from "./SandboxEnvironmentVersionStatus.js";
export * from "./SandboxProviderManifest.js";
export * from "./Schedule.js";
export * from "./ScheduleManifest.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/index.ts b/packages/trueforge-sdk/src/serialization/resources/index.ts
index 4d4bfd3a0..fb0e61aaf 100644
--- a/packages/trueforge-sdk/src/serialization/resources/index.ts
+++ b/packages/trueforge-sdk/src/serialization/resources/index.ts
@@ -2,6 +2,8 @@ export * from "./agents/client/requests/index.js";
export * as agents from "./agents/index.js";
export * from "./internal/client/requests/index.js";
export * as internal from "./internal/index.js";
+export * from "./sandboxEnvironments/client/requests/index.js";
+export * as sandboxEnvironments from "./sandboxEnvironments/index.js";
export * from "./schedules/client/requests/index.js";
export * as schedules from "./schedules/index.js";
export * from "./sessions/client/requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/index.ts b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
new file mode 100644
index 000000000..cc1001878
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
@@ -0,0 +1,19 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../../api/index.js";
+import * as core from "../../../../../core/index.js";
+import type * as serializers from "../../../../index.js";
+import { SandboxEnvironmentManifest } from "../../../../types/SandboxEnvironmentManifest.js";
+
+export const UpdateSandboxEnvironmentRequest: core.serialization.Schema<
+ serializers.UpdateSandboxEnvironmentRequest.Raw,
+ TrueForge.UpdateSandboxEnvironmentRequest
+> = core.serialization.object({
+ manifest: SandboxEnvironmentManifest,
+});
+
+export declare namespace UpdateSandboxEnvironmentRequest {
+ export interface Raw {
+ manifest: SandboxEnvironmentManifest.Raw;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/index.ts b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/index.ts
new file mode 100644
index 000000000..ab09842a3
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/index.ts
@@ -0,0 +1 @@
+export { UpdateSandboxEnvironmentRequest } from "./UpdateSandboxEnvironmentRequest.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/index.ts b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/DeleteSandboxEnvironmentResponse.ts b/packages/trueforge-sdk/src/serialization/types/DeleteSandboxEnvironmentResponse.ts
new file mode 100644
index 000000000..11565de1b
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/DeleteSandboxEnvironmentResponse.ts
@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const DeleteSandboxEnvironmentResponse: core.serialization.ObjectSchema<
+ serializers.DeleteSandboxEnvironmentResponse.Raw,
+ TrueForge.DeleteSandboxEnvironmentResponse
+> = core.serialization.object({});
+
+export declare namespace DeleteSandboxEnvironmentResponse {
+ export type Raw = {};
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/GetSandboxEnvironmentResponse.ts b/packages/trueforge-sdk/src/serialization/types/GetSandboxEnvironmentResponse.ts
new file mode 100644
index 000000000..400aa98b2
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/GetSandboxEnvironmentResponse.ts
@@ -0,0 +1,19 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { SandboxEnvironment } from "./SandboxEnvironment.js";
+
+export const GetSandboxEnvironmentResponse: core.serialization.ObjectSchema<
+ serializers.GetSandboxEnvironmentResponse.Raw,
+ TrueForge.GetSandboxEnvironmentResponse
+> = core.serialization.object({
+ data: SandboxEnvironment,
+});
+
+export declare namespace GetSandboxEnvironmentResponse {
+ export interface Raw {
+ data: SandboxEnvironment.Raw;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/ListSandboxEnvironmentsResponse.ts b/packages/trueforge-sdk/src/serialization/types/ListSandboxEnvironmentsResponse.ts
new file mode 100644
index 000000000..c33d25772
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/ListSandboxEnvironmentsResponse.ts
@@ -0,0 +1,22 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { SandboxEnvironment } from "./SandboxEnvironment.js";
+import { TokenPagination } from "./TokenPagination.js";
+
+export const ListSandboxEnvironmentsResponse: core.serialization.ObjectSchema<
+ serializers.ListSandboxEnvironmentsResponse.Raw,
+ TrueForge.ListSandboxEnvironmentsResponse
+> = core.serialization.object({
+ data: core.serialization.list(SandboxEnvironment),
+ pagination: TokenPagination,
+});
+
+export declare namespace ListSandboxEnvironmentsResponse {
+ export interface Raw {
+ data: SandboxEnvironment.Raw[];
+ pagination: TokenPagination.Raw;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxConfig.ts b/packages/trueforge-sdk/src/serialization/types/SandboxConfig.ts
index 6476134b7..a5906238b 100644
--- a/packages/trueforge-sdk/src/serialization/types/SandboxConfig.ts
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxConfig.ts
@@ -7,12 +7,14 @@ import type * as serializers from "../index.js";
export const SandboxConfig: core.serialization.ObjectSchema<serializers.SandboxConfig.Raw, TrueForge.SandboxConfig> =
core.serialization.object({
enabled: core.serialization.boolean(),
+ environmentName: core.serialization.property("environment_name", core.serialization.string().optional()),
fileDownloads: core.serialization.property("file_downloads", core.serialization.boolean().optional()),
});
export declare namespace SandboxConfig {
export interface Raw {
enabled: boolean;
+ environment_name?: string | null;
file_downloads?: boolean | null;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironment.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironment.ts
new file mode 100644
index 000000000..9232af91b
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironment.ts
@@ -0,0 +1,41 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { CreatedBySubject } from "./CreatedBySubject.js";
+import { ResourceName } from "./ResourceName.js";
+import { SandboxEnvironmentLifecycleStage } from "./SandboxEnvironmentLifecycleStage.js";
+import { SandboxEnvironmentManifest } from "./SandboxEnvironmentManifest.js";
+import { SandboxEnvironmentVersionStatus } from "./SandboxEnvironmentVersionStatus.js";
+
+export const SandboxEnvironment: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironment.Raw,
+ TrueForge.SandboxEnvironment
+> = core.serialization.object({
+ createdAt: core.serialization.property("created_at", core.serialization.date()),
+ createdBySubject: core.serialization.property("created_by_subject", CreatedBySubject),
+ description: core.serialization.string(),
+ id: core.serialization.string(),
+ lifecycleStage: core.serialization.property("lifecycle_stage", SandboxEnvironmentLifecycleStage),
+ manifest: SandboxEnvironmentManifest,
+ name: ResourceName,
+ status: SandboxEnvironmentVersionStatus,
+ statusReason: core.serialization.property("status_reason", core.serialization.string().nullable()),
+ updatedAt: core.serialization.property("updated_at", core.serialization.date()),
+});
+
+export declare namespace SandboxEnvironment {
+ export interface Raw {
+ created_at: string;
+ created_by_subject: CreatedBySubject.Raw;
+ description: string;
+ id: string;
+ lifecycle_stage: SandboxEnvironmentLifecycleStage.Raw;
+ manifest: SandboxEnvironmentManifest.Raw;
+ name: ResourceName.Raw;
+ status: SandboxEnvironmentVersionStatus.Raw;
+ status_reason?: string | null;
+ updated_at: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentImage.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentImage.ts
new file mode 100644
index 000000000..41b0c8b63
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentImage.ts
@@ -0,0 +1,20 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const SandboxEnvironmentImage: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentImage.Raw,
+ TrueForge.SandboxEnvironmentImage
+> = core.serialization.object({
+ buildScript: core.serialization.property("build_script", core.serialization.string().optional()),
+ type: core.serialization.stringLiteral("build"),
+});
+
+export declare namespace SandboxEnvironmentImage {
+ export interface Raw {
+ build_script?: string | null;
+ type: "build";
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentLifecycleStage.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentLifecycleStage.ts
new file mode 100644
index 000000000..9b7a5630a
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentLifecycleStage.ts
@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const SandboxEnvironmentLifecycleStage: core.serialization.Schema<
+ serializers.SandboxEnvironmentLifecycleStage.Raw,
+ TrueForge.SandboxEnvironmentLifecycleStage
+> = core.serialization.enum_(["active", "deleted"]);
+
+export declare namespace SandboxEnvironmentLifecycleStage {
+ export type Raw = "active" | "deleted";
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifest.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifest.ts
new file mode 100644
index 000000000..4f9aed3a3
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifest.ts
@@ -0,0 +1,35 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { ResourceName } from "./ResourceName.js";
+import { SandboxEnvironmentImage } from "./SandboxEnvironmentImage.js";
+import { SandboxEnvironmentNetworking } from "./SandboxEnvironmentNetworking.js";
+import { SandboxEnvironmentResources } from "./SandboxEnvironmentResources.js";
+
+export const SandboxEnvironmentManifest: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentManifest.Raw,
+ TrueForge.SandboxEnvironmentManifest
+> = core.serialization.object({
+ description: core.serialization.string().optional(),
+ environmentVariables: core.serialization.property(
+ "environment_variables",
+ core.serialization.record(core.serialization.string(), core.serialization.string()).optional(),
+ ),
+ image: SandboxEnvironmentImage.optional(),
+ name: ResourceName,
+ networking: SandboxEnvironmentNetworking.optional(),
+ resources: SandboxEnvironmentResources.optional(),
+});
+
+export declare namespace SandboxEnvironmentManifest {
+ export interface Raw {
+ description?: string | null;
+ environment_variables?: Record<string, string> | null;
+ image?: SandboxEnvironmentImage.Raw | null;
+ name: ResourceName.Raw;
+ networking?: SandboxEnvironmentNetworking.Raw | null;
+ resources?: SandboxEnvironmentResources.Raw | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentNetworking.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentNetworking.ts
new file mode 100644
index 000000000..2e84030f2
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentNetworking.ts
@@ -0,0 +1,23 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { SandboxEnvironmentSecret } from "./SandboxEnvironmentSecret.js";
+
+export const SandboxEnvironmentNetworking: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentNetworking.Raw,
+ TrueForge.SandboxEnvironmentNetworking
+> = core.serialization.object({
+ domainAllowList: core.serialization.property("domain_allow_list", core.serialization.string().optional()),
+ networkBlockAll: core.serialization.property("network_block_all", core.serialization.boolean().optional()),
+ secrets: core.serialization.list(SandboxEnvironmentSecret).optional(),
+});
+
+export declare namespace SandboxEnvironmentNetworking {
+ export interface Raw {
+ domain_allow_list?: string | null;
+ network_block_all?: boolean | null;
+ secrets?: SandboxEnvironmentSecret.Raw[] | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentResources.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentResources.ts
new file mode 100644
index 000000000..fc8d6fc48
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentResources.ts
@@ -0,0 +1,22 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const SandboxEnvironmentResources: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentResources.Raw,
+ TrueForge.SandboxEnvironmentResources
+> = core.serialization.object({
+ cpu: core.serialization.number().optional(),
+ disk: core.serialization.number().optional(),
+ memory: core.serialization.number().optional(),
+});
+
+export declare namespace SandboxEnvironmentResources {
+ export interface Raw {
+ cpu?: number | null;
+ disk?: number | null;
+ memory?: number | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentSecret.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentSecret.ts
new file mode 100644
index 000000000..4f9f091a8
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentSecret.ts
@@ -0,0 +1,22 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const SandboxEnvironmentSecret: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentSecret.Raw,
+ TrueForge.SandboxEnvironmentSecret
+> = core.serialization.object({
+ env: core.serialization.string(),
+ hosts: core.serialization.list(core.serialization.string()),
+ value: core.serialization.string(),
+});
+
+export declare namespace SandboxEnvironmentSecret {
+ export interface Raw {
+ env: string;
+ hosts: string[];
+ value: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts
new file mode 100644
index 000000000..56c9013f5
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts
@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const SandboxEnvironmentVersionStatus: core.serialization.Schema<
+ serializers.SandboxEnvironmentVersionStatus.Raw,
+ TrueForge.SandboxEnvironmentVersionStatus
+> = core.serialization.enum_(["pending", "active", "failed"]);
+
+export declare namespace SandboxEnvironmentVersionStatus {
+ export type Raw = "pending" | "active" | "failed";
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index 733cc6cdb..d94cd0213 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -55,6 +55,7 @@ export * from "./CronExpression.js";
export * from "./CustomModelProvider.js";
export * from "./DaytonaSandboxProviderAuth.js";
export * from "./DeleteAgentResponse.js";
+export * from "./DeleteSandboxEnvironmentResponse.js";
export * from "./DeleteScheduleResponse.js";
export * from "./DynamicSubAgentsConfig.js";
export * from "./ExtendedChunkDeltaToolCall.js";
@@ -72,6 +73,7 @@ export * from "./GetMeResponse.js";
export * from "./GetMeSubject.js";
export * from "./GetModelProviderCatalogResponse.js";
export * from "./GetModelProviderResponse.js";
+export * from "./GetSandboxEnvironmentResponse.js";
export * from "./GetSandboxProviderCatalogResponse.js";
export * from "./GetSandboxProviderResponse.js";
export * from "./GetScheduleResponse.js";
@@ -98,6 +100,7 @@ export * from "./ListMcpServerToolsResponse.js";
export * from "./ListModelProvidersResponse.js";
export * from "./ListPermissionsData.js";
export * from "./ListPermissionsResponse.js";
+export * from "./ListSandboxEnvironmentsResponse.js";
export * from "./ListScheduleRunsResponse.js";
export * from "./ListSchedulesResponse.js";
export * from "./ListSessionEventsResponse.js";
@@ -162,6 +165,14 @@ export * from "./SandboxBuildStatus.js";
export * from "./SandboxCapability.js";
export * from "./SandboxConfig.js";
export * from "./SandboxCreatedEvent.js";
+export * from "./SandboxEnvironment.js";
+export * from "./SandboxEnvironmentImage.js";
+export * from "./SandboxEnvironmentLifecycleStage.js";
+export * from "./SandboxEnvironmentManifest.js";
+export * from "./SandboxEnvironmentNetworking.js";
+export * from "./SandboxEnvironmentResources.js";
+export * from "./SandboxEnvironmentSecret.js";
+export * from "./SandboxEnvironmentVersionStatus.js";
export * from "./SandboxProviderManifest.js";
export * from "./Schedule.js";
export * from "./ScheduleManifest.js";
diff --git a/packages/trueforge-sdk/tests/wire/sandboxEnvironments.test.ts b/packages/trueforge-sdk/tests/wire/sandboxEnvironments.test.ts
new file mode 100644
index 000000000..634ee4949
--- /dev/null
+++ b/packages/trueforge-sdk/tests/wire/sandboxEnvironments.test.ts
@@ -0,0 +1,466 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import * as TrueForgeTypes from "../../src/api/index";
+import { TrueForge } from "../../src/Client";
+import { mockServerPool } from "../mock-server/MockServerPool";
+
+describe("SandboxEnvironmentsClient", () => {
+ test("list (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = {
+ data: [
+ {
+ created_at: "2024-01-15T09:30:00Z",
+ created_by_subject: {
+ subject_display_name: "subject_display_name",
+ subject_id: "subject_id",
+ subject_type: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycle_stage: "active",
+ manifest: { image: { build_script: "set -ex\npip install httpx\n", type: "build" }, name: "name" },
+ name: "name",
+ status: "pending",
+ status_reason: "status_reason",
+ updated_at: "2024-01-15T09:30:00Z",
+ },
+ ],
+ pagination: { limit: 1, next_page_token: "next_page_token", previous_page_token: "previous_page_token" },
+ };
+
+ server
+ .mockEndpoint({ once: false })
+ .get("/api/v1/sandbox-environments")
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const expected = {
+ data: [
+ {
+ createdAt: new Date("2024-01-15T09:30:00.000Z"),
+ createdBySubject: {
+ subjectDisplayName: "subject_display_name",
+ subjectId: "subject_id",
+ subjectType: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycleStage: "active",
+ manifest: {
+ image: {
+ buildScript: "set -ex\npip install httpx\n",
+ type: "build",
+ },
+ name: "name",
+ },
+ name: "name",
+ status: "pending",
+ statusReason: "status_reason",
+ updatedAt: new Date("2024-01-15T09:30:00.000Z"),
+ },
+ ],
+ pagination: {
+ limit: 1,
+ nextPageToken: "next_page_token",
+ previousPageToken: "previous_page_token",
+ },
+ };
+ const page = await client.sandboxEnvironments.list();
+
+ expect(expected.data).toEqual(page.data);
+ expect(page.hasNextPage()).toBe(true);
+ const nextPage = await page.getNextPage();
+ expect(expected.data).toEqual(nextPage.data);
+ });
+
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/sandbox-environments")
+ .respondWith()
+ .statusCode(400)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.list();
+ }).rejects.toThrow(TrueForgeTypes.BadRequestError);
+ });
+
+ test("list (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/sandbox-environments")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("create_or_update (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { name: "name" } };
+ const rawResponseBody = {
+ data: {
+ created_at: "2024-01-15T09:30:00Z",
+ created_by_subject: {
+ subject_display_name: "subject_display_name",
+ subject_id: "subject_id",
+ subject_type: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycle_stage: "active",
+ manifest: {
+ description: "description",
+ environment_variables: { key: "value" },
+ image: { build_script: "set -ex\npip install httpx\n", type: "build" },
+ name: "name",
+ },
+ name: "name",
+ status: "pending",
+ status_reason: "status_reason",
+ updated_at: "2024-01-15T09:30:00Z",
+ },
+ };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/sandbox-environments")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "name",
+ },
+ });
+ expect(response).toEqual({
+ data: {
+ createdAt: new Date("2024-01-15T09:30:00.000Z"),
+ createdBySubject: {
+ subjectDisplayName: "subject_display_name",
+ subjectId: "subject_id",
+ subjectType: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycleStage: "active",
+ manifest: {
+ description: "description",
+ environmentVariables: {
+ key: "value",
+ },
+ image: {
+ buildScript: "set -ex\npip install httpx\n",
+ type: "build",
+ },
+ name: "name",
+ },
+ name: "name",
+ status: "pending",
+ statusReason: "status_reason",
+ updatedAt: new Date("2024-01-15T09:30:00.000Z"),
+ },
+ });
+ });
+
+ test("create_or_update (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { name: "xy" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/sandbox-environments")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(400)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "xy",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.BadRequestError);
+ });
+
+ test("create_or_update (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { name: "xy" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/sandbox-environments")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "xy",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("create_or_update (4)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { name: "xy" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/sandbox-environments")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(409)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "xy",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.ConflictError);
+ });
+
+ test("create_or_update (5)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { name: "xy" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/sandbox-environments")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(422)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.createOrUpdate({
+ manifest: {
+ name: "xy",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.UnprocessableEntityError);
+ });
+
+ test("get (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = {
+ data: {
+ created_at: "2024-01-15T09:30:00Z",
+ created_by_subject: {
+ subject_display_name: "subject_display_name",
+ subject_id: "subject_id",
+ subject_type: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycle_stage: "active",
+ manifest: {
+ description: "description",
+ environment_variables: { key: "value" },
+ image: { build_script: "set -ex\npip install httpx\n", type: "build" },
+ name: "name",
+ },
+ name: "name",
+ status: "pending",
+ status_reason: "status_reason",
+ updated_at: "2024-01-15T09:30:00Z",
+ },
+ };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.sandboxEnvironments.get("name");
+ expect(response).toEqual({
+ data: {
+ createdAt: new Date("2024-01-15T09:30:00.000Z"),
+ createdBySubject: {
+ subjectDisplayName: "subject_display_name",
+ subjectId: "subject_id",
+ subjectType: "subject_type",
+ },
+ description: "description",
+ id: "id",
+ lifecycleStage: "active",
+ manifest: {
+ description: "description",
+ environmentVariables: {
+ key: "value",
+ },
+ image: {
+ buildScript: "set -ex\npip install httpx\n",
+ type: "build",
+ },
+ name: "name",
+ },
+ name: "name",
+ status: "pending",
+ statusReason: "status_reason",
+ updatedAt: new Date("2024-01-15T09:30:00.000Z"),
+ },
+ });
+ });
+
+ test("get (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.get("name");
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("get (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(404)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.get("name");
+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);
+ });
+
+ test("delete (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = {};
+
+ server
+ .mockEndpoint()
+ .delete("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.sandboxEnvironments.delete("name");
+ expect(response).toEqual({});
+ });
+
+ test("delete (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .delete("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.delete("name");
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("delete (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .delete("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(404)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.delete("name");
+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);
+ });
+
+ test("delete (4)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .delete("/api/v1/sandbox-environments/name")
+ .respondWith()
+ .statusCode(409)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sandboxEnvironments.delete("name");
+ }).rejects.toThrow(TrueForgeTypes.ConflictError);
+ });
+});
diff --git a/packages/trueforge/scripts/write-openapi.ts b/packages/trueforge/scripts/write-openapi.ts
index 078c1c727..f07bfdec3 100644
--- a/packages/trueforge/scripts/write-openapi.ts
+++ b/packages/trueforge/scripts/write-openapi.ts
@@ -27,6 +27,7 @@ import { SqliteAgentStore } from '../src/db/sqlite/agent-store/SqliteAgentStore'
import { createSqliteDb } from '../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteScheduleStore } from '../src/db/sqlite/schedule-store/SqliteScheduleStore';
import { SqliteSessionMetricsStore } from '../src/db/sqlite/session-metrics/SqliteSessionMetricsStore';
@@ -64,6 +65,7 @@ const sessionStore = new InMemorySessionStore();
const db = createSqliteDb(':memory:');
const tokenStore = new SqliteOAuthTokenStore(db);
const agentStore = new SqliteAgentStore(db);
+const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
const skillStore = new SqliteSkillStore(db);
const sandboxProviderStore = new SqliteSandboxProviderStore(db);
const webSearchProviderStore = new SqliteWebSearchProviderStore(db);
@@ -86,6 +88,7 @@ const app = createServerApp({
resolveAgentStore: () => agentStore,
resolveImportAgentStore: () => agentStore,
agentStore,
+ sandboxEnvironmentStore,
turnSkillsResolverStore: skillStore,
withTransaction: callback => db.transaction().execute(callback),
scheduleStore: new SqliteScheduleStore(db),
diff --git a/packages/trueforge/src/apis/agents.ts b/packages/trueforge/src/apis/agents.ts
index f5d25ae21..5cf30a25a 100644
--- a/packages/trueforge/src/apis/agents.ts
+++ b/packages/trueforge/src/apis/agents.ts
@@ -15,6 +15,7 @@ import {
} from '../db/agentStore';
import type { IMcpServerStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import type { ISkillStore } from '../db/skillStore';
import type { WithTransaction } from '../db/transaction';
@@ -39,6 +40,7 @@ export interface AgentsRouterDeps<TTransaction> {
resolveMcpServerStore: (c: Context) => IMcpServerStore<TTransaction>;
resolveSkillStore: ResolveSkillStore<TTransaction>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
resolveRequestContext: ResolveRequestContext;
@@ -62,24 +64,30 @@ async function validateManifest<TTransaction>({
mcpServerStore,
skillStore,
sandboxProviderStore,
+ sandboxEnvironmentStore,
webSearchProviderStore,
tenant_id,
+ created_by_subject_id,
}: {
spec: AgentSpec;
modelProviderStore: IModelProviderStore<TTransaction>;
mcpServerStore: IMcpServerStore<TTransaction>;
skillStore: ISkillStore<TTransaction>;
sandboxProviderStore: ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
webSearchProviderStore: IWebSearchProviderStore<TTransaction>;
tenant_id: string;
+ created_by_subject_id: string;
}): Promise<AgentSpec> {
await validateAgentSpec({
spec,
tenant_id,
+ created_by_subject_id,
modelProviderStore,
mcpServerStore,
skillStore,
sandboxProviderStore,
+ sandboxEnvironmentStore,
webSearchProviderStore,
});
return spec;
@@ -117,8 +125,10 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
mcpServerStore: deps.resolveMcpServerStore(c),
skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
tenant_id: requestContext.tenant_id,
+ created_by_subject_id: requestContext.subject.id,
});
try {
const record = await deps.resolveAgentStore(c).createAgent({
@@ -222,8 +232,10 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
mcpServerStore: deps.resolveMcpServerStore(c),
skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
tenant_id: requestContext.tenant_id,
+ created_by_subject_id: requestContext.subject.id,
});
const record = await deps.resolveAgentStore(c).updateAgent({
tenant_id: requestContext.tenant_id,
diff --git a/packages/trueforge/src/apis/sandboxEnvironments.ts b/packages/trueforge/src/apis/sandboxEnvironments.ts
index 9039e3948..74685ffcc 100644
--- a/packages/trueforge/src/apis/sandboxEnvironments.ts
+++ b/packages/trueforge/src/apis/sandboxEnvironments.ts
@@ -1,107 +1,206 @@
/**
* Sandbox environments API (mounted at /api/v1/sandbox-environments).
- * Handlers return properly shaped dummy data; no DB persistence yet.
- * OpenAPI / Fern registration intentionally deferred.
+ * Snapshot builds are not started here — versions land in `pending` for a future controller.
*/
-import { OpenAPIHono, z } from '@hono/zod-openapi';
+import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
+import { InvalidPageTokenError } from '@truefoundry/trueforge-core/agent-session';
import type { Context } from 'hono';
-import { PAGE_LIMIT } from '../schemas/common';
+import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';
+import { isTrueFoundryModeEnabled } from '../config';
+import type { IAgentStore } from '../db/agentStore';
import {
- CreateSandboxEnvironmentRequestSchema,
- UpdateSandboxEnvironmentRequestSchema,
- type SandboxEnvironment,
- type SandboxEnvironmentManifest,
-} from '../schemas/sandboxEnvironment';
-import { zodErrorResponse } from '../zodErrorResponse';
-
-const DUMMY_CREATED_AT = '2026-09-26T00:00:00.000Z';
+ SandboxEnvironmentNameConflictError,
+ SandboxEnvironmentVersionConflictError,
+ type ISandboxEnvironmentStore,
+ type SandboxEnvironmentWithVersion,
+ type UpsertSandboxEnvironmentPrevious,
+} from '../db/sandboxEnvironmentStore';
+import type { ISandboxProviderStore, SandboxProviderRecord } from '../db/sandboxProviderStore';
+import {
+ deleteSandboxEnvironmentRoute,
+ getSandboxEnvironmentRoute,
+ listSandboxEnvironmentsRoute,
+ putSandboxEnvironmentRoute,
+} from '../routes/sandboxEnvironmentRoutes';
+import { buildNextVersion, redactManifestSecrets } from '../sandbox/sandboxEnvironmentVersion';
+import type { SandboxEnvironment, SandboxEnvironmentManifest } from '../schemas/sandboxEnvironment';
+import { MissingStoredSecretError } from '../utils/secretRedaction';
-const DUMMY_BASE_MANIFEST: SandboxEnvironmentManifest = {
- name: 'xyz',
- description: 'my-env',
- image: {
- type: 'build',
- build_script: 'set -ex\npip install httpx\n',
- },
- resources: { cpu: 1, memory: 1, disk: 3 },
- environment_variables: { FOO: 'bar' },
- networking: {
- network_block_all: false,
- domain_allow_list: 'api.github.com,api.openai.com',
- secrets: [{ env: 'GITHUB_TOKEN', value: '*****', hosts: ['api.github.com'] }],
- },
-};
+export interface SandboxEnvironmentsRouterDeps<TTransaction> {
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
+ resolveAgentStore: (c: Context) => IAgentStore<TTransaction>;
+ resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ resolveRequestContext: ResolveRequestContext;
+}
-function dummyEnvironment(manifest: SandboxEnvironmentManifest = DUMMY_BASE_MANIFEST): SandboxEnvironment {
+function toSandboxEnvironment({ environment, version }: SandboxEnvironmentWithVersion): SandboxEnvironment {
+ const { type, sandbox_provider, ...manifest } = version.manifest;
+ void type;
+ void sandbox_provider;
return {
- id: '01HZXAMPLE0000000000000000',
- name: manifest.name,
- description: manifest.description ?? '',
- active_version: 1,
- lifecycle_stage: 'active',
- manifest,
- version: {
- version: 1,
- status: 'active',
- status_reason: null,
- external_ref: 'trueforge-build-example',
- },
- created_by_subject: {
- subject_id: 'dummy-user',
- subject_type: 'user',
- subject_display_name: 'Dummy User',
- },
- created_at: DUMMY_CREATED_AT,
- updated_at: DUMMY_CREATED_AT,
+ id: environment.id,
+ name: environment.name,
+ description: environment.description,
+ lifecycle_stage: environment.lifecycle_stage,
+ status: version.status,
+ status_reason: version.status_reason,
+ manifest: redactManifestSecrets(manifest),
+ created_by_subject: environment.created_by_subject,
+ created_at: environment.created_at,
+ updated_at: environment.updated_at,
};
}
-async function validateJsonBody<T>(
- c: Context,
- schema: z.ZodType<T>,
-): Promise<{ ok: true; data: T } | { ok: false; response: Response }> {
- const raw: unknown = await c.req.json();
- const parsed = schema.safeParse(raw);
- if (!parsed.success) {
- return { ok: false, response: zodErrorResponse(c, parsed.error) };
- }
- return { ok: true, data: parsed.data };
+/** Resolve the tenant sandbox provider record, if configured. */
+async function resolveSandboxProviderRecord(
+ providerStore: ISandboxProviderStore,
+ tenant_id: string,
+): Promise<SandboxProviderRecord | undefined> {
+ return providerStore.getSandboxProvider(tenant_id);
}
-/** Dummy CRUD for sandbox environments (no OpenAPI registration yet). */
-export function createSandboxEnvironmentsRouter(): OpenAPIHono {
- const router = new OpenAPIHono();
+function buildUpsertVersion({
+ manifest,
+ created_by_subject,
+ previous,
+}: {
+ manifest: SandboxEnvironmentManifest;
+ created_by_subject: ReturnType<typeof createdBySubjectFromRequestContext>;
+ previous?: UpsertSandboxEnvironmentPrevious;
+}) {
+ // Label follows platform mode; create/build always use Daytona credentials + code.
+ return {
+ ...buildNextVersion({
+ version: previous ? previous.latest_version + 1 : 1,
+ ...(previous
+ ? {
+ previous_manifest: previous.previous_manifest,
+ previous_external_ref: previous.previous_external_ref,
+ }
+ : {}),
+ manifest,
+ provider_type: isTrueFoundryModeEnabled() ? 'truefoundry' : 'daytona',
+ }),
+ created_by_subject,
+ };
+}
- router.get('/', c => {
- return c.json({
- data: [dummyEnvironment()],
- pagination: { limit: PAGE_LIMIT },
- });
- });
+/** CRUD for sandbox environments. */
+export function createSandboxEnvironmentsRouter<TTransaction>(
+ deps: SandboxEnvironmentsRouterDeps<TTransaction>,
+): OpenAPIHono {
+ const { sandboxEnvironmentStore: store, resolveAgentStore, resolveRequestContext } = deps;
- router.get('/:name', c => {
- return c.json({ data: dummyEnvironment() });
- });
+ const listHandler: RouteHandler<typeof listSandboxEnvironmentsRoute> = async c => {
+ const { tenant_id, subject } = resolveRequestContext(c);
+ const { limit, page_token: pageToken } = c.req.valid('query');
+ try {
+ const listed = await store.listEnvironments({
+ tenant_id,
+ created_by_subject_id: subject.id,
+ limit,
+ page_token: pageToken,
+ });
+ return c.json({ data: listed.data.map(toSandboxEnvironment), pagination: listed.pagination }, 200);
+ } catch (error) {
+ if (error instanceof InvalidPageTokenError) {
+ return c.json({ error: { message: error.message } }, 400);
+ }
+ throw error;
+ }
+ };
- router.post('/', async c => {
- const body = await validateJsonBody(c, CreateSandboxEnvironmentRequestSchema);
- if (!body.ok) {
- return body.response;
+ const getHandler: RouteHandler<typeof getSandboxEnvironmentRoute> = async c => {
+ const { tenant_id, subject } = resolveRequestContext(c);
+ const { name } = c.req.valid('param');
+ const loaded = await store.getEnvironment({
+ tenant_id,
+ name,
+ created_by_subject_id: subject.id,
+ });
+ if (!loaded) {
+ return c.json({ error: { message: `Sandbox environment not found: ${name}` } }, 404);
}
- return c.json({ data: dummyEnvironment(body.data.manifest) }, 201);
- });
+ return c.json({ data: toSandboxEnvironment(loaded) }, 200);
+ };
- router.put('/:name', async c => {
- const body = await validateJsonBody(c, UpdateSandboxEnvironmentRequestSchema);
- if (!body.ok) {
- return body.response;
+ // Create-or-update keyed by manifest.name.
+ const putHandler: RouteHandler<typeof putSandboxEnvironmentRoute> = async c => {
+ const body = c.req.valid('json');
+ const requestContext = resolveRequestContext(c);
+ const provider = await resolveSandboxProviderRecord(deps.resolveSandboxProviderStore(c), requestContext.tenant_id);
+ if (provider?.manifest.type !== 'daytona') {
+ return c.json({ error: { message: 'Sandbox environments require a Daytona sandbox provider' } }, 422);
}
- return c.json({ data: dummyEnvironment(body.data.manifest) });
- });
- router.delete('/:name', c => {
- return c.json({});
- });
+ const created_by_subject = createdBySubjectFromRequestContext(requestContext);
+ const { manifest } = body;
+ try {
+ const result = await store.upsertEnvironment({
+ tenant_id: requestContext.tenant_id,
+ name: manifest.name,
+ description: manifest.description ?? '',
+ created_by_subject,
+ buildVersion: previous =>
+ buildUpsertVersion({
+ manifest,
+ created_by_subject,
+ ...(previous ? { previous } : {}),
+ }),
+ });
+ return c.json({ data: toSandboxEnvironment(result) }, 200);
+ } catch (error) {
+ if (error instanceof SandboxEnvironmentNameConflictError) {
+ return c.json({ error: { message: error.message } }, 409);
+ }
+ if (error instanceof SandboxEnvironmentVersionConflictError) {
+ return c.json({ error: { message: 'Sandbox environment was updated concurrently; retry' } }, 409);
+ }
+ if (error instanceof MissingStoredSecretError) {
+ return c.json({ error: { message: 'Secret value is required' } }, 400);
+ }
+ throw error;
+ }
+ };
+
+ const deleteHandler: RouteHandler<typeof deleteSandboxEnvironmentRoute> = async c => {
+ const { tenant_id, subject } = resolveRequestContext(c);
+ const { name } = c.req.valid('param');
+ const existing = await store.getEnvironment({
+ tenant_id,
+ name,
+ created_by_subject_id: subject.id,
+ });
+ if (!existing) {
+ return c.json({ error: { message: `Sandbox environment not found: ${name}` } }, 404);
+ }
+ const agentNames = await resolveAgentStore(c).listAgentNamesUsingSandboxEnvironment({
+ tenant_id,
+ environment_name: name,
+ });
+ if (agentNames.length > 0) {
+ return c.json(
+ {
+ error: {
+ message: `Sandbox environment "${name}" is referenced by agent(s): ${agentNames.join(', ')}`,
+ },
+ },
+ 409,
+ );
+ }
+ await store.deleteEnvironment({
+ tenant_id,
+ name,
+ created_by_subject_id: subject.id,
+ });
+ return c.json({}, 200);
+ };
+
+ const router = new OpenAPIHono();
+ router.openapi(listSandboxEnvironmentsRoute, listHandler);
+ router.openapi(getSandboxEnvironmentRoute, getHandler);
+ router.openapi(putSandboxEnvironmentRoute, putHandler);
+ router.openapi(deleteSandboxEnvironmentRoute, deleteHandler);
return router;
}
diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.ts
index fba8ef5e8..725a30210 100644
--- a/packages/trueforge/src/apis/schedules.ts
+++ b/packages/trueforge/src/apis/schedules.ts
@@ -27,6 +27,7 @@ import {
import type { AgentRecord, IAgentStore } from '../db/agentStore';
import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import {
manualRunName,
@@ -73,6 +74,7 @@ export interface ScheduleTurnExecutionDeps<TTransaction> {
resolveModelProviderStore: (c: Context, runAsAgent?: AgentRecord) => IModelProviderStore<TTransaction>;
resolveMcpServerStore: (c: Context, runAsAgent?: AgentRecord) => IMcpServerWithAuthStore<TTransaction>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore<TTransaction>;
/** Persistence agent store (schedule agent binding is not caller-scoped). */
agentStore: IAgentStore<TTransaction>;
@@ -116,6 +118,7 @@ export async function startScheduleRunOnRequest<TTransaction>(params: {
modelProviderStore: deps.resolveModelProviderStore(c, prepared.agent),
mcpServerStore: deps.resolveMcpServerStore(c, prepared.agent),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
skillStore: deps.turnSkillsResolverStore,
logger: deps.logger,
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index c865e0e7f..e98fee6ec 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -27,6 +27,7 @@ import configuration from '../config';
import type { IAgentStore } from '../db/agentStore';
import type { IMcpServerStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';
import {
@@ -82,6 +83,7 @@ export interface SessionsRouterDeps {
resolveSkillStore: ResolveSkillStore;
resolveAgentStore: (c: Context) => IAgentStore;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
redis?: RedisClient | undefined;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore;
requestReplyRouter: RequestReplyRouter;
@@ -239,6 +241,7 @@ type InternalSessionsRouterDeps = Pick<
| 'resolveSkillStore'
| 'resolveAgentStore'
| 'resolveSandboxProviderStore'
+ | 'sandboxEnvironmentStore'
| 'resolveWebSearchProviderStore'
| 'resolveRequestContext'
| 'authorizer'
@@ -288,10 +291,12 @@ function createGetOrCreateSessionByExternalIdHandler(
await validateAgentSpec({
spec: body.agent.spec,
tenant_id: requestContext.tenant_id,
+ created_by_subject_id: requestContext.subject.id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
});
agent = { type: 'inline', spec: body.agent.spec };
@@ -361,10 +366,12 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
await validateAgentSpec({
spec: body.agent.spec,
tenant_id: requestContext.tenant_id,
+ created_by_subject_id: requestContext.subject.id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
});
const session = await deps.sessions.create({
@@ -453,10 +460,12 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
await validateAgentSpec({
spec: body.agent.spec,
tenant_id: requestContext.tenant_id,
+ created_by_subject_id: requestContext.subject.id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
});
}
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index faef5f957..efeb23427 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -38,6 +38,7 @@ import configuration from '../config';
import type { AgentRecord, IAgentStore } from '../db/agentStore';
import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import type { ISkillStore } from '../db/skillStore';
import type { TurnMetadata } from '../db/turnMetadata';
@@ -120,6 +121,7 @@ export interface TurnsRouterDeps {
/** Resumable live turn-event transport: create-turn writes, subscribe polls. */
eventSubscriptions: EventSubscriptionRegistry<TurnStreamingEvent>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore;
logger: Logger;
resolveRequestContext: ResolveRequestContext;
@@ -131,7 +133,10 @@ export interface TurnsRouterDeps {
* stores; callers must resolve them from the request context (e.g. schedule `resolveTurnDeps(c, agent)`)
* so TrueFoundry mode stays token-bound for models, MCP, and skills.
*/
-export type BeginTurnExecutionDeps = Pick<TurnsRouterDeps, 'activeTurns' | 'eventSubscriptions' | 'logger'> & {
+export type BeginTurnExecutionDeps = Pick<
+ TurnsRouterDeps,
+ 'activeTurns' | 'eventSubscriptions' | 'logger' | 'sandboxEnvironmentStore'
+> & {
agentStore: IAgentStore;
modelProviderStore: IModelProviderStore;
mcpServerStore: IMcpServerWithAuthStore;
@@ -158,6 +163,7 @@ function createTurnResolver(deps: {
mcpServerStore: IMcpServerWithAuthStore;
skillStore: Pick<ISkillStore, 'resolveTurnSkills'>;
sandboxProviderStore: ISandboxProviderStore;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
agentStore: IAgentStore;
modelProviderStore: IModelProviderStore;
webSearchProvider: IWebSearchProvider | undefined;
@@ -171,6 +177,7 @@ function createTurnResolver(deps: {
mcpServerStore,
skillStore,
sandboxProviderStore,
+ sandboxEnvironmentStore,
agentStore,
modelProviderStore,
webSearchProvider,
@@ -223,25 +230,28 @@ function createTurnResolver(deps: {
mcpConnectTimeoutMs: configuration.MCP_CONNECT_TIMEOUT_MS,
mcpMaxResponseBytes: configuration.MCP_TOOL_CALL_MAX_RESPONSE_BYTES,
sandboxProvider: async ({ spec, existingSandboxId, tracing }) => {
- const provider = await resolveSandboxProvider({
+ const environment_name = spec.config.sandbox.environment_name;
+ const resolved = await resolveSandboxProvider({
tenant_id,
store: sandboxProviderStore,
logger,
sessionId,
+ sandboxEnvironmentStore,
+ environment_name,
});
- if (provider === undefined) {
+ if (resolved === undefined) {
throw new HTTPException(422, {
message: 'no sandbox provider configured — PUT /settings/sandbox-providers',
});
}
+ const { provider, usesEnvironmentSnapshot } = resolved;
const carriedSandboxId = existingSandboxIdForProvider({
existingSandboxId,
currentProviderType: provider.type,
});
- // A fresh Daytona sandbox is cloned from the release snapshot, so the build must be ready first.
- // Restoring an existing sandbox goes through daytona.get and never touches the snapshot.
- // Local fallback has no image build.
- if (carriedSandboxId === undefined && provider.type !== 'local') {
+ // Fresh non-local create: env snapshot readiness is gated in resolveSandboxProvider;
+ // release snapshot still needs tenant provider status when not using an env build.
+ if (carriedSandboxId === undefined && provider.type !== 'local' && !usesEnvironmentSnapshot) {
const status = await checkSnapshotStatus({ store: sandboxProviderStore, tenant_id, logger });
if (status?.status !== 'ready') {
throw new HTTPException(422, {
@@ -414,6 +424,7 @@ export async function beginTurnExecution(
mcpServerStore: deps.mcpServerStore,
skillStore: deps.skillStore,
sandboxProviderStore: deps.sandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
agentStore: deps.agentStore,
modelProviderStore: deps.modelProviderStore,
webSearchProvider,
@@ -666,18 +677,20 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
return c.json({ error: { message: `Turn has no sandbox: ${turnId}` } }, 412);
}
- const provider = await resolveSandboxProvider({
+ const resolved = await resolveSandboxProvider({
tenant_id: requestContext.tenant_id,
store: deps.resolveSandboxProviderStore(c),
logger: deps.logger,
sessionId,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
+ environment_name: undefined,
});
- if (provider === undefined) {
+ if (resolved === undefined) {
return c.json({ error: { message: 'No sandbox provider configured' } }, 412);
}
// TODO: stream the body instead of buffering the whole file in memory.
- const content = await provider.downloadFile({ sandboxId: rawSandboxId(sandboxId), path });
+ const content = await resolved.provider.downloadFile({ sandboxId: rawSandboxId(sandboxId), path });
return c.body(toArrayBuffer(content), 200, {
'Content-Type': 'application/octet-stream',
'Content-Length': String(content.byteLength),
@@ -796,6 +809,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
skillStore: deps.resolveSkillStore(c),
agentStore: deps.resolveAgentStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
webSearchProviderStore: deps.resolveWebSearchProviderStore(c),
},
};
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index 79ad8d336..0f9897263 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -44,6 +44,7 @@ import configuration, { getPublicUiBasePath, getTrueForgeAuthMode, TrueForgeAuth
import type { AgentRecord, IAgentStore } from './db/agentStore';
import type { IMcpServerWithAuthStore } from './db/mcpServerStore';
import type { IModelProviderStore } from './db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from './db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from './db/sandboxProviderStore';
import type { IScheduleStore } from './db/scheduleStore';
import type { ISessionMetricsStore } from './db/sessionMetricsStore';
@@ -207,6 +208,8 @@ export interface ServerDeps<TTransaction> {
sessionMetricsStore: ISessionMetricsStore;
/** Persistence agent store (schedule runs resolve the bound agent without an HTTP caller). */
agentStore: IAgentStore<TTransaction>;
+ /** Sandbox environment parent + version persistence (no TrueFoundry dual-write). */
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
/** Resolve turn skills - persistence store or TrueFoundry resolve with Service API key (schedule runs do have any caller token). */
turnSkillsResolverStore: Pick<ISkillStore<TTransaction>, 'resolveTurnSkills'>;
sessions: Sessions;
@@ -241,6 +244,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
activeTurns: deps.activeTurns,
turnSkillsResolverStore: deps.turnSkillsResolverStore,
@@ -345,6 +349,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveMcpServerStore: deps.resolveMcpServerStore,
resolveSkillStore: deps.resolveSkillStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
withTransaction: deps.withTransaction,
resolveRequestContext,
@@ -353,7 +358,18 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
authMiddleware,
),
);
- app.route('/api/v1/sandbox-environments', withAuth(createSandboxEnvironmentsRouter(), authMiddleware));
+ app.route(
+ '/api/v1/sandbox-environments',
+ withAuth(
+ createSandboxEnvironmentsRouter({
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
+ resolveAgentStore: deps.resolveAgentStore,
+ resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ resolveRequestContext,
+ }),
+ authMiddleware,
+ ),
+ );
app.route(
'/api/internal/schedules',
withAuth(createScheduleExecutionRouter(scheduleTurnDeps), scheduleExecutionAuthMiddleware),
@@ -408,6 +424,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveSkillStore: deps.resolveSkillStore,
resolveAgentStore: deps.resolveAgentStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
resolveRequestContext,
authorizer: deps.authorizer,
@@ -452,6 +469,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveSkillStore: deps.resolveSkillStore,
resolveAgentStore: deps.resolveAgentStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
redis: deps.redis,
requestReplyRouter: deps.requestReplyRouter,
@@ -475,6 +493,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveAgentStore: deps.resolveAgentStore,
eventSubscriptions: deps.eventSubscriptions,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
logger: deps.logger,
resolveRequestContext,
diff --git a/packages/trueforge/src/db/agentStore.ts b/packages/trueforge/src/db/agentStore.ts
index 8430680d8..69fa60ffa 100644
--- a/packages/trueforge/src/db/agentStore.ts
+++ b/packages/trueforge/src/db/agentStore.ts
@@ -91,6 +91,11 @@ export interface DeleteAgentInput {
id: string;
}
+export interface ListAgentNamesUsingSandboxEnvironmentInput {
+ tenant_id: string;
+ environment_name: string;
+}
+
/** Unique `(tenant_id, name)` violation on create. */
export class AgentNameConflictError extends Error {
readonly tenant_id: string;
@@ -136,4 +141,9 @@ export interface IAgentStore<TTransaction = never> {
updateAgent(input: UpdateAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined>;
/** Deletes by immutable id. Idempotent if already missing. */
deleteAgent(input: DeleteAgentInput, transaction?: TTransaction): Promise<void>;
+ /** Agent names whose manifest references the given sandbox environment name. */
+ listAgentNamesUsingSandboxEnvironment(
+ input: ListAgentNamesUsingSandboxEnvironmentInput,
+ transaction?: TTransaction,
+ ): Promise<readonly string[]>;
}
diff --git a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
index 5a647a839..4ef901f1e 100644
--- a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
+++ b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
@@ -17,6 +17,7 @@ import {
type GetExternalIdsByIdsInput,
type GetOwnedIdsInput,
type IAgentStore,
+ type ListAgentNamesUsingSandboxEnvironmentInput,
type ListAgentsInput,
type UpdateAgentInput,
} from '../../agentStore';
@@ -205,4 +206,19 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
const db = transaction ?? this.#db;
await db.deleteFrom('agent').where('tenant_id', '=', input.tenant_id).where('id', '=', input.id).execute();
}
+
+ async listAgentNamesUsingSandboxEnvironment(
+ input: ListAgentNamesUsingSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<readonly string[]> {
+ const db = transaction ?? this.#db;
+ const rows = await db
+ .selectFrom('agent')
+ .select('name')
+ .where('tenant_id', '=', input.tenant_id)
+ .where(sql`manifest->'config'->'sandbox'->>'environment_name'`, '=', input.environment_name)
+ .orderBy('name', 'asc')
+ .execute();
+ return rows.map(row => row.name);
+ }
}
diff --git a/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts b/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts
new file mode 100644
index 000000000..dd2ca7591
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts
@@ -0,0 +1,372 @@
+import { CreatedBySubjectSchema, type TokenPagination } from '@truefoundry/trueforge-core/agent-session';
+import {
+ decodeOffsetPageToken,
+ paginateOffsetRows,
+} from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
+import type { Kysely, Selectable, Transaction } from 'kysely';
+import { sql } from 'kysely';
+import { NameSchema } from '../../../schemas/common';
+import { SandboxEnvironmentVersionInternalMetadataSchema } from '../../../schemas/sandboxEnvironment';
+import { newId } from '../../../utils/id';
+import { SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ, SANDBOX_ENVIRONMENT_VERSION_UQ } from '../../indexes';
+import {
+ SandboxEnvironmentNameConflictError,
+ SandboxEnvironmentVersionConflictError,
+ parseStoredSandboxEnvironmentManifest,
+ toUpsertSandboxEnvironmentVersionWrite,
+ type DeleteSandboxEnvironmentInput,
+ type GetSandboxEnvironmentInput,
+ type ISandboxEnvironmentStore,
+ type ListSandboxEnvironmentsInput,
+ type MarkSandboxEnvironmentVersionActiveInput,
+ type MarkSandboxEnvironmentVersionFailedInput,
+ type SandboxEnvironmentRecord,
+ type SandboxEnvironmentVersionRecord,
+ type SandboxEnvironmentWithVersion,
+ type UpsertSandboxEnvironmentInput,
+ type UpsertSandboxEnvironmentVersionWrite,
+} from '../../sandboxEnvironmentStore';
+import { isPgConstraint, isUniqueViolation } from '../client';
+import { json, now } from '../sqlExpressions';
+import type { Database, SandboxEnvironmentTable, SandboxEnvironmentVersionTable } from '../types';
+
+type JoinedRow = Selectable<SandboxEnvironmentTable> & {
+ ver_id: string;
+ ver_environment_id: string;
+ ver_version: number;
+ ver_manifest: Selectable<SandboxEnvironmentVersionTable>['manifest'];
+ ver_status: Selectable<SandboxEnvironmentVersionTable>['status'];
+ ver_status_reason: string | null;
+ ver_external_ref: string;
+ ver_internal_metadata: Selectable<SandboxEnvironmentVersionTable>['internal_metadata'];
+ ver_created_by_subject: Selectable<SandboxEnvironmentVersionTable>['created_by_subject'];
+ ver_created_at: Date;
+ ver_updated_at: Date;
+};
+
+function toEnvironmentRecord(row: Selectable<SandboxEnvironmentTable>): SandboxEnvironmentRecord {
+ return {
+ id: row.id,
+ tenant_id: row.tenant_id,
+ name: NameSchema.parse(row.name),
+ description: row.description,
+ active_version: row.active_version,
+ lifecycle_stage: row.lifecycle_stage,
+ created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
+ created_at: row.created_at.toISOString(),
+ updated_at: row.updated_at.toISOString(),
+ };
+}
+
+function toVersionRecord(row: Selectable<SandboxEnvironmentVersionTable>): SandboxEnvironmentVersionRecord {
+ return {
+ id: row.id,
+ environment_id: row.environment_id,
+ version: row.version,
+ manifest: parseStoredSandboxEnvironmentManifest(row.manifest),
+ status: row.status,
+ status_reason: row.status_reason,
+ external_ref: row.external_ref,
+ internal_metadata: SandboxEnvironmentVersionInternalMetadataSchema.parse(row.internal_metadata),
+ created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
+ created_at: row.created_at.toISOString(),
+ updated_at: row.updated_at.toISOString(),
+ };
+}
+
+function toWithVersion(row: JoinedRow): SandboxEnvironmentWithVersion {
+ return {
+ environment: toEnvironmentRecord(row),
+ version: toVersionRecord({
+ id: row.ver_id,
+ environment_id: row.ver_environment_id,
+ version: row.ver_version,
+ manifest: row.ver_manifest,
+ status: row.ver_status,
+ status_reason: row.ver_status_reason,
+ external_ref: row.ver_external_ref,
+ internal_metadata: row.ver_internal_metadata,
+ created_by_subject: row.ver_created_by_subject,
+ created_at: row.ver_created_at,
+ updated_at: row.ver_updated_at,
+ }),
+ };
+}
+
+function activeVersionJoin(db: Kysely<Database> | Transaction<Database>) {
+ return db
+ .selectFrom('sandbox_environment as env')
+ .innerJoin('sandbox_environment_version as ver', join =>
+ join.onRef('ver.environment_id', '=', 'env.id').onRef('ver.version', '=', 'env.active_version'),
+ )
+ .selectAll('env')
+ .select([
+ 'ver.id as ver_id',
+ 'ver.environment_id as ver_environment_id',
+ 'ver.version as ver_version',
+ 'ver.manifest as ver_manifest',
+ 'ver.status as ver_status',
+ 'ver.status_reason as ver_status_reason',
+ 'ver.external_ref as ver_external_ref',
+ 'ver.internal_metadata as ver_internal_metadata',
+ 'ver.created_by_subject as ver_created_by_subject',
+ 'ver.created_at as ver_created_at',
+ 'ver.updated_at as ver_updated_at',
+ ]);
+}
+
+export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore<Transaction<Database>> {
+ readonly #db: Kysely<Database>;
+
+ constructor(db: Kysely<Database>) {
+ this.#db = db;
+ }
+
+ async listEnvironments(
+ input: ListSandboxEnvironmentsInput,
+ transaction?: Transaction<Database>,
+ ): Promise<{ data: SandboxEnvironmentWithVersion[]; pagination: TokenPagination }> {
+ const db = transaction ?? this.#db;
+ const query = activeVersionJoin(db)
+ .where('env.tenant_id', '=', input.tenant_id)
+ .where('env.lifecycle_stage', '=', 'active')
+ .where(sql`env.created_by_subject->>'subject_id'`, '=', input.created_by_subject_id)
+ .orderBy('env.name');
+ if (!input.limit) {
+ const rows = await query.execute();
+ return { data: rows.map(toWithVersion), pagination: { limit: rows.length } };
+ }
+ const offset = decodeOffsetPageToken(input.page_token);
+ const rows = await query
+ .limit(input.limit + 1)
+ .offset(offset)
+ .execute();
+ const { data, pagination } = paginateOffsetRows(rows, input.limit, offset);
+ return { data: data.map(toWithVersion), pagination };
+ }
+
+ async getEnvironment(
+ input: GetSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ const db = transaction ?? this.#db;
+ let query = activeVersionJoin(db)
+ .where('env.tenant_id', '=', input.tenant_id)
+ .where('env.name', '=', input.name)
+ .where('env.lifecycle_stage', '=', 'active');
+ if (input.created_by_subject_id) {
+ query = query.where(sql`env.created_by_subject->>'subject_id'`, '=', input.created_by_subject_id);
+ }
+ const row = await query.executeTakeFirst();
+ return row ? toWithVersion(row) : undefined;
+ }
+
+ async upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion> {
+ if (transaction) {
+ return this.#upsertEnvironment(input, transaction);
+ }
+ return this.#db.transaction().execute(db => this.#upsertEnvironment(input, db));
+ }
+
+ async #upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ db: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion> {
+ const environmentRow = await db
+ .selectFrom('sandbox_environment')
+ .selectAll()
+ .where('tenant_id', '=', input.tenant_id)
+ .where('name', '=', input.name)
+ .where('lifecycle_stage', '=', 'active')
+ .where(sql`created_by_subject->>'subject_id'`, '=', input.created_by_subject.subject_id)
+ .forUpdate()
+ .executeTakeFirst();
+
+ if (!environmentRow) {
+ const environment_id = newId();
+ const versionWrite = toUpsertSandboxEnvironmentVersionWrite(input.buildVersion());
+ // First version: point here so get/list join works; later versions only move the
+ // pointer when their status is (or becomes) active.
+ const active_version = versionWrite.version;
+ try {
+ const created = await db
+ .insertInto('sandbox_environment')
+ .values({
+ id: environment_id,
+ tenant_id: input.tenant_id,
+ name: input.name,
+ description: input.description,
+ active_version,
+ lifecycle_stage: 'active',
+ created_by_subject: json(input.created_by_subject),
+ created_at: now(),
+ updated_at: now(),
+ })
+ .returningAll()
+ .executeTakeFirstOrThrow();
+ return {
+ environment: toEnvironmentRecord(created),
+ version: await this.#insertVersionRow(db, environment_id, versionWrite),
+ };
+ } catch (error) {
+ if (isUniqueViolation(error) || isPgConstraint(error, SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)) {
+ throw new SandboxEnvironmentNameConflictError(
+ { tenant_id: input.tenant_id, name: input.name },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+ }
+
+ const previousVersion = await db
+ .selectFrom('sandbox_environment_version')
+ .selectAll()
+ .where('environment_id', '=', environmentRow.id)
+ .orderBy('version', 'desc')
+ .executeTakeFirstOrThrow();
+ const versionWrite = toUpsertSandboxEnvironmentVersionWrite(
+ input.buildVersion({
+ latest_version: previousVersion.version,
+ previous_manifest: parseStoredSandboxEnvironmentManifest(previousVersion.manifest),
+ previous_external_ref: previousVersion.external_ref,
+ }),
+ );
+ const version = await this.#insertVersionRow(db, environmentRow.id, versionWrite);
+ const updated = await db
+ .updateTable('sandbox_environment')
+ .set({
+ ...(versionWrite.status === 'active' ? { active_version: versionWrite.version } : {}),
+ description: input.description,
+ updated_at: now(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('id', '=', environmentRow.id)
+ .where('lifecycle_stage', '=', 'active')
+ .returningAll()
+ .executeTakeFirst();
+ if (!updated) {
+ throw new SandboxEnvironmentVersionConflictError(
+ { environment_id: environmentRow.id, version: versionWrite.version },
+ { cause: new Error('Sandbox environment disappeared during upsert') },
+ );
+ }
+ return { environment: toEnvironmentRecord(updated), version };
+ }
+
+ async markVersionActive(
+ input: MarkSandboxEnvironmentVersionActiveInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ if (transaction) {
+ return this.#markVersionActive(input, transaction);
+ }
+ return this.#db.transaction().execute(db => this.#markVersionActive(input, db));
+ }
+
+ async #markVersionActive(
+ input: MarkSandboxEnvironmentVersionActiveInput,
+ db: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ const versionRow = await db
+ .updateTable('sandbox_environment_version')
+ .set({
+ status: 'active',
+ status_reason: null,
+ updated_at: now(),
+ })
+ .where('environment_id', '=', input.environment_id)
+ .where('version', '=', input.version)
+ .returningAll()
+ .executeTakeFirst();
+ if (!versionRow) {
+ return undefined;
+ }
+ const parentUpdated = await db
+ .updateTable('sandbox_environment')
+ .set({
+ active_version: input.version,
+ updated_at: now(),
+ })
+ .where('id', '=', input.environment_id)
+ .where('lifecycle_stage', '=', 'active')
+ .executeTakeFirst();
+ if (!Number(parentUpdated.numUpdatedRows)) {
+ return undefined;
+ }
+ const row = await activeVersionJoin(db).where('env.id', '=', input.environment_id).executeTakeFirst();
+ return row ? toWithVersion(row) : undefined;
+ }
+
+ async markVersionFailed(
+ input: MarkSandboxEnvironmentVersionFailedInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentVersionRecord | undefined> {
+ const db = transaction ?? this.#db;
+ const row = await db
+ .updateTable('sandbox_environment_version')
+ .set({
+ status: 'failed',
+ status_reason: input.status_reason,
+ updated_at: now(),
+ })
+ .where('environment_id', '=', input.environment_id)
+ .where('version', '=', input.version)
+ .returningAll()
+ .executeTakeFirst();
+ return row ? toVersionRecord(row) : undefined;
+ }
+
+ async deleteEnvironment(input: DeleteSandboxEnvironmentInput, transaction?: Transaction<Database>): Promise<void> {
+ const db = transaction ?? this.#db;
+ await db
+ .updateTable('sandbox_environment')
+ .set({
+ lifecycle_stage: 'deleted',
+ updated_at: now(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('name', '=', input.name)
+ .where('lifecycle_stage', '=', 'active')
+ .where(sql`created_by_subject->>'subject_id'`, '=', input.created_by_subject_id)
+ .execute();
+ }
+
+ async #insertVersionRow(
+ db: Kysely<Database> | Transaction<Database>,
+ environment_id: string,
+ version: UpsertSandboxEnvironmentVersionWrite,
+ ): Promise<SandboxEnvironmentVersionRecord> {
+ try {
+ const row = await db
+ .insertInto('sandbox_environment_version')
+ .values({
+ id: newId(),
+ environment_id,
+ version: version.version,
+ manifest: json(version.manifest),
+ status: version.status,
+ status_reason: version.status_reason,
+ external_ref: version.external_ref,
+ internal_metadata: json(version.internal_metadata),
+ created_by_subject: json(version.created_by_subject),
+ created_at: now(),
+ updated_at: now(),
+ })
+ .returningAll()
+ .executeTakeFirstOrThrow();
+ return toVersionRecord(row);
+ } catch (error) {
+ if (isUniqueViolation(error) || isPgConstraint(error, SANDBOX_ENVIRONMENT_VERSION_UQ)) {
+ throw new SandboxEnvironmentVersionConflictError(
+ { environment_id, version: version.version },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+ }
+}
diff --git a/packages/trueforge/src/db/sandboxEnvironmentStore.ts b/packages/trueforge/src/db/sandboxEnvironmentStore.ts
new file mode 100644
index 000000000..5726c23d7
--- /dev/null
+++ b/packages/trueforge/src/db/sandboxEnvironmentStore.ts
@@ -0,0 +1,194 @@
+/**
+ * DB-backed sandbox environments: parent row + immutable version rows.
+ * Implementations: PostgresSandboxEnvironmentStore and SqliteSandboxEnvironmentStore.
+ */
+import type { CreatedBySubject, TokenPagination } from '@truefoundry/trueforge-core/agent-session';
+import type { NextSandboxEnvironmentVersion } from '../sandbox/sandboxEnvironmentVersion';
+import type { ResourceName } from '../schemas/common';
+import type {
+ SandboxEnvironmentLifecycleStage,
+ SandboxEnvironmentVersionInternalMetadata,
+ SandboxEnvironmentVersionStatus,
+ StoredSandboxEnvironmentManifest,
+} from '../schemas/sandboxEnvironment';
+import { StoredSandboxEnvironmentManifestSchema } from '../schemas/sandboxEnvironment';
+
+export interface SandboxEnvironmentRecord {
+ id: string;
+ tenant_id: string;
+ name: ResourceName;
+ description: string;
+ active_version: number;
+ lifecycle_stage: SandboxEnvironmentLifecycleStage;
+ created_by_subject: CreatedBySubject;
+ /** ISO-8601 UTC instant. */
+ created_at: string;
+ /** ISO-8601 UTC instant. */
+ updated_at: string;
+}
+
+export interface SandboxEnvironmentVersionRecord {
+ id: string;
+ environment_id: string;
+ version: number;
+ manifest: StoredSandboxEnvironmentManifest;
+ status: SandboxEnvironmentVersionStatus;
+ status_reason: string | null;
+ external_ref: string;
+ internal_metadata: SandboxEnvironmentVersionInternalMetadata;
+ created_by_subject: CreatedBySubject;
+ /** ISO-8601 UTC instant. */
+ created_at: string;
+ /** ISO-8601 UTC instant. */
+ updated_at: string;
+}
+
+/** Parent + its active version row (list/get join). */
+export interface SandboxEnvironmentWithVersion {
+ environment: SandboxEnvironmentRecord;
+ version: SandboxEnvironmentVersionRecord;
+}
+
+export function parseStoredSandboxEnvironmentManifest(manifest: unknown): StoredSandboxEnvironmentManifest {
+ return StoredSandboxEnvironmentManifestSchema.parse(manifest);
+}
+
+export interface ListSandboxEnvironmentsInput {
+ tenant_id: string;
+ /** Only environments created by this subject. */
+ created_by_subject_id: string;
+ limit: number | undefined;
+ page_token: string | undefined;
+}
+
+export interface GetSandboxEnvironmentInput {
+ tenant_id: string;
+ name: string;
+ /**
+ * When set (CRUD / agent attach), only return if this subject created the environment.
+ * Omit when resolving an env during agent execution: running the agent already
+ * implies access to its referenced sandbox environment, so ownership is not checked.
+ */
+ created_by_subject_id?: string;
+}
+
+/**
+ * Result of `buildVersion` during upsert — {@link NextSandboxEnvironmentVersion} plus subject.
+ */
+export type UpsertSandboxEnvironmentVersion = NextSandboxEnvironmentVersion & {
+ created_by_subject: CreatedBySubject;
+};
+
+/** Version row columns for insert (store fills `environment_id`). */
+export type UpsertSandboxEnvironmentVersionWrite = UpsertSandboxEnvironmentVersion;
+
+export function toUpsertSandboxEnvironmentVersionWrite(
+ built: UpsertSandboxEnvironmentVersion,
+): UpsertSandboxEnvironmentVersionWrite {
+ return built;
+}
+
+/** Latest version row when updating; omitted on first create. Used for numbering + secret/diff. */
+export interface UpsertSandboxEnvironmentPrevious {
+ latest_version: number;
+ previous_manifest: StoredSandboxEnvironmentManifest;
+ previous_external_ref: string;
+}
+
+export interface UpsertSandboxEnvironmentInput {
+ tenant_id: string;
+ name: ResourceName;
+ description: string;
+ created_by_subject: CreatedBySubject;
+ /**
+ * Called inside the write transaction. `previous` is set when updating an existing
+ * env (after the parent row is locked / re-read) so concurrent PUTs cannot collide
+ * on the next version number.
+ */
+ buildVersion: (previous?: UpsertSandboxEnvironmentPrevious) => UpsertSandboxEnvironmentVersion;
+}
+
+export interface MarkSandboxEnvironmentVersionActiveInput {
+ environment_id: string;
+ version: number;
+}
+
+export interface MarkSandboxEnvironmentVersionFailedInput {
+ environment_id: string;
+ version: number;
+ status_reason: string;
+}
+
+export interface DeleteSandboxEnvironmentInput {
+ tenant_id: string;
+ name: string;
+ /** Soft-delete only if created by this subject. */
+ created_by_subject_id: string;
+}
+
+/** Partial unique `(tenant_id, name) WHERE lifecycle_stage = 'active'` violation. */
+export class SandboxEnvironmentNameConflictError extends Error {
+ readonly tenant_id: string;
+ readonly environment_name: string;
+
+ constructor({ tenant_id, name }: { tenant_id: string; name: string }, options?: ErrorOptions) {
+ super(`Sandbox environment name already exists: ${name}`, options);
+ this.name = 'SandboxEnvironmentNameConflictError';
+ this.tenant_id = tenant_id;
+ this.environment_name = name;
+ }
+}
+
+/** Unique `(environment_id, version)` violation from concurrent updates. */
+export class SandboxEnvironmentVersionConflictError extends Error {
+ readonly environment_id: string;
+ readonly version: number;
+
+ constructor({ environment_id, version }: { environment_id: string; version: number }, options?: ErrorOptions) {
+ super(`Sandbox environment version conflict: ${environment_id}@${String(version)}`, options);
+ this.name = 'SandboxEnvironmentVersionConflictError';
+ this.environment_id = environment_id;
+ this.version = version;
+ }
+}
+
+export interface ISandboxEnvironmentStore<TTransaction = never> {
+ /** Active environments joined to the version pointed at by `active_version`. */
+ listEnvironments(
+ input: ListSandboxEnvironmentsInput,
+ transaction?: TTransaction,
+ ): Promise<{ data: SandboxEnvironmentWithVersion[]; pagination: TokenPagination }>;
+ /**
+ * Active environment by name, joined to its active version.
+ * Pass `created_by_subject_id` for owner-scoped CRUD/attach; omit it when an agent
+ * run resolves the env by name (caller already has access via the agent).
+ */
+ getEnvironment(
+ input: GetSandboxEnvironmentInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion | undefined>;
+ /**
+ * Create or replace by `(tenant_id, name)` for this subject — parent + new version row.
+ * On update, parent `active_version` advances only when the new version's status is
+ * `active` (otherwise use markVersionActive). Uses `transaction` when passed;
+ * otherwise opens its own (multi-write).
+ */
+ upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion>;
+ /**
+ * Set version status to `active` and point the parent `active_version` at it.
+ * No-op (returns undefined) if the version row is missing.
+ */
+ markVersionActive(
+ input: MarkSandboxEnvironmentVersionActiveInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion | undefined>;
+ markVersionFailed(
+ input: MarkSandboxEnvironmentVersionFailedInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentVersionRecord | undefined>;
+ /** Soft-delete: set lifecycle_stage = deleted. Idempotent if missing or already deleted. */
+ deleteEnvironment(input: DeleteSandboxEnvironmentInput, transaction?: TTransaction): Promise<void>;
+}
diff --git a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
index 27b1daa6a..535295865 100644
--- a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
+++ b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
@@ -22,6 +22,7 @@ import {
type GetExternalIdsByIdsInput,
type GetOwnedIdsInput,
type IAgentStore,
+ type ListAgentNamesUsingSandboxEnvironmentInput,
type ListAgentsInput,
type UpdateAgentInput,
} from '../../agentStore';
@@ -213,6 +214,21 @@ export class SqliteAgentStore implements IAgentStore<Transaction<Database>> {
await db.deleteFrom('agent').where('tenant_id', '=', input.tenant_id).where('id', '=', input.id).execute();
}
+ async listAgentNamesUsingSandboxEnvironment(
+ input: ListAgentNamesUsingSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<readonly string[]> {
+ const db = transaction ?? this.#db;
+ const rows = await db
+ .selectFrom('agent')
+ .select('name')
+ .where('tenant_id', '=', input.tenant_id)
+ .where(sql`json_extract(manifest, '$.config.sandbox.environment_name')`, '=', input.environment_name)
+ .orderBy('name', 'asc')
+ .execute();
+ return rows.map(row => row.name);
+ }
+
/** Map unique violations to external_id vs name conflicts. */
private async throwCreateUnique({
error,
diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.ts
index cb416bc18..ca5e07dd3 100644
--- a/packages/trueforge/src/db/sqlite/client.ts
+++ b/packages/trueforge/src/db/sqlite/client.ts
@@ -152,6 +152,10 @@ const JSON_RESULT_COLUMNS = new Set([
'auth_data',
'created_by_subject',
'source',
+ // sandbox_environment ↔ version join aliases
+ 'ver_manifest',
+ 'ver_internal_metadata',
+ 'ver_created_by_subject',
]);
/** Top-level row field only — `$[0]."body"`, not `$[0]."body"."content"`. */
diff --git a/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts b/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts
new file mode 100644
index 000000000..dc057fd2b
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts
@@ -0,0 +1,475 @@
+import {
+ CreatedBySubjectSchema,
+ type CreatedBySubject,
+ type TokenPagination,
+} from '@truefoundry/trueforge-core/agent-session';
+import {
+ decodeOffsetPageToken,
+ paginateOffsetRows,
+} from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
+import type { Kysely, Transaction } from 'kysely';
+import { sql } from 'kysely';
+import { NameSchema } from '../../../schemas/common';
+import {
+ SandboxEnvironmentVersionInternalMetadataSchema,
+ type SandboxEnvironmentVersionInternalMetadata,
+ type StoredSandboxEnvironmentManifest,
+} from '../../../schemas/sandboxEnvironment';
+import { newId } from '../../../utils/id';
+import {
+ parseStoredSandboxEnvironmentManifest,
+ SandboxEnvironmentNameConflictError,
+ SandboxEnvironmentVersionConflictError,
+ toUpsertSandboxEnvironmentVersionWrite,
+ type DeleteSandboxEnvironmentInput,
+ type GetSandboxEnvironmentInput,
+ type ISandboxEnvironmentStore,
+ type ListSandboxEnvironmentsInput,
+ type MarkSandboxEnvironmentVersionActiveInput,
+ type MarkSandboxEnvironmentVersionFailedInput,
+ type SandboxEnvironmentRecord,
+ type SandboxEnvironmentVersionRecord,
+ type SandboxEnvironmentWithVersion,
+ type UpsertSandboxEnvironmentInput,
+ type UpsertSandboxEnvironmentVersionWrite,
+} from '../../sandboxEnvironmentStore';
+import { isUniqueViolation } from '../client';
+import { jsonbBind, jsonText, nowIso } from '../sqlExpressions';
+import type { Database } from '../types';
+
+function activeVersionJoin(db: Kysely<Database> | Transaction<Database>) {
+ return db
+ .selectFrom('sandbox_environment as env')
+ .innerJoin('sandbox_environment_version as ver', join =>
+ join.onRef('ver.environment_id', '=', 'env.id').onRef('ver.version', '=', 'env.active_version'),
+ )
+ .select([
+ 'env.id',
+ 'env.tenant_id',
+ 'env.name',
+ 'env.description',
+ 'env.active_version',
+ 'env.lifecycle_stage',
+ jsonText<CreatedBySubject>(sql.ref('env.created_by_subject')).as('created_by_subject'),
+ 'env.created_at',
+ 'env.updated_at',
+ 'ver.id as ver_id',
+ 'ver.environment_id as ver_environment_id',
+ 'ver.version as ver_version',
+ jsonText<StoredSandboxEnvironmentManifest>(sql.ref('ver.manifest')).as('ver_manifest'),
+ 'ver.status as ver_status',
+ 'ver.status_reason as ver_status_reason',
+ 'ver.external_ref as ver_external_ref',
+ jsonText<SandboxEnvironmentVersionInternalMetadata>(sql.ref('ver.internal_metadata')).as('ver_internal_metadata'),
+ jsonText<CreatedBySubject>(sql.ref('ver.created_by_subject')).as('ver_created_by_subject'),
+ 'ver.created_at as ver_created_at',
+ 'ver.updated_at as ver_updated_at',
+ ]);
+}
+
+function versionSelect() {
+ return [
+ 'id' as const,
+ 'environment_id' as const,
+ 'version' as const,
+ jsonText<StoredSandboxEnvironmentManifest>(sql.ref('manifest')).as('manifest'),
+ 'status' as const,
+ 'status_reason' as const,
+ 'external_ref' as const,
+ jsonText<SandboxEnvironmentVersionInternalMetadata>(sql.ref('internal_metadata')).as('internal_metadata'),
+ jsonText<CreatedBySubject>(sql.ref('created_by_subject')).as('created_by_subject'),
+ 'created_at' as const,
+ 'updated_at' as const,
+ ];
+}
+
+function toEnvironmentRecord(row: {
+ id: string;
+ tenant_id: string;
+ name: string;
+ description: string;
+ active_version: number;
+ lifecycle_stage: SandboxEnvironmentRecord['lifecycle_stage'];
+ created_by_subject: CreatedBySubject;
+ created_at: string;
+ updated_at: string;
+}): SandboxEnvironmentRecord {
+ return {
+ id: row.id,
+ tenant_id: row.tenant_id,
+ name: NameSchema.parse(row.name),
+ description: row.description,
+ active_version: row.active_version,
+ lifecycle_stage: row.lifecycle_stage,
+ created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
+ created_at: row.created_at,
+ updated_at: row.updated_at,
+ };
+}
+
+function toVersionRecord(row: {
+ id: string;
+ environment_id: string;
+ version: number;
+ manifest: StoredSandboxEnvironmentManifest;
+ status: SandboxEnvironmentVersionRecord['status'];
+ status_reason: string | null;
+ external_ref: string;
+ internal_metadata: SandboxEnvironmentVersionInternalMetadata;
+ created_by_subject: CreatedBySubject;
+ created_at: string;
+ updated_at: string;
+}): SandboxEnvironmentVersionRecord {
+ return {
+ id: row.id,
+ environment_id: row.environment_id,
+ version: row.version,
+ manifest: parseStoredSandboxEnvironmentManifest(row.manifest),
+ status: row.status,
+ status_reason: row.status_reason,
+ external_ref: row.external_ref,
+ internal_metadata: SandboxEnvironmentVersionInternalMetadataSchema.parse(row.internal_metadata),
+ created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
+ created_at: row.created_at,
+ updated_at: row.updated_at,
+ };
+}
+
+function toWithVersion(row: {
+ id: string;
+ tenant_id: string;
+ name: string;
+ description: string;
+ active_version: number;
+ lifecycle_stage: SandboxEnvironmentRecord['lifecycle_stage'];
+ created_by_subject: CreatedBySubject;
+ created_at: string;
+ updated_at: string;
+ ver_id: string;
+ ver_environment_id: string;
+ ver_version: number;
+ ver_manifest: StoredSandboxEnvironmentManifest;
+ ver_status: SandboxEnvironmentVersionRecord['status'];
+ ver_status_reason: string | null;
+ ver_external_ref: string;
+ ver_internal_metadata: SandboxEnvironmentVersionInternalMetadata;
+ ver_created_by_subject: CreatedBySubject;
+ ver_created_at: string;
+ ver_updated_at: string;
+}): SandboxEnvironmentWithVersion {
+ return {
+ environment: toEnvironmentRecord(row),
+ version: toVersionRecord({
+ id: row.ver_id,
+ environment_id: row.ver_environment_id,
+ version: row.ver_version,
+ manifest: row.ver_manifest,
+ status: row.ver_status,
+ status_reason: row.ver_status_reason,
+ external_ref: row.ver_external_ref,
+ internal_metadata: row.ver_internal_metadata,
+ created_by_subject: row.ver_created_by_subject,
+ created_at: row.ver_created_at,
+ updated_at: row.ver_updated_at,
+ }),
+ };
+}
+
+export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<Transaction<Database>> {
+ readonly #db: Kysely<Database>;
+
+ constructor(db: Kysely<Database>) {
+ this.#db = db;
+ }
+
+ async listEnvironments(
+ input: ListSandboxEnvironmentsInput,
+ transaction?: Transaction<Database>,
+ ): Promise<{ data: SandboxEnvironmentWithVersion[]; pagination: TokenPagination }> {
+ const db = transaction ?? this.#db;
+ const query = activeVersionJoin(db)
+ .where('env.tenant_id', '=', input.tenant_id)
+ .where('env.lifecycle_stage', '=', 'active')
+ .where(sql`json_extract(env.created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id)
+ .orderBy('env.name');
+ if (!input.limit) {
+ const rows = await query.execute();
+ return { data: rows.map(toWithVersion), pagination: { limit: rows.length } };
+ }
+ const offset = decodeOffsetPageToken(input.page_token);
+ const rows = await query
+ .limit(input.limit + 1)
+ .offset(offset)
+ .execute();
+ const { data, pagination } = paginateOffsetRows(rows, input.limit, offset);
+ return { data: data.map(toWithVersion), pagination };
+ }
+
+ async getEnvironment(
+ input: GetSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ const db = transaction ?? this.#db;
+ let query = activeVersionJoin(db)
+ .where('env.tenant_id', '=', input.tenant_id)
+ .where('env.name', '=', input.name)
+ .where('env.lifecycle_stage', '=', 'active');
+ if (input.created_by_subject_id) {
+ query = query.where(sql`json_extract(env.created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id);
+ }
+ const row = await query.executeTakeFirst();
+ return row ? toWithVersion(row) : undefined;
+ }
+
+ async upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion> {
+ if (transaction) {
+ return this.#upsertEnvironment(input, transaction);
+ }
+ return this.#db.transaction().execute(db => this.#upsertEnvironment(input, db));
+ }
+
+ async #upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ db: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion> {
+ const environmentRow = await db
+ .selectFrom('sandbox_environment')
+ .select([
+ 'id',
+ 'tenant_id',
+ 'name',
+ 'description',
+ 'active_version',
+ 'lifecycle_stage',
+ jsonText<CreatedBySubject>(sql.ref('created_by_subject')).as('created_by_subject'),
+ 'created_at',
+ 'updated_at',
+ ])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('name', '=', input.name)
+ .where('lifecycle_stage', '=', 'active')
+ .where(sql`json_extract(created_by_subject, '$.subject_id')`, '=', input.created_by_subject.subject_id)
+ .executeTakeFirst();
+
+ if (!environmentRow) {
+ const environment_id = newId();
+ const versionWrite = toUpsertSandboxEnvironmentVersionWrite(input.buildVersion());
+ const created_at = nowIso();
+ // First version: point here so get/list join works; later versions only move the
+ // pointer when their status is (or becomes) active.
+ const active_version = versionWrite.version;
+ try {
+ await db
+ .insertInto('sandbox_environment')
+ .values({
+ id: environment_id,
+ tenant_id: input.tenant_id,
+ name: input.name,
+ description: input.description,
+ active_version,
+ lifecycle_stage: 'active',
+ created_by_subject: jsonbBind(input.created_by_subject),
+ created_at,
+ updated_at: created_at,
+ })
+ .execute();
+ } catch (error) {
+ if (isUniqueViolation(error)) {
+ throw new SandboxEnvironmentNameConflictError(
+ { tenant_id: input.tenant_id, name: input.name },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+ const version = await this.#insertVersionRow(db, environment_id, versionWrite);
+ return {
+ environment: {
+ id: environment_id,
+ tenant_id: input.tenant_id,
+ name: input.name,
+ description: input.description,
+ active_version,
+ lifecycle_stage: 'active',
+ created_by_subject: input.created_by_subject,
+ created_at,
+ updated_at: created_at,
+ },
+ version,
+ };
+ }
+
+ const previousVersion = await db
+ .selectFrom('sandbox_environment_version')
+ .select(versionSelect())
+ .where('environment_id', '=', environmentRow.id)
+ .orderBy('version', 'desc')
+ .executeTakeFirstOrThrow();
+ const versionWrite = toUpsertSandboxEnvironmentVersionWrite(
+ input.buildVersion({
+ latest_version: previousVersion.version,
+ previous_manifest: parseStoredSandboxEnvironmentManifest(previousVersion.manifest),
+ previous_external_ref: previousVersion.external_ref,
+ }),
+ );
+ const version = await this.#insertVersionRow(db, environmentRow.id, versionWrite);
+ const updated_at = nowIso();
+ const nextActiveVersion = versionWrite.status === 'active' ? versionWrite.version : environmentRow.active_version;
+ const result = await db
+ .updateTable('sandbox_environment')
+ .set({
+ ...(versionWrite.status === 'active' ? { active_version: versionWrite.version } : {}),
+ description: input.description,
+ updated_at,
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('id', '=', environmentRow.id)
+ .where('lifecycle_stage', '=', 'active')
+ .executeTakeFirst();
+ if (!Number(result.numUpdatedRows)) {
+ throw new SandboxEnvironmentVersionConflictError(
+ { environment_id: environmentRow.id, version: versionWrite.version },
+ { cause: new Error('Sandbox environment disappeared during upsert') },
+ );
+ }
+ return {
+ environment: toEnvironmentRecord({
+ ...environmentRow,
+ description: input.description,
+ active_version: nextActiveVersion,
+ updated_at,
+ }),
+ version,
+ };
+ }
+
+ async markVersionActive(
+ input: MarkSandboxEnvironmentVersionActiveInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ if (transaction) {
+ return this.#markVersionActive(input, transaction);
+ }
+ return this.#db.transaction().execute(db => this.#markVersionActive(input, db));
+ }
+
+ async #markVersionActive(
+ input: MarkSandboxEnvironmentVersionActiveInput,
+ db: Transaction<Database>,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ const updated_at = nowIso();
+ const versionResult = await db
+ .updateTable('sandbox_environment_version')
+ .set({
+ status: 'active',
+ status_reason: null,
+ updated_at,
+ })
+ .where('environment_id', '=', input.environment_id)
+ .where('version', '=', input.version)
+ .executeTakeFirst();
+ if (!Number(versionResult.numUpdatedRows)) {
+ return undefined;
+ }
+ const parentResult = await db
+ .updateTable('sandbox_environment')
+ .set({
+ active_version: input.version,
+ updated_at,
+ })
+ .where('id', '=', input.environment_id)
+ .where('lifecycle_stage', '=', 'active')
+ .executeTakeFirst();
+ if (!Number(parentResult.numUpdatedRows)) {
+ return undefined;
+ }
+ const row = await activeVersionJoin(db).where('env.id', '=', input.environment_id).executeTakeFirst();
+ return row ? toWithVersion(row) : undefined;
+ }
+
+ async markVersionFailed(
+ input: MarkSandboxEnvironmentVersionFailedInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentVersionRecord | undefined> {
+ const db = transaction ?? this.#db;
+ const result = await db
+ .updateTable('sandbox_environment_version')
+ .set({
+ status: 'failed',
+ status_reason: input.status_reason,
+ updated_at: nowIso(),
+ })
+ .where('environment_id', '=', input.environment_id)
+ .where('version', '=', input.version)
+ .executeTakeFirst();
+ if (!Number(result.numUpdatedRows)) {
+ return undefined;
+ }
+ const row = await db
+ .selectFrom('sandbox_environment_version')
+ .select(versionSelect())
+ .where('environment_id', '=', input.environment_id)
+ .where('version', '=', input.version)
+ .executeTakeFirst();
+ return row ? toVersionRecord(row) : undefined;
+ }
+
+ async deleteEnvironment(input: DeleteSandboxEnvironmentInput, transaction?: Transaction<Database>): Promise<void> {
+ const db = transaction ?? this.#db;
+ await db
+ .updateTable('sandbox_environment')
+ .set({
+ lifecycle_stage: 'deleted',
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('name', '=', input.name)
+ .where('lifecycle_stage', '=', 'active')
+ .where(sql`json_extract(created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id)
+ .execute();
+ }
+
+ async #insertVersionRow(
+ db: Kysely<Database> | Transaction<Database>,
+ environment_id: string,
+ version: UpsertSandboxEnvironmentVersionWrite,
+ ): Promise<SandboxEnvironmentVersionRecord> {
+ const id = newId();
+ const created_at = nowIso();
+ try {
+ await db
+ .insertInto('sandbox_environment_version')
+ .values({
+ id,
+ environment_id,
+ version: version.version,
+ manifest: jsonbBind(version.manifest),
+ status: version.status,
+ status_reason: version.status_reason,
+ external_ref: version.external_ref,
+ internal_metadata: jsonbBind(version.internal_metadata),
+ created_by_subject: jsonbBind(version.created_by_subject),
+ created_at,
+ updated_at: created_at,
+ })
+ .execute();
+ } catch (error) {
+ if (isUniqueViolation(error)) {
+ throw new SandboxEnvironmentVersionConflictError(
+ { environment_id, version: version.version },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+ const row = await db
+ .selectFrom('sandbox_environment_version')
+ .select(versionSelect())
+ .where('id', '=', id)
+ .executeTakeFirstOrThrow();
+ return toVersionRecord(row);
+ }
+}
diff --git a/packages/trueforge/src/main.ts b/packages/trueforge/src/main.ts
index fe9924aa2..56ca1acfb 100644
--- a/packages/trueforge/src/main.ts
+++ b/packages/trueforge/src/main.ts
@@ -78,6 +78,7 @@ import { McpServerWithAuthStore } from './db/McpServerWithAuthStore';
import type { IModelProviderStore } from './db/modelProviderStore';
import type { PostgresAgentStore } from './db/postgres/agent-store/PostgresAgentStore';
import type { Database as PostgresDatabase } from './db/postgres/types';
+import type { ISandboxEnvironmentStore } from './db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from './db/sandboxProviderStore';
import type { IScheduleStore } from './db/scheduleStore';
import type { ISessionMetricsStore } from './db/sessionMetricsStore';
@@ -143,6 +144,7 @@ interface ServerPersistence<TTransaction> {
resolveImportAgentStore: (serviceFoundryServerHeaders: Record<string, string>) => IAgentStore<TTransaction>;
/** extra pre-resolved stores for scheduled runs */
agentStore: IAgentStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
turnSkillsResolverStore: Pick<ISkillStore<TTransaction>, 'resolveTurnSkills'>;
destroyDb: () => Promise<void>;
/** Connected Redis (client + mode) for distributed peering; undefined in standalone. */
@@ -324,6 +326,7 @@ async function createStandalonePersistence(options: {
import('./db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore'),
import('./db/sqlite/agent-store/SqliteAgentStore'),
import('./db/sqlite/schedule-store/SqliteScheduleStore'),
+ import('./db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore'),
]),
]);
const [
@@ -337,6 +340,7 @@ async function createStandalonePersistence(options: {
{ SqliteWebSearchProviderStore },
{ SqliteAgentStore },
{ SqliteScheduleStore },
+ { SqliteSandboxEnvironmentStore },
] = sqliteStores;
const db = createSqliteDb(sqlitePath);
@@ -346,6 +350,7 @@ async function createStandalonePersistence(options: {
const tokenStore = new SqliteOAuthTokenStore(db);
const agentStore = new SqliteAgentStore(db);
+ const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
const modelProviderStore = new SqliteModelProviderStore(db);
const mcpServerStore = new McpServerWithAuthStore({
store: new SqliteMcpServerStore(db),
@@ -370,6 +375,7 @@ async function createStandalonePersistence(options: {
resolveAgentStore: () => agentStore,
resolveImportAgentStore: () => agentStore,
agentStore,
+ sandboxEnvironmentStore,
turnSkillsResolverStore: skillStore,
destroyDb: () => db.destroy(),
redis: undefined,
@@ -417,6 +423,7 @@ async function createDistributedPersistence(options: {
import('./db/postgres/web-search-provider-store/PostgresWebSearchProviderStore'),
import('./db/postgres/agent-store/PostgresAgentStore'),
import('./db/postgres/schedule-store/PostgresScheduleStore'),
+ import('./db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore'),
]),
]);
const [
@@ -430,6 +437,7 @@ async function createDistributedPersistence(options: {
{ PostgresWebSearchProviderStore },
{ PostgresAgentStore },
{ PostgresScheduleStore },
+ { PostgresSandboxEnvironmentStore },
] = postgresStores;
logger.info('Connecting to Postgres');
@@ -461,6 +469,7 @@ async function createDistributedPersistence(options: {
const webSearchProviderStore = new PostgresWebSearchProviderStore(db);
const skillStore = new PostgresSkillStore(db);
const agentStore = new PostgresAgentStore(db);
+ const sandboxEnvironmentStore = new PostgresSandboxEnvironmentStore(db);
const turnSkillsResolverStore = buildTurnSkillsResolverStore({
persistenceStore: skillStore,
client: serviceFoundryClient,
@@ -525,6 +534,7 @@ async function createDistributedPersistence(options: {
resolveAgentStore,
resolveImportAgentStore,
agentStore,
+ sandboxEnvironmentStore,
turnSkillsResolverStore,
destroyDb: () => db.destroy(),
redis: await connectRedis({
@@ -557,6 +567,7 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
mcpOAuthStore,
resolveImportAgentStore,
agentStore,
+ sandboxEnvironmentStore,
turnSkillsResolverStore,
destroyDb,
redis,
@@ -669,6 +680,7 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
tokenStore,
scheduleStore,
agentStore,
+ sandboxEnvironmentStore,
turnSkillsResolverStore,
sessionStore,
sessionMetricsStore,
diff --git a/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts b/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts
new file mode 100644
index 000000000..48a930c3a
--- /dev/null
+++ b/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts
@@ -0,0 +1,157 @@
+/**
+ * Sandbox environment route definitions (mounted at /api/v1/sandbox-environments).
+ * Handlers are registered in apis/sandboxEnvironments.ts.
+ */
+import { createRoute, z } from '@hono/zod-openapi';
+import { NameSchema, PAGE_LIMIT } from '../schemas/common';
+import { RequestErrorResponseSchema } from '../schemas/errors';
+import {
+ DeleteSandboxEnvironmentResponseSchema,
+ GetSandboxEnvironmentResponseSchema,
+ ListSandboxEnvironmentsResponseSchema,
+ UpdateSandboxEnvironmentRequestSchema,
+} from '../schemas/sandboxEnvironment';
+import { TOKEN_PAGINATION } from './fernExtensions';
+import { OpenApiTag } from './openapiTags';
+
+const SandboxEnvironmentNameParamsSchema = z.object({
+ name: NameSchema.describe('Sandbox environment name.'),
+});
+
+export const ListSandboxEnvironmentsQuerySchema = z
+ .object({
+ limit: z.coerce
+ .number()
+ .int()
+ .min(1)
+ .max(PAGE_LIMIT)
+ .optional()
+ .default(PAGE_LIMIT)
+ .describe(`Page size. Defaults to ${String(PAGE_LIMIT)}`),
+ page_token: z.string().optional().describe('Opaque token from a previous response `next_page_token`.'),
+ })
+ .openapi('ListSandboxEnvironmentsQuery');
+
+export const listSandboxEnvironmentsRoute = createRoute({
+ method: 'get',
+ path: '/',
+ tags: [OpenApiTag.SANDBOXES],
+ summary: 'List sandbox environments',
+ description: 'List sandbox environments created by the authenticated subject, newest first.',
+ 'x-fern-sdk-group-name': ['sandboxEnvironments'],
+ 'x-fern-sdk-method-name': 'list',
+ 'x-fern-pagination': TOKEN_PAGINATION,
+ request: {
+ query: ListSandboxEnvironmentsQuerySchema,
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: ListSandboxEnvironmentsResponseSchema } },
+ description: 'Paginated sandbox environments.',
+ },
+ 400: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Invalid query parameters or page token.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unauthenticated.',
+ },
+ },
+});
+
+export const getSandboxEnvironmentRoute = createRoute({
+ method: 'get',
+ path: '/{name}',
+ tags: [OpenApiTag.SANDBOXES],
+ summary: 'Get a sandbox environment',
+ description: 'Get a sandbox environment by name for the authenticated subject.',
+ 'x-fern-sdk-group-name': ['sandboxEnvironments'],
+ 'x-fern-sdk-method-name': 'get',
+ request: {
+ params: SandboxEnvironmentNameParamsSchema,
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: GetSandboxEnvironmentResponseSchema } },
+ description: 'The sandbox environment.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unauthenticated.',
+ },
+ 404: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Sandbox environment not found.',
+ },
+ },
+});
+
+export const putSandboxEnvironmentRoute = createRoute({
+ method: 'put',
+ path: '/',
+ tags: [OpenApiTag.SANDBOXES],
+ summary: 'Create or update a sandbox environment',
+ description: 'Create or replace by `manifest.name`. Requires a Daytona sandbox provider.',
+ 'x-fern-sdk-group-name': ['sandboxEnvironments'],
+ 'x-fern-sdk-method-name': 'create_or_update',
+ request: {
+ body: {
+ content: { 'application/json': { schema: UpdateSandboxEnvironmentRequestSchema } },
+ required: true,
+ },
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: GetSandboxEnvironmentResponseSchema } },
+ description: 'The saved sandbox environment.',
+ },
+ 400: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Invalid request body, or missing secret value.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unauthenticated.',
+ },
+ 409: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Name conflict or concurrent update.',
+ },
+ 422: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'No Daytona sandbox provider configured.',
+ },
+ },
+});
+
+export const deleteSandboxEnvironmentRoute = createRoute({
+ method: 'delete',
+ path: '/{name}',
+ tags: [OpenApiTag.SANDBOXES],
+ summary: 'Delete a sandbox environment',
+ description: 'Delete by name. Fails if any agent still references the environment.',
+ 'x-fern-sdk-group-name': ['sandboxEnvironments'],
+ 'x-fern-sdk-method-name': 'delete',
+ request: {
+ params: SandboxEnvironmentNameParamsSchema,
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: DeleteSandboxEnvironmentResponseSchema } },
+ description: 'Sandbox environment deleted.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unauthenticated.',
+ },
+ 404: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Sandbox environment not found.',
+ },
+ 409: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Environment is referenced by one or more agents.',
+ },
+ },
+});
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index dd2f6b7a6..1ee7b9fc7 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -16,13 +16,14 @@ import type { Logger } from 'winston';
import configuration from '../config';
import type { IMcpServerStore, IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import type { ISkillStore } from '../db/skillStore';
import type { TurnMetadata } from '../db/turnMetadata';
import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';
import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProvider';
import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
-import { toSandboxProviderFromRecord } from '../sandbox/providerUtils';
+import { toDaytonaSandboxProvider, toSandboxProviderFromRecord } from '../sandbox/providerUtils';
import type { ReasoningEffort } from '../schemas/modelProvider';
import { hasConfiguredWebSearchProvider } from '../websearch/providers';
@@ -140,6 +141,13 @@ export async function getMcpConnection({
* Build a runtime SandboxProvider from the configured store row, or the
* in-memory local fallback when standalone + the cached probe is supported.
* Builds a fresh provider client per call (no network I/O).
+ *
+ * When `environment_name` is set (and not the reserved `default`), loads that
+ * sandbox environment by tenant + name (must be `active`) — no subject ownership
+ * check so anyone who can run the agent can use its env. `default` falls through
+ * to the tenant provider. Env create overlays use Daytona only (switch on
+ * provider type). For `image.type === 'build'` pins the snapshot to the
+ * environment version `external_ref`.
*/
/** Single path segment under the sandboxes parent (`_` when sessionId is missing or unsafe). */
export function localSandboxSessionSegment(sessionId: string | undefined): string {
@@ -149,20 +157,83 @@ export function localSandboxSessionSegment(sessionId: string | undefined): strin
return sessionId;
}
+export interface ResolvedSandboxProvider {
+ provider: SandboxProvider;
+ /**
+ * True when cloning an environment's built snapshot (`external_ref`).
+ * Callers should skip the tenant provider release-snapshot readiness check.
+ */
+ usesEnvironmentSnapshot: boolean;
+}
+
export async function resolveSandboxProvider({
tenant_id,
store,
logger,
sessionId,
+ environment_name,
+ sandboxEnvironmentStore,
}: {
tenant_id: string;
store: ISandboxProviderStore;
logger: Logger;
sessionId: string;
-}): Promise<SandboxProvider | undefined> {
+ environment_name: string | undefined;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
+}): Promise<ResolvedSandboxProvider | undefined> {
const record = await store.getSandboxProvider(tenant_id);
+
+ // Reserved `default` means the tenant sandbox provider (no env overlay).
+ if (environment_name && environment_name !== 'default') {
+ const loaded = await sandboxEnvironmentStore.getEnvironment({
+ tenant_id,
+ name: environment_name,
+ });
+ if (loaded === undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown sandbox environment "${environment_name}" — not configured`,
+ });
+ }
+ if (loaded.version.status !== 'active') {
+ throw new HTTPException(422, {
+ message:
+ loaded.version.status === 'failed'
+ ? `Sandbox environment "${environment_name}" build failed (${loaded.version.status_reason ?? 'unknown error'})`
+ : `Sandbox environment "${environment_name}" is not ready (status: ${loaded.version.status}) — retry shortly`,
+ });
+ }
+ if (record === undefined) {
+ throw new HTTPException(422, {
+ message: `Sandbox environment "${environment_name}" requires a sandbox provider — configure via PUT /settings/sandbox-providers`,
+ });
+ }
+ const usesEnvironmentSnapshot = loaded.version.manifest.image?.type === 'build';
+ switch (record.manifest.type) {
+ case 'daytona':
+ return {
+ provider: toDaytonaSandboxProvider({
+ manifest: record.manifest,
+ tenant_id,
+ logger,
+ build_metadata: usesEnvironmentSnapshot
+ ? { build_ref: loaded.version.external_ref }
+ : record.build_metadata,
+ environment: loaded.version.manifest,
+ }),
+ usesEnvironmentSnapshot,
+ };
+ default:
+ throw new HTTPException(422, {
+ message: `Sandbox environment "${environment_name}" requires a Daytona sandbox provider (configured provider type: "${record.manifest.type}")`,
+ });
+ }
+ }
+
if (record !== undefined) {
- return toSandboxProviderFromRecord({ record, tenant_id, logger });
+ return {
+ provider: toSandboxProviderFromRecord({ record, tenant_id, logger }),
+ usesEnvironmentSnapshot: false,
+ };
}
if (!configuration.STANDALONE) {
return undefined;
@@ -171,13 +242,16 @@ export async function resolveSandboxProvider({
if (support?.supported !== true) {
return undefined;
}
- return new LocalSandboxProvider({
- sandboxRootPathParent: join(configuration.LOCAL_SANDBOX_ROOT_PARENT, localSandboxSessionSegment(sessionId)),
- codeModeSocketParentPath: configuration.CODE_MODE_SOCKET_PARENT,
- support,
- fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
- logger,
- });
+ return {
+ provider: new LocalSandboxProvider({
+ sandboxRootPathParent: join(configuration.LOCAL_SANDBOX_ROOT_PARENT, localSandboxSessionSegment(sessionId)),
+ codeModeSocketParentPath: configuration.CODE_MODE_SOCKET_PARENT,
+ support,
+ fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
+ logger,
+ }),
+ usesEnvironmentSnapshot: false,
+ };
}
/**
@@ -213,18 +287,22 @@ export function buildTurnSandbox(input: {
export async function validateAgentSpec({
spec,
tenant_id,
+ created_by_subject_id,
modelProviderStore,
mcpServerStore,
skillStore,
sandboxProviderStore,
+ sandboxEnvironmentStore,
webSearchProviderStore,
}: {
spec: AgentSpec;
tenant_id: string;
+ created_by_subject_id: string;
modelProviderStore: IModelProviderStore;
mcpServerStore: IMcpServerStore;
skillStore: ISkillStore;
sandboxProviderStore: ISandboxProviderStore;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
webSearchProviderStore: IWebSearchProviderStore;
}): Promise<void> {
const resolved = await getModelDetails({
@@ -281,6 +359,20 @@ export async function validateAgentSpec({
}
}
+ const environmentName = spec.config.sandbox.environment_name;
+ if (environmentName) {
+ const environment = await sandboxEnvironmentStore.getEnvironment({
+ tenant_id,
+ name: environmentName,
+ created_by_subject_id,
+ });
+ if (environment === undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown sandbox environment "${environmentName}" — not configured`,
+ });
+ }
+ }
+
if (spec.config.web_search.enabled) {
const hasProvider = await hasConfiguredWebSearchProvider({ tenant_id, store: webSearchProviderStore });
if (!hasProvider) {
diff --git a/packages/trueforge/src/sandbox/providerUtils.ts b/packages/trueforge/src/sandbox/providerUtils.ts
index f65f99350..a75b2a0a4 100644
--- a/packages/trueforge/src/sandbox/providerUtils.ts
+++ b/packages/trueforge/src/sandbox/providerUtils.ts
@@ -6,11 +6,13 @@ import {
TFYSandboxProvider,
withTimeout,
type SandboxBuild,
+ type SandboxEnvironment,
type SandboxProvider,
} from '@truefoundry/trueforge-core/core';
import type { Logger } from 'winston';
import configuration from '../config';
import type { ISandboxProviderStore, SandboxProviderRecord } from '../db/sandboxProviderStore';
+import type { SandboxEnvironmentManifest } from '../schemas/sandboxEnvironment';
import {
toDaytonaSandboxProviderInput,
type SandboxBuildMetadata,
@@ -27,6 +29,28 @@ export function isDaytonaPermissionError(error: unknown): boolean {
return error instanceof DaytonaError && error.statusCode === 403;
}
+/** Map host sandbox-environment manifest onto the Daytona provider environment. */
+export function toDaytonaSandboxEnvironment(manifest: SandboxEnvironmentManifest): SandboxEnvironment {
+ return {
+ resources: manifest.resources,
+ ...(manifest.image ? { image: manifest.image } : {}),
+ ...(manifest.environment_variables ? { environment_variables: manifest.environment_variables } : {}),
+ ...(manifest.networking
+ ? {
+ networking: {
+ ...(manifest.networking.network_block_all
+ ? { network_block_all: manifest.networking.network_block_all }
+ : {}),
+ ...(manifest.networking.domain_allow_list
+ ? { domain_allow_list: manifest.networking.domain_allow_list }
+ : {}),
+ ...(manifest.networking.secrets ? { secrets: manifest.networking.secrets } : {}),
+ },
+ }
+ : {}),
+ };
+}
+
/**
* Builds the Daytona runtime provider for a stored Daytona manifest. No network I/O until a method is called.
*
@@ -40,11 +64,13 @@ export function toDaytonaSandboxProvider({
tenant_id,
logger,
build_metadata,
+ environment,
}: {
manifest: SandboxProviderManifest;
tenant_id: string;
logger: Logger;
build_metadata?: SandboxBuildMetadata | null;
+ environment?: SandboxEnvironmentManifest;
}): DaytonaSandboxProvider {
const { apiKey, ...settings } = toDaytonaSandboxProviderInput(manifest);
return new DaytonaSandboxProvider({
@@ -55,6 +81,7 @@ export function toDaytonaSandboxProvider({
sandboxImage: build_metadata?.['image_uri'] ?? SANDBOX_IMAGE_URI,
buildRef: build_metadata?.['build_ref'],
fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
+ ...(environment ? { environment: toDaytonaSandboxEnvironment(environment) } : {}),
logger,
});
}
@@ -62,14 +89,19 @@ export function toDaytonaSandboxProvider({
/**
* Builds the runtime SandboxProvider for a store record. One switch on `manifest.type`.
* No network I/O until a provider method is called.
+ *
+ * Optional `build_metadata` overrides the record's persisted metadata (e.g. env-version
+ * snapshot `build_ref`); ignored for non-Daytona providers.
*/
export function toSandboxProviderFromRecord({
record,
tenant_id,
logger,
+ build_metadata,
}: {
record: SandboxProviderRecord;
tenant_id: string;
+ build_metadata?: SandboxBuildMetadata | null;
logger: Logger;
}): SandboxProvider {
switch (record.manifest.type) {
@@ -78,7 +110,7 @@ export function toSandboxProviderFromRecord({
manifest: record.manifest,
tenant_id,
logger,
- build_metadata: record.build_metadata,
+ build_metadata: build_metadata ?? record.build_metadata,
});
case 'truefoundry':
return new TFYSandboxProvider({
diff --git a/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts b/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts
new file mode 100644
index 000000000..472b898b5
--- /dev/null
+++ b/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts
@@ -0,0 +1,148 @@
+/**
+ * Versioning helpers for sandbox environments: stored manifest shape, diff,
+ * and buildNextVersion (no DB writes — store create/update persist the row).
+ */
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import {
+ SandboxEnvironmentVersionInternalMetadataSchema,
+ type SandboxEnvironmentManifest,
+ type SandboxEnvironmentVersionInternalMetadata,
+ type SandboxEnvironmentVersionStatus,
+ type StoredSandboxEnvironmentManifest,
+} from '../schemas/sandboxEnvironment';
+import { isRedactedSecretValue, resolveStoredSecretValue, toRedactedSecretValue } from '../utils/secretRedaction';
+
+export type SandboxEnvironmentProviderType = StoredSandboxEnvironmentManifest['type'];
+
+export interface ManifestDiff {
+ build_changed: boolean;
+ resources_changed: boolean;
+ /** Request includes at least one non-redacted secret value (new material to sync). */
+ secrets_changed: boolean;
+}
+
+/** Next version row fields (status/external_ref encode whether a future controller must build). */
+export interface NextSandboxEnvironmentVersion {
+ version: number;
+ manifest: StoredSandboxEnvironmentManifest;
+ status: SandboxEnvironmentVersionStatus;
+ status_reason: null;
+ external_ref: string;
+ internal_metadata: SandboxEnvironmentVersionInternalMetadata;
+}
+
+/** Merge redacted keep-as-is stand-ins with previously stored secret values (sandbox-provider style). */
+export function resolveManifestSecrets({
+ manifest,
+ previous,
+}: {
+ manifest: SandboxEnvironmentManifest;
+ previous?: StoredSandboxEnvironmentManifest;
+}): SandboxEnvironmentManifest {
+ const secrets = manifest.networking?.secrets;
+ if (!secrets) {
+ return manifest;
+ }
+ const previousByEnv = new Map((previous?.networking?.secrets ?? []).map(secret => [secret.env, secret.value]));
+ return {
+ ...manifest,
+ networking: {
+ ...manifest.networking,
+ secrets: secrets.map(secret => ({
+ ...secret,
+ value: resolveStoredSecretValue({
+ incoming: secret.value,
+ existing: previousByEnv.get(secret.env),
+ }),
+ })),
+ },
+ };
+}
+
+/** Mask secret values for API responses. */
+export function redactManifestSecrets(manifest: SandboxEnvironmentManifest): SandboxEnvironmentManifest {
+ const secrets = manifest.networking?.secrets;
+ if (!secrets) {
+ return manifest;
+ }
+ return {
+ ...manifest,
+ networking: {
+ ...manifest.networking,
+ secrets: secrets.map(secret => ({
+ ...secret,
+ value: toRedactedSecretValue(secret.value),
+ })),
+ },
+ };
+}
+
+/** Fill backend-only type/sandbox_provider for jsonb storage. */
+export function toStoredManifest({
+ manifest,
+ provider_type,
+}: {
+ manifest: SandboxEnvironmentManifest;
+ provider_type: SandboxEnvironmentProviderType;
+}): StoredSandboxEnvironmentManifest {
+ return {
+ ...manifest,
+ type: provider_type,
+ sandbox_provider: provider_type,
+ };
+}
+
+export function diffManifest({
+ previous,
+ next,
+}: {
+ previous: StoredSandboxEnvironmentManifest | undefined;
+ next: SandboxEnvironmentManifest;
+}): ManifestDiff {
+ return {
+ build_changed: previous?.image?.build_script !== next.image?.build_script,
+ resources_changed: previous === undefined || !isDeepStrictEqual(previous.resources, next.resources),
+ secrets_changed: (next.networking?.secrets ?? []).some(secret => !isRedactedSecretValue(secret.value)),
+ };
+}
+
+/** Opaque Daytona snapshot name for an environment version. */
+export function newExternalRef(): string {
+ return `trueforge-${randomUUID()}`;
+}
+
+/** Build the next version row fields (no insert). Secrets / Daytona sync intentionally skipped. */
+export function buildNextVersion({
+ version,
+ previous_manifest,
+ previous_external_ref,
+ manifest,
+ provider_type,
+}: {
+ version: number;
+ previous_manifest?: StoredSandboxEnvironmentManifest;
+ previous_external_ref?: string;
+ manifest: SandboxEnvironmentManifest;
+ provider_type: SandboxEnvironmentProviderType;
+}): NextSandboxEnvironmentVersion {
+ const diff = diffManifest({ previous: previous_manifest, next: manifest });
+ // Detect only — do NOT call Daytona secrets/build APIs here.
+ const needs_snapshot =
+ manifest.image?.type === 'build' && (diff.build_changed || diff.resources_changed || !previous_external_ref);
+
+ const resolved = resolveManifestSecrets({
+ manifest,
+ ...(previous_manifest ? { previous: previous_manifest } : {}),
+ });
+
+ // Always `pending` until a future controller activates (or fails) the version.
+ return {
+ version,
+ manifest: toStoredManifest({ manifest: resolved, provider_type }),
+ status: 'pending',
+ status_reason: null,
+ external_ref: needs_snapshot || !previous_external_ref ? newExternalRef() : previous_external_ref,
+ internal_metadata: SandboxEnvironmentVersionInternalMetadataSchema.parse({}),
+ };
+}
diff --git a/packages/trueforge/src/schemas/sandboxEnvironment.ts b/packages/trueforge/src/schemas/sandboxEnvironment.ts
index c8e741544..c7acdab7b 100644
--- a/packages/trueforge/src/schemas/sandboxEnvironment.ts
+++ b/packages/trueforge/src/schemas/sandboxEnvironment.ts
@@ -26,7 +26,7 @@ export const SandboxEnvironmentLifecycleStageSchema = z
export const SandboxEnvironmentVersionStatusSchema = z
.enum(['pending', 'active', 'failed'])
- .describe('Build/activation status of an environment version.')
+ .describe('Build/activation status of the environment (active version under the hood).')
.openapi('SandboxEnvironmentVersionStatus');
/** Single image variant today; widen with discriminatedUnion when another type lands. */
@@ -53,11 +53,7 @@ export const SandboxEnvironmentResourcesSchema = z
export const SandboxEnvironmentSecretSchema = z
.object({
env: z.string().min(1).describe('Environment variable name injected into the sandbox.'),
- value: z
- .string()
- .min(1)
- .optional()
- .describe('Secret value or placeholder; resolved against the secrets store later.'),
+ value: z.string().min(1).describe('Secret value; GET responses use a redacted stand-in.'),
hosts: z.array(z.string().min(1)).describe('Hosts this secret may be sent to.'),
})
.strict()
@@ -97,7 +93,9 @@ export const SandboxEnvironmentNetworkingSchema = z
/** Wire + request/response document — no `type` / `sandbox_provider`. */
export const SandboxEnvironmentManifestSchema = z
.object({
- name: NameSchema,
+ name: NameSchema.refine(name => name !== 'default', {
+ message: 'name "default" is reserved',
+ }),
description: SandboxEnvironmentDescriptionSchema.optional(),
image: SandboxEnvironmentImageSchema.optional(),
resources: SandboxEnvironmentResourcesSchema.default({ cpu: 1, memory: 1, disk: 3 }),
@@ -109,6 +107,7 @@ export const SandboxEnvironmentManifestSchema = z
/**
* Persisted version jsonb — wire fields plus backend-resolved provider identity.
+ * `truefoundry` = TrueFoundry platform mode label; runtime still uses Daytona for envs.
* Not exposed on request/response wire types.
*/
export const StoredSandboxEnvironmentManifestSchema = z
@@ -129,27 +128,14 @@ export const SandboxEnvironmentVersionSecretSchema = z
/** Version jsonb column only — not on CRUD wire responses. */
export const SandboxEnvironmentVersionInternalMetadataSchema = z
.object({
- secrets: z.array(SandboxEnvironmentVersionSecretSchema).describe('Resolved secret refs for this version.'),
+ secrets: z
+ .array(SandboxEnvironmentVersionSecretSchema)
+ .default([])
+ .describe('Resolved secret refs for this version.'),
})
.strict();
-export const SandboxEnvironmentVersionSummarySchema = z
- .object({
- version: z.number().int().positive().describe('Monotonic version number within the environment.'),
- status: SandboxEnvironmentVersionStatusSchema,
- status_reason: z.string().nullable().describe('Failure detail when status is failed; null otherwise.'),
- external_ref: z.string().min(1).describe('Server-generated provider snapshot/build name.'),
- })
- .strict()
- .openapi('SandboxEnvironmentVersionSummary');
-
-export const CreateSandboxEnvironmentRequestSchema = z
- .object({
- manifest: SandboxEnvironmentManifestSchema,
- })
- .strict()
- .openapi('CreateSandboxEnvironmentRequest');
-
+/** PUT create-or-update body (single write API). */
export const UpdateSandboxEnvironmentRequestSchema = z
.object({
manifest: SandboxEnvironmentManifestSchema,
@@ -164,10 +150,10 @@ export const SandboxEnvironmentSchema = z
id: z.string().min(1).describe('Immutable server-generated environment identifier.'),
name: NameSchema,
description: z.string().describe('Human-readable description; empty when unset.'),
- active_version: z.number().int().positive().describe('Version currently pointed at by the environment.'),
lifecycle_stage: SandboxEnvironmentLifecycleStageSchema,
+ status: SandboxEnvironmentVersionStatusSchema.describe('Readiness of the environment.'),
+ status_reason: z.string().nullable().describe('Failure detail when status is failed; null otherwise.'),
manifest: SandboxEnvironmentManifestSchema,
- version: SandboxEnvironmentVersionSummarySchema,
created_by_subject: CreatedBySubjectSchema,
created_at: IsoTimestamp.describe('ISO-8601 create time.'),
updated_at: IsoTimestamp.describe('ISO-8601 last update time.'),
@@ -193,7 +179,5 @@ export type SandboxEnvironmentVersionStatus = z.infer<typeof SandboxEnvironmentV
export type SandboxEnvironmentManifest = z.infer<typeof SandboxEnvironmentManifestSchema>;
export type StoredSandboxEnvironmentManifest = z.infer<typeof StoredSandboxEnvironmentManifestSchema>;
export type SandboxEnvironmentVersionInternalMetadata = z.infer<typeof SandboxEnvironmentVersionInternalMetadataSchema>;
-export type SandboxEnvironmentVersionSummary = z.infer<typeof SandboxEnvironmentVersionSummarySchema>;
-export type CreateSandboxEnvironmentRequest = z.infer<typeof CreateSandboxEnvironmentRequestSchema>;
export type UpdateSandboxEnvironmentRequest = z.infer<typeof UpdateSandboxEnvironmentRequestSchema>;
export type SandboxEnvironment = z.infer<typeof SandboxEnvironmentSchema>;
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
index adef757da..e4b904315 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
@@ -10,6 +10,7 @@ import {
type GetExternalIdsByIdsInput,
type GetOwnedIdsInput,
type IAgentStore,
+ type ListAgentNamesUsingSandboxEnvironmentInput,
type ListAgentsInput,
type UpdateAgentInput,
} from '../db/agentStore';
@@ -115,6 +116,13 @@ export class TrueFoundryAgentStore implements IAgentStore<Transaction<Database>>
return this.#inner.getAgent(input, transaction);
}
+ listAgentNamesUsingSandboxEnvironment(
+ input: ListAgentNamesUsingSandboxEnvironmentInput,
+ transaction?: Transaction<Database>,
+ ): Promise<readonly string[]> {
+ return this.#inner.listAgentNamesUsingSandboxEnvironment(input, transaction);
+ }
+
// Takes a Postgres transaction advisory lock for this tenant + agent id so concurrent
// update/delete cannot desync ServiceFoundry MCP grants. The lock only lasts for the
// lifetime of a DB transaction: if the caller passed one, use it; otherwise open a
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index a85368e0a..450ceb4c5 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -7,6 +7,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
import { SqliteWebSearchProviderStore } from '../../../src/db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore';
@@ -105,6 +106,7 @@ describe('agents router', () => {
resolveMcpServerStore: () => new SqliteMcpServerStore(db),
resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -116,6 +118,7 @@ describe('agents router', () => {
resolveMcpServerStore: () => new SqliteMcpServerStore(db),
resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
index 51b5c5ea6..4d6565d75 100644
--- a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
+++ b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
@@ -13,6 +13,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
@@ -39,6 +40,7 @@ describe('public CRUD after session deletion', () => {
const skillStore = new SqliteSkillStore(db);
const agentStore = new SqliteAgentStore(db);
const sandboxProviderStore = new SqliteSandboxProviderStore(db);
+ const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
const webSearchProviderStore = new SqliteWebSearchProviderStore(db);
const app = new OpenAPIHono();
@@ -53,6 +55,7 @@ describe('public CRUD after session deletion', () => {
resolveSkillStore: () => skillStore,
resolveAgentStore: () => agentStore,
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore,
resolveWebSearchProviderStore: () => webSearchProviderStore,
redis: createClient(),
requestReplyRouter: new RequestReplyRouter(),
@@ -73,6 +76,7 @@ describe('public CRUD after session deletion', () => {
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore,
resolveWebSearchProviderStore: () => webSearchProviderStore,
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
index 87ba267ab..b265be6c9 100644
--- a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
+++ b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
@@ -11,6 +11,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
@@ -52,6 +53,7 @@ async function buildApp() {
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/apis/schedules.test.ts b/packages/trueforge/tests/unit/apis/schedules.test.ts
index 199272e38..7da44b000 100644
--- a/packages/trueforge/tests/unit/apis/schedules.test.ts
+++ b/packages/trueforge/tests/unit/apis/schedules.test.ts
@@ -72,6 +72,7 @@ function stubTurnExecutionDeps(agentStore: SqliteAgentStore, scheduleStore: Sqli
resolveMcpServerStore: () => ({}) as never,
turnSkillsResolverStore: { resolveTurnSkills: async () => [] },
resolveSandboxProviderStore: () => ({}) as never,
+ sandboxEnvironmentStore: {} as never,
resolveWebSearchProviderStore: () => ({}) as never,
};
}
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index 48ee641b0..6da92584e 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -19,6 +19,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSessionMetricsStore } from '../../../src/db/sqlite/session-metrics/SqliteSessionMetricsStore';
import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
@@ -74,6 +75,7 @@ describe('sessions HTTP agent binding', () => {
const mcpServerStore = new SqliteMcpServerStore(db);
const skillStore = new SqliteSkillStore(db);
const sandboxProviderStore = new SqliteSandboxProviderStore(db);
+ const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
const webSearchProviderStore = new SqliteWebSearchProviderStore(db);
agentStore = new SqliteAgentStore(db);
@@ -103,6 +105,7 @@ describe('sessions HTTP agent binding', () => {
resolveSkillStore: () => skillStore,
resolveAgentStore: () => agentStore,
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore,
resolveWebSearchProviderStore: () => webSearchProviderStore,
redis: createClient(),
requestReplyRouter: new RequestReplyRouter(),
@@ -131,6 +134,7 @@ describe('sessions HTTP agent binding', () => {
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore,
resolveWebSearchProviderStore: () => webSearchProviderStore,
logger: deps.logger,
resolveRequestContext: deps.resolveRequestContext,
diff --git a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
index a9e444870..83bdb51f4 100644
--- a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
+++ b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
@@ -11,6 +11,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
@@ -80,6 +81,7 @@ async function postTurnRejectingWith(error: AgentHarnessError): Promise<Response
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/apis/turns.test.ts b/packages/trueforge/tests/unit/apis/turns.test.ts
index fc1e20c4e..e75e602eb 100644
--- a/packages/trueforge/tests/unit/apis/turns.test.ts
+++ b/packages/trueforge/tests/unit/apis/turns.test.ts
@@ -16,6 +16,7 @@ import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgent
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
@@ -76,6 +77,7 @@ describe('turns', () => {
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -171,6 +173,7 @@ describe('turns', () => {
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -272,6 +275,7 @@ describe('turns', () => {
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -342,6 +346,7 @@ describe('turns', () => {
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -449,6 +454,7 @@ describe('turns', () => {
resolveSkillStore: () => new SqliteSkillStore(db),
eventSubscriptions,
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger,
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -557,6 +563,7 @@ describe('turns', () => {
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger,
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -643,6 +650,7 @@ describe('turns', () => {
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
logger: createLogger({ silent: true }),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index 37c9bddc4..e658d1363 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -6,6 +6,7 @@ import type { ISkillStore } from '../../../src/db/skillStore';
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
import { SqliteWebSearchProviderStore } from '../../../src/db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore';
@@ -67,6 +68,7 @@ describe('validateAgentSpec', () => {
mcpServerStore: new SqliteMcpServerStore(db),
skillStore: new SqliteSkillStore(db),
sandboxProviderStore: new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
webSearchProviderStore: new SqliteWebSearchProviderStore(db),
};
}
@@ -100,6 +102,7 @@ describe('validateAgentSpec', () => {
instructions: 'test',
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -117,6 +120,7 @@ describe('validateAgentSpec', () => {
instructions: 'test',
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -134,6 +138,7 @@ describe('validateAgentSpec', () => {
instructions: 'test',
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -151,6 +156,7 @@ describe('validateAgentSpec', () => {
instructions: 'test',
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -169,6 +175,7 @@ describe('validateAgentSpec', () => {
mcp_servers: [{ name: 'missing-mcp' }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -187,6 +194,7 @@ describe('validateAgentSpec', () => {
skills: [{ name: 'missing-skill' }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -205,6 +213,7 @@ describe('validateAgentSpec', () => {
config: { sandbox: { enabled: true } },
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -223,6 +232,7 @@ describe('validateAgentSpec', () => {
config: { web_search: { enabled: true } },
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -242,6 +252,7 @@ describe('validateAgentSpec', () => {
config: { web_search: { enabled: true } },
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).resolves.toBeUndefined();
@@ -269,6 +280,7 @@ describe('validateAgentSpec', () => {
skills: [{ name: 'demo' }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
@@ -302,6 +314,7 @@ describe('validateAgentSpec', () => {
config: { sandbox: { enabled: true } },
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).resolves.toBeUndefined();
@@ -323,6 +336,7 @@ describe('validateAgentSpec', () => {
config: { sandbox: { enabled: true } },
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).resolves.toBeUndefined();
@@ -378,6 +392,7 @@ describe('validateAgentSpec', () => {
skills: [{ name: fqn }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
skillStore,
}),
@@ -404,6 +419,7 @@ describe('validateAgentSpec', () => {
skills: [{ name: 'agent-skill:acme/team-a/echo:3', preload: false }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).resolves.toBeUndefined();
@@ -440,6 +456,7 @@ describe('validateAgentSpec', () => {
skills: [{ name: 'echo', preload: true }],
}),
tenant_id: 'default',
+ created_by_subject_id: 'test-subject',
...stores,
}),
).rejects.toMatchObject({
diff --git a/python/trueforge_sdk/reference.md b/python/trueforge_sdk/reference.md
index 29caa7ba4..a83fc737a 100644
--- a/python/trueforge_sdk/reference.md
+++ b/python/trueforge_sdk/reference.md
@@ -1045,6 +1045,303 @@ client.models.list()
</dl>
+</dd>
+</dl>
+</details>
+
+## SandboxEnvironments
+<details><summary><code>client.sandbox_environments.<a href="src/trueforge_sdk/sandbox_environments/client.py">list</a>(...) -> ListSandboxEnvironmentsResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+List sandbox environments created by the authenticated subject, newest first.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.sandbox_environments.list()
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**limit:** `typing.Optional[int]` — Page size. Defaults to 25
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**page_token:** `typing.Optional[str]` — Opaque token from a previous response `next_page_token`.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandbox_environments.<a href="src/trueforge_sdk/sandbox_environments/client.py">create_or_update</a>(...) -> GetSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge, SandboxEnvironmentManifest
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.sandbox_environments.create_or_update(
+ manifest=SandboxEnvironmentManifest(
+ name="name",
+ ),
+)
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**manifest:** `SandboxEnvironmentManifest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandbox_environments.<a href="src/trueforge_sdk/sandbox_environments/client.py">get</a>(...) -> GetSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Get a sandbox environment by name for the authenticated subject.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.sandbox_environments.get(
+ name="name",
+)
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**name:** `str` — Sandbox environment name.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sandbox_environments.<a href="src/trueforge_sdk/sandbox_environments/client.py">delete</a>(...) -> DeleteSandboxEnvironmentResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Delete by name. Fails if any agent still references the environment.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.sandbox_environments.delete(
+ name="name",
+)
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**name:** `str` — Sandbox environment name.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index 280074011..17101a3d2 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -64,6 +64,7 @@ if typing.TYPE_CHECKING:
CustomModelProvider,
DaytonaSandboxProviderAuth,
DeleteAgentResponse,
+ DeleteSandboxEnvironmentResponse,
DeleteScheduleResponse,
DynamicSubAgentsConfig,
ExtendedChunkDeltaToolCall,
@@ -81,6 +82,7 @@ if typing.TYPE_CHECKING:
GetMeSubject,
GetModelProviderCatalogResponse,
GetModelProviderResponse,
+ GetSandboxEnvironmentResponse,
GetSandboxProviderCatalogResponse,
GetSandboxProviderResponse,
GetScheduleResponse,
@@ -107,6 +109,7 @@ if typing.TYPE_CHECKING:
ListModelProvidersResponse,
ListPermissionsData,
ListPermissionsResponse,
+ ListSandboxEnvironmentsResponse,
ListScheduleRunsResponse,
ListSchedulesResponse,
ListSessionEventsResponse,
@@ -171,6 +174,14 @@ if typing.TYPE_CHECKING:
SandboxCapability,
SandboxConfig,
SandboxCreatedEvent,
+ SandboxEnvironment,
+ SandboxEnvironmentImage,
+ SandboxEnvironmentLifecycleStage,
+ SandboxEnvironmentManifest,
+ SandboxEnvironmentNetworking,
+ SandboxEnvironmentResources,
+ SandboxEnvironmentSecret,
+ SandboxEnvironmentVersionStatus,
SandboxProviderManifest,
Schedule,
ScheduleManifest,
@@ -275,7 +286,20 @@ if typing.TYPE_CHECKING:
UnauthorizedError,
UnprocessableEntityError,
)
- from . import agents, auth, catalogs, internal, mcp_servers, models, schedules, server, sessions, settings, skills
+ from . import (
+ agents,
+ auth,
+ catalogs,
+ internal,
+ mcp_servers,
+ models,
+ sandbox_environments,
+ schedules,
+ server,
+ sessions,
+ settings,
+ skills,
+ )
from ._default_clients import DefaultAioHttpClient, DefaultAsyncHttpxClient
from .client import AsyncTrueForge, TrueForge
from .version import __version__
@@ -344,6 +368,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"DefaultAioHttpClient": "._default_clients",
"DefaultAsyncHttpxClient": "._default_clients",
"DeleteAgentResponse": ".types",
+ "DeleteSandboxEnvironmentResponse": ".types",
"DeleteScheduleResponse": ".types",
"DynamicSubAgentsConfig": ".types",
"ExtendedChunkDeltaToolCall": ".types",
@@ -363,6 +388,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"GetMeSubject": ".types",
"GetModelProviderCatalogResponse": ".types",
"GetModelProviderResponse": ".types",
+ "GetSandboxEnvironmentResponse": ".types",
"GetSandboxProviderCatalogResponse": ".types",
"GetSandboxProviderResponse": ".types",
"GetScheduleResponse": ".types",
@@ -391,6 +417,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ListModelProvidersResponse": ".types",
"ListPermissionsData": ".types",
"ListPermissionsResponse": ".types",
+ "ListSandboxEnvironmentsResponse": ".types",
"ListScheduleRunsResponse": ".types",
"ListSchedulesResponse": ".types",
"ListSessionEventsResponse": ".types",
@@ -457,6 +484,14 @@ _dynamic_imports: typing.Dict[str, str] = {
"SandboxCapability": ".types",
"SandboxConfig": ".types",
"SandboxCreatedEvent": ".types",
+ "SandboxEnvironment": ".types",
+ "SandboxEnvironmentImage": ".types",
+ "SandboxEnvironmentLifecycleStage": ".types",
+ "SandboxEnvironmentManifest": ".types",
+ "SandboxEnvironmentNetworking": ".types",
+ "SandboxEnvironmentResources": ".types",
+ "SandboxEnvironmentSecret": ".types",
+ "SandboxEnvironmentVersionStatus": ".types",
"SandboxProviderManifest": ".types",
"Schedule": ".types",
"ScheduleManifest": ".types",
@@ -556,6 +591,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"internal": ".internal",
"mcp_servers": ".mcp_servers",
"models": ".models",
+ "sandbox_environments": ".sandbox_environments",
"schedules": ".schedules",
"server": ".server",
"sessions": ".sessions",
@@ -650,6 +686,7 @@ __all__ = [
"DefaultAioHttpClient",
"DefaultAsyncHttpxClient",
"DeleteAgentResponse",
+ "DeleteSandboxEnvironmentResponse",
"DeleteScheduleResponse",
"DynamicSubAgentsConfig",
"ExtendedChunkDeltaToolCall",
@@ -669,6 +706,7 @@ __all__ = [
"GetMeSubject",
"GetModelProviderCatalogResponse",
"GetModelProviderResponse",
+ "GetSandboxEnvironmentResponse",
"GetSandboxProviderCatalogResponse",
"GetSandboxProviderResponse",
"GetScheduleResponse",
@@ -697,6 +735,7 @@ __all__ = [
"ListModelProvidersResponse",
"ListPermissionsData",
"ListPermissionsResponse",
+ "ListSandboxEnvironmentsResponse",
"ListScheduleRunsResponse",
"ListSchedulesResponse",
"ListSessionEventsResponse",
@@ -763,6 +802,14 @@ __all__ = [
"SandboxCapability",
"SandboxConfig",
"SandboxCreatedEvent",
+ "SandboxEnvironment",
+ "SandboxEnvironmentImage",
+ "SandboxEnvironmentLifecycleStage",
+ "SandboxEnvironmentManifest",
+ "SandboxEnvironmentNetworking",
+ "SandboxEnvironmentResources",
+ "SandboxEnvironmentSecret",
+ "SandboxEnvironmentVersionStatus",
"SandboxProviderManifest",
"Schedule",
"ScheduleManifest",
@@ -862,6 +909,7 @@ __all__ = [
"internal",
"mcp_servers",
"models",
+ "sandbox_environments",
"schedules",
"server",
"sessions",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/base_client.py b/python/trueforge_sdk/src/trueforge_sdk/base_client.py
index e086197b1..f2fbb2e2c 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/base_client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/base_client.py
@@ -15,6 +15,7 @@ if typing.TYPE_CHECKING:
from .internal.client import AsyncInternalClient, InternalClient
from .mcp_servers.client import AsyncMcpServersClient, McpServersClient
from .models.client import AsyncModelsClient, ModelsClient
+ from .sandbox_environments.client import AsyncSandboxEnvironmentsClient, SandboxEnvironmentsClient
from .schedules.client import AsyncSchedulesClient, SchedulesClient
from .server.client import AsyncServerClient, ServerClient
from .sessions.client import AsyncSessionsClient, SessionsClient
@@ -103,6 +104,7 @@ class BaseTrueForge:
self._server: typing.Optional[ServerClient] = None
self._mcp_servers: typing.Optional[McpServersClient] = None
self._models: typing.Optional[ModelsClient] = None
+ self._sandbox_environments: typing.Optional[SandboxEnvironmentsClient] = None
self._schedules: typing.Optional[SchedulesClient] = None
self._sessions: typing.Optional[SessionsClient] = None
self._skills: typing.Optional[SkillsClient] = None
@@ -157,6 +159,14 @@ class BaseTrueForge:
self._models = ModelsClient(client_wrapper=self._client_wrapper)
return self._models
+ @property
+ def sandbox_environments(self):
+ if self._sandbox_environments is None:
+ from .sandbox_environments.client import SandboxEnvironmentsClient # noqa: E402
+
+ self._sandbox_environments = SandboxEnvironmentsClient(client_wrapper=self._client_wrapper)
+ return self._sandbox_environments
+
@property
def schedules(self):
if self._schedules is None:
@@ -300,6 +310,7 @@ class AsyncBaseTrueForge:
self._server: typing.Optional[AsyncServerClient] = None
self._mcp_servers: typing.Optional[AsyncMcpServersClient] = None
self._models: typing.Optional[AsyncModelsClient] = None
+ self._sandbox_environments: typing.Optional[AsyncSandboxEnvironmentsClient] = None
self._schedules: typing.Optional[AsyncSchedulesClient] = None
self._sessions: typing.Optional[AsyncSessionsClient] = None
self._skills: typing.Optional[AsyncSkillsClient] = None
@@ -354,6 +365,14 @@ class AsyncBaseTrueForge:
self._models = AsyncModelsClient(client_wrapper=self._client_wrapper)
return self._models
+ @property
+ def sandbox_environments(self):
+ if self._sandbox_environments is None:
+ from .sandbox_environments.client import AsyncSandboxEnvironmentsClient # noqa: E402
+
+ self._sandbox_environments = AsyncSandboxEnvironmentsClient(client_wrapper=self._client_wrapper)
+ return self._sandbox_environments
+
@property
def schedules(self):
if self._schedules is None:
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/__init__.py
new file mode 100644
index 000000000..5cde0202d
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/__init__.py
@@ -0,0 +1,4 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py
new file mode 100644
index 000000000..8c93146b5
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py
@@ -0,0 +1,373 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.pagination import AsyncPager, SyncPager
+from ..core.request_options import RequestOptions
+from ..types.delete_sandbox_environment_response import DeleteSandboxEnvironmentResponse
+from ..types.get_sandbox_environment_response import GetSandboxEnvironmentResponse
+from ..types.list_sandbox_environments_response import ListSandboxEnvironmentsResponse
+from ..types.sandbox_environment import SandboxEnvironment
+from ..types.sandbox_environment_manifest import SandboxEnvironmentManifest
+from .raw_client import AsyncRawSandboxEnvironmentsClient, RawSandboxEnvironmentsClient
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class SandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: SyncClientWrapper):
+ self._raw_client = RawSandboxEnvironmentsClient(client_wrapper=client_wrapper)
+
+ @property
+ def with_raw_response(self) -> RawSandboxEnvironmentsClient:
+ """
+ Retrieves a raw implementation of this client that returns raw responses.
+
+ Returns
+ -------
+ RawSandboxEnvironmentsClient
+ """
+ return self._raw_client
+
+ def list(
+ self,
+ *,
+ limit: typing.Optional[int] = 25,
+ page_token: typing.Optional[str] = None,
+ request_options: typing.Optional[RequestOptions] = None,
+ ) -> SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
+ """
+ List sandbox environments created by the authenticated subject, newest first.
+
+ Parameters
+ ----------
+ limit : typing.Optional[int]
+ Page size. Defaults to 25
+
+ page_token : typing.Optional[str]
+ Opaque token from a previous response `next_page_token`.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]
+ Paginated sandbox environments.
+
+ Examples
+ --------
+ from trueforge_sdk import TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ response = client.sandbox_environments.list()
+ for item in response:
+ yield item
+ # alternatively, you can paginate page-by-page
+ for page in response.iter_pages():
+ yield page
+ """
+ return self._raw_client.list(limit=limit, page_token=page_token, request_options=request_options)
+
+ def create_or_update(
+ self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ ) -> GetSandboxEnvironmentResponse:
+ """
+ Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+
+ Parameters
+ ----------
+ manifest : SandboxEnvironmentManifest
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ GetSandboxEnvironmentResponse
+ The saved sandbox environment.
+
+ Examples
+ --------
+ from trueforge_sdk import SandboxEnvironmentManifest, TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ client.sandbox_environments.create_or_update(
+ manifest=SandboxEnvironmentManifest(
+ name="name",
+ ),
+ )
+ """
+ _response = self._raw_client.create_or_update(manifest=manifest, request_options=request_options)
+ return _response.data
+
+ def get(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> GetSandboxEnvironmentResponse:
+ """
+ Get a sandbox environment by name for the authenticated subject.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ GetSandboxEnvironmentResponse
+ The sandbox environment.
+
+ Examples
+ --------
+ from trueforge_sdk import TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ client.sandbox_environments.get(
+ name="name",
+ )
+ """
+ _response = self._raw_client.get(name=name, request_options=request_options)
+ return _response.data
+
+ def delete(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> DeleteSandboxEnvironmentResponse:
+ """
+ Delete by name. Fails if any agent still references the environment.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ DeleteSandboxEnvironmentResponse
+ Sandbox environment deleted.
+
+ Examples
+ --------
+ from trueforge_sdk import TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ client.sandbox_environments.delete(
+ name="name",
+ )
+ """
+ _response = self._raw_client.delete(name=name, request_options=request_options)
+ return _response.data
+
+
+class AsyncSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: AsyncClientWrapper):
+ self._raw_client = AsyncRawSandboxEnvironmentsClient(client_wrapper=client_wrapper)
+
+ @property
+ def with_raw_response(self) -> AsyncRawSandboxEnvironmentsClient:
+ """
+ Retrieves a raw implementation of this client that returns raw responses.
+
+ Returns
+ -------
+ AsyncRawSandboxEnvironmentsClient
+ """
+ return self._raw_client
+
+ async def list(
+ self,
+ *,
+ limit: typing.Optional[int] = 25,
+ page_token: typing.Optional[str] = None,
+ request_options: typing.Optional[RequestOptions] = None,
+ ) -> AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
+ """
+ List sandbox environments created by the authenticated subject, newest first.
+
+ Parameters
+ ----------
+ limit : typing.Optional[int]
+ Page size. Defaults to 25
+
+ page_token : typing.Optional[str]
+ Opaque token from a previous response `next_page_token`.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]
+ Paginated sandbox environments.
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ response = await client.sandbox_environments.list()
+ async for item in response:
+ yield item
+
+ # alternatively, you can paginate page-by-page
+ async for page in response.iter_pages():
+ yield page
+
+
+ asyncio.run(main())
+ """
+ return await self._raw_client.list(limit=limit, page_token=page_token, request_options=request_options)
+
+ async def create_or_update(
+ self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ ) -> GetSandboxEnvironmentResponse:
+ """
+ Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+
+ Parameters
+ ----------
+ manifest : SandboxEnvironmentManifest
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ GetSandboxEnvironmentResponse
+ The saved sandbox environment.
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge, SandboxEnvironmentManifest
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ await client.sandbox_environments.create_or_update(
+ manifest=SandboxEnvironmentManifest(
+ name="name",
+ ),
+ )
+
+
+ asyncio.run(main())
+ """
+ _response = await self._raw_client.create_or_update(manifest=manifest, request_options=request_options)
+ return _response.data
+
+ async def get(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> GetSandboxEnvironmentResponse:
+ """
+ Get a sandbox environment by name for the authenticated subject.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ GetSandboxEnvironmentResponse
+ The sandbox environment.
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ await client.sandbox_environments.get(
+ name="name",
+ )
+
+
+ asyncio.run(main())
+ """
+ _response = await self._raw_client.get(name=name, request_options=request_options)
+ return _response.data
+
+ async def delete(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> DeleteSandboxEnvironmentResponse:
+ """
+ Delete by name. Fails if any agent still references the environment.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ DeleteSandboxEnvironmentResponse
+ Sandbox environment deleted.
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ await client.sandbox_environments.delete(
+ name="name",
+ )
+
+
+ asyncio.run(main())
+ """
+ _response = await self._raw_client.delete(name=name, request_options=request_options)
+ return _response.data
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py
new file mode 100644
index 000000000..7a52bfff4
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py
@@ -0,0 +1,688 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from json.decoder import JSONDecodeError
+
+from ..core.api_error import ApiError
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.http_response import AsyncHttpResponse, HttpResponse
+from ..core.jsonable_encoder import encode_path_param
+from ..core.pagination import AsyncPager, SyncPager
+from ..core.parse_error import ParsingError
+from ..core.request_options import RequestOptions
+from ..core.serialization import convert_and_respect_annotation_metadata
+from ..core.unchecked_base_model import construct_type
+from ..errors.bad_request_error import BadRequestError
+from ..errors.conflict_error import ConflictError
+from ..errors.not_found_error import NotFoundError
+from ..errors.unauthorized_error import UnauthorizedError
+from ..errors.unprocessable_entity_error import UnprocessableEntityError
+from ..types.delete_sandbox_environment_response import DeleteSandboxEnvironmentResponse
+from ..types.get_sandbox_environment_response import GetSandboxEnvironmentResponse
+from ..types.list_sandbox_environments_response import ListSandboxEnvironmentsResponse
+from ..types.request_error_response import RequestErrorResponse
+from ..types.sandbox_environment import SandboxEnvironment
+from ..types.sandbox_environment_manifest import SandboxEnvironmentManifest
+from pydantic import ValidationError
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class RawSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: SyncClientWrapper):
+ self._client_wrapper = client_wrapper
+
+ def list(
+ self,
+ *,
+ limit: typing.Optional[int] = 25,
+ page_token: typing.Optional[str] = None,
+ request_options: typing.Optional[RequestOptions] = None,
+ ) -> SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
+ """
+ List sandbox environments created by the authenticated subject, newest first.
+
+ Parameters
+ ----------
+ limit : typing.Optional[int]
+ Page size. Defaults to 25
+
+ page_token : typing.Optional[str]
+ Opaque token from a previous response `next_page_token`.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]
+ Paginated sandbox environments.
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ "api/v1/sandbox-environments",
+ method="GET",
+ params={
+ "limit": limit,
+ "page_token": page_token,
+ },
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _parsed_response = typing.cast(
+ ListSandboxEnvironmentsResponse,
+ construct_type(
+ type_=ListSandboxEnvironmentsResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ _items = _parsed_response.data
+ _has_next = False
+ _get_next = None
+ if _parsed_response.pagination is not None:
+ _parsed_next = _parsed_response.pagination.next_page_token
+ _has_next = _parsed_next is not None and _parsed_next != ""
+ _get_next = lambda: self.list(
+ limit=limit,
+ page_token=_parsed_next,
+ request_options=request_options,
+ )
+ return SyncPager(has_next=_has_next, items=_items, get_next=_get_next, response=_parsed_response)
+ if _response.status_code == 400:
+ raise BadRequestError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ def create_or_update(
+ self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ ) -> HttpResponse[GetSandboxEnvironmentResponse]:
+ """
+ Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+
+ Parameters
+ ----------
+ manifest : SandboxEnvironmentManifest
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ HttpResponse[GetSandboxEnvironmentResponse]
+ The saved sandbox environment.
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ "api/v1/sandbox-environments",
+ method="PUT",
+ json={
+ "manifest": convert_and_respect_annotation_metadata(
+ object_=manifest, annotation=SandboxEnvironmentManifest, direction="write"
+ ),
+ },
+ headers={
+ "content-type": "application/json",
+ },
+ request_options=request_options,
+ omit=OMIT,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ GetSandboxEnvironmentResponse,
+ construct_type(
+ type_=GetSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return HttpResponse(response=_response, data=_data)
+ if _response.status_code == 400:
+ raise BadRequestError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 409:
+ raise ConflictError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 422:
+ raise UnprocessableEntityError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ def get(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> HttpResponse[GetSandboxEnvironmentResponse]:
+ """
+ Get a sandbox environment by name for the authenticated subject.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ HttpResponse[GetSandboxEnvironmentResponse]
+ The sandbox environment.
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ f"api/v1/sandbox-environments/{encode_path_param(name)}",
+ method="GET",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ GetSandboxEnvironmentResponse,
+ construct_type(
+ type_=GetSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return HttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ def delete(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> HttpResponse[DeleteSandboxEnvironmentResponse]:
+ """
+ Delete by name. Fails if any agent still references the environment.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ HttpResponse[DeleteSandboxEnvironmentResponse]
+ Sandbox environment deleted.
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ f"api/v1/sandbox-environments/{encode_path_param(name)}",
+ method="DELETE",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ DeleteSandboxEnvironmentResponse,
+ construct_type(
+ type_=DeleteSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return HttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 409:
+ raise ConflictError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+
+class AsyncRawSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: AsyncClientWrapper):
+ self._client_wrapper = client_wrapper
+
+ async def list(
+ self,
+ *,
+ limit: typing.Optional[int] = 25,
+ page_token: typing.Optional[str] = None,
+ request_options: typing.Optional[RequestOptions] = None,
+ ) -> AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
+ """
+ List sandbox environments created by the authenticated subject, newest first.
+
+ Parameters
+ ----------
+ limit : typing.Optional[int]
+ Page size. Defaults to 25
+
+ page_token : typing.Optional[str]
+ Opaque token from a previous response `next_page_token`.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]
+ Paginated sandbox environments.
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ "api/v1/sandbox-environments",
+ method="GET",
+ params={
+ "limit": limit,
+ "page_token": page_token,
+ },
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _parsed_response = typing.cast(
+ ListSandboxEnvironmentsResponse,
+ construct_type(
+ type_=ListSandboxEnvironmentsResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ _items = _parsed_response.data
+ _has_next = False
+ _get_next = None
+ if _parsed_response.pagination is not None:
+ _parsed_next = _parsed_response.pagination.next_page_token
+ _has_next = _parsed_next is not None and _parsed_next != ""
+
+ async def _get_next():
+ return await self.list(
+ limit=limit,
+ page_token=_parsed_next,
+ request_options=request_options,
+ )
+
+ return AsyncPager(has_next=_has_next, items=_items, get_next=_get_next, response=_parsed_response)
+ if _response.status_code == 400:
+ raise BadRequestError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ async def create_or_update(
+ self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ ) -> AsyncHttpResponse[GetSandboxEnvironmentResponse]:
+ """
+ Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+
+ Parameters
+ ----------
+ manifest : SandboxEnvironmentManifest
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncHttpResponse[GetSandboxEnvironmentResponse]
+ The saved sandbox environment.
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ "api/v1/sandbox-environments",
+ method="PUT",
+ json={
+ "manifest": convert_and_respect_annotation_metadata(
+ object_=manifest, annotation=SandboxEnvironmentManifest, direction="write"
+ ),
+ },
+ headers={
+ "content-type": "application/json",
+ },
+ request_options=request_options,
+ omit=OMIT,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ GetSandboxEnvironmentResponse,
+ construct_type(
+ type_=GetSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return AsyncHttpResponse(response=_response, data=_data)
+ if _response.status_code == 400:
+ raise BadRequestError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 409:
+ raise ConflictError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 422:
+ raise UnprocessableEntityError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ async def get(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> AsyncHttpResponse[GetSandboxEnvironmentResponse]:
+ """
+ Get a sandbox environment by name for the authenticated subject.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncHttpResponse[GetSandboxEnvironmentResponse]
+ The sandbox environment.
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ f"api/v1/sandbox-environments/{encode_path_param(name)}",
+ method="GET",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ GetSandboxEnvironmentResponse,
+ construct_type(
+ type_=GetSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return AsyncHttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ async def delete(
+ self, *, name: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> AsyncHttpResponse[DeleteSandboxEnvironmentResponse]:
+ """
+ Delete by name. Fails if any agent still references the environment.
+
+ Parameters
+ ----------
+ name : str
+ Sandbox environment name.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncHttpResponse[DeleteSandboxEnvironmentResponse]
+ Sandbox environment deleted.
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ f"api/v1/sandbox-environments/{encode_path_param(name)}",
+ method="DELETE",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ DeleteSandboxEnvironmentResponse,
+ construct_type(
+ type_=DeleteSandboxEnvironmentResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return AsyncHttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 409:
+ raise ConflictError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index 7c265d263..a4996ddb6 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -63,6 +63,7 @@ if typing.TYPE_CHECKING:
from .custom_model_provider import CustomModelProvider
from .daytona_sandbox_provider_auth import DaytonaSandboxProviderAuth
from .delete_agent_response import DeleteAgentResponse
+ from .delete_sandbox_environment_response import DeleteSandboxEnvironmentResponse
from .delete_schedule_response import DeleteScheduleResponse
from .dynamic_sub_agents_config import DynamicSubAgentsConfig
from .extended_chunk_delta_tool_call import ExtendedChunkDeltaToolCall
@@ -80,6 +81,7 @@ if typing.TYPE_CHECKING:
from .get_me_subject import GetMeSubject
from .get_model_provider_catalog_response import GetModelProviderCatalogResponse
from .get_model_provider_response import GetModelProviderResponse
+ from .get_sandbox_environment_response import GetSandboxEnvironmentResponse
from .get_sandbox_provider_catalog_response import GetSandboxProviderCatalogResponse
from .get_sandbox_provider_response import GetSandboxProviderResponse
from .get_schedule_response import GetScheduleResponse
@@ -106,6 +108,7 @@ if typing.TYPE_CHECKING:
from .list_model_providers_response import ListModelProvidersResponse
from .list_permissions_data import ListPermissionsData
from .list_permissions_response import ListPermissionsResponse
+ from .list_sandbox_environments_response import ListSandboxEnvironmentsResponse
from .list_schedule_runs_response import ListScheduleRunsResponse
from .list_schedules_response import ListSchedulesResponse
from .list_session_events_response import ListSessionEventsResponse
@@ -170,6 +173,14 @@ if typing.TYPE_CHECKING:
from .sandbox_capability import SandboxCapability
from .sandbox_config import SandboxConfig
from .sandbox_created_event import SandboxCreatedEvent
+ from .sandbox_environment import SandboxEnvironment
+ from .sandbox_environment_image import SandboxEnvironmentImage
+ from .sandbox_environment_lifecycle_stage import SandboxEnvironmentLifecycleStage
+ from .sandbox_environment_manifest import SandboxEnvironmentManifest
+ from .sandbox_environment_networking import SandboxEnvironmentNetworking
+ from .sandbox_environment_resources import SandboxEnvironmentResources
+ from .sandbox_environment_secret import SandboxEnvironmentSecret
+ from .sandbox_environment_version_status import SandboxEnvironmentVersionStatus
from .sandbox_provider_manifest import SandboxProviderManifest
from .schedule import Schedule
from .schedule_manifest import ScheduleManifest
@@ -317,6 +328,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"CustomModelProvider": ".custom_model_provider",
"DaytonaSandboxProviderAuth": ".daytona_sandbox_provider_auth",
"DeleteAgentResponse": ".delete_agent_response",
+ "DeleteSandboxEnvironmentResponse": ".delete_sandbox_environment_response",
"DeleteScheduleResponse": ".delete_schedule_response",
"DynamicSubAgentsConfig": ".dynamic_sub_agents_config",
"ExtendedChunkDeltaToolCall": ".extended_chunk_delta_tool_call",
@@ -334,6 +346,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"GetMeSubject": ".get_me_subject",
"GetModelProviderCatalogResponse": ".get_model_provider_catalog_response",
"GetModelProviderResponse": ".get_model_provider_response",
+ "GetSandboxEnvironmentResponse": ".get_sandbox_environment_response",
"GetSandboxProviderCatalogResponse": ".get_sandbox_provider_catalog_response",
"GetSandboxProviderResponse": ".get_sandbox_provider_response",
"GetScheduleResponse": ".get_schedule_response",
@@ -360,6 +373,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ListModelProvidersResponse": ".list_model_providers_response",
"ListPermissionsData": ".list_permissions_data",
"ListPermissionsResponse": ".list_permissions_response",
+ "ListSandboxEnvironmentsResponse": ".list_sandbox_environments_response",
"ListScheduleRunsResponse": ".list_schedule_runs_response",
"ListSchedulesResponse": ".list_schedules_response",
"ListSessionEventsResponse": ".list_session_events_response",
@@ -424,6 +438,14 @@ _dynamic_imports: typing.Dict[str, str] = {
"SandboxCapability": ".sandbox_capability",
"SandboxConfig": ".sandbox_config",
"SandboxCreatedEvent": ".sandbox_created_event",
+ "SandboxEnvironment": ".sandbox_environment",
+ "SandboxEnvironmentImage": ".sandbox_environment_image",
+ "SandboxEnvironmentLifecycleStage": ".sandbox_environment_lifecycle_stage",
+ "SandboxEnvironmentManifest": ".sandbox_environment_manifest",
+ "SandboxEnvironmentNetworking": ".sandbox_environment_networking",
+ "SandboxEnvironmentResources": ".sandbox_environment_resources",
+ "SandboxEnvironmentSecret": ".sandbox_environment_secret",
+ "SandboxEnvironmentVersionStatus": ".sandbox_environment_version_status",
"SandboxProviderManifest": ".sandbox_provider_manifest",
"Schedule": ".schedule",
"ScheduleManifest": ".schedule_manifest",
@@ -595,6 +617,7 @@ __all__ = [
"CustomModelProvider",
"DaytonaSandboxProviderAuth",
"DeleteAgentResponse",
+ "DeleteSandboxEnvironmentResponse",
"DeleteScheduleResponse",
"DynamicSubAgentsConfig",
"ExtendedChunkDeltaToolCall",
@@ -612,6 +635,7 @@ __all__ = [
"GetMeSubject",
"GetModelProviderCatalogResponse",
"GetModelProviderResponse",
+ "GetSandboxEnvironmentResponse",
"GetSandboxProviderCatalogResponse",
"GetSandboxProviderResponse",
"GetScheduleResponse",
@@ -638,6 +662,7 @@ __all__ = [
"ListModelProvidersResponse",
"ListPermissionsData",
"ListPermissionsResponse",
+ "ListSandboxEnvironmentsResponse",
"ListScheduleRunsResponse",
"ListSchedulesResponse",
"ListSessionEventsResponse",
@@ -702,6 +727,14 @@ __all__ = [
"SandboxCapability",
"SandboxConfig",
"SandboxCreatedEvent",
+ "SandboxEnvironment",
+ "SandboxEnvironmentImage",
+ "SandboxEnvironmentLifecycleStage",
+ "SandboxEnvironmentManifest",
+ "SandboxEnvironmentNetworking",
+ "SandboxEnvironmentResources",
+ "SandboxEnvironmentSecret",
+ "SandboxEnvironmentVersionStatus",
"SandboxProviderManifest",
"Schedule",
"ScheduleManifest",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/delete_sandbox_environment_response.py b/python/trueforge_sdk/src/trueforge_sdk/types/delete_sandbox_environment_response.py
new file mode 100644
index 000000000..11de44ee7
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/delete_sandbox_environment_response.py
@@ -0,0 +1,17 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class DeleteSandboxEnvironmentResponse(UncheckedBaseModel):
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/get_sandbox_environment_response.py b/python/trueforge_sdk/src/trueforge_sdk/types/get_sandbox_environment_response.py
new file mode 100644
index 000000000..9bb4ff8b9
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/get_sandbox_environment_response.py
@@ -0,0 +1,20 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .sandbox_environment import SandboxEnvironment
+
+
+class GetSandboxEnvironmentResponse(UncheckedBaseModel):
+ data: SandboxEnvironment
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/list_sandbox_environments_response.py b/python/trueforge_sdk/src/trueforge_sdk/types/list_sandbox_environments_response.py
new file mode 100644
index 000000000..1f93f47e8
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/list_sandbox_environments_response.py
@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .sandbox_environment import SandboxEnvironment
+from .token_pagination import TokenPagination
+
+
+class ListSandboxEnvironmentsResponse(UncheckedBaseModel):
+ data: typing.List[SandboxEnvironment]
+ pagination: TokenPagination
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py
index d3e7b3ae5..a4e9e4589 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py
@@ -13,6 +13,11 @@ class SandboxConfig(UncheckedBaseModel):
Give the agent a sandbox. Required for skills and Code Mode.
"""
+ environment_name: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Name of a configured sandbox environment to use. Must exist when set.
+ """
+
file_downloads: typing.Optional[bool] = pydantic.Field(default=True)
"""
Allow downloading agent-produced files via the turn download endpoint. Default: true.
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment.py
new file mode 100644
index 000000000..d456f2de2
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment.py
@@ -0,0 +1,53 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .created_by_subject import CreatedBySubject
+from .resource_name import ResourceName
+from .sandbox_environment_lifecycle_stage import SandboxEnvironmentLifecycleStage
+from .sandbox_environment_manifest import SandboxEnvironmentManifest
+from .sandbox_environment_version_status import SandboxEnvironmentVersionStatus
+
+
+class SandboxEnvironment(UncheckedBaseModel):
+ created_at: dt.datetime = pydantic.Field()
+ """
+ ISO-8601 create time.
+ """
+
+ created_by_subject: CreatedBySubject
+ description: str = pydantic.Field()
+ """
+ Human-readable description; empty when unset.
+ """
+
+ id: str = pydantic.Field()
+ """
+ Immutable server-generated environment identifier.
+ """
+
+ lifecycle_stage: SandboxEnvironmentLifecycleStage
+ manifest: SandboxEnvironmentManifest
+ name: ResourceName
+ status: SandboxEnvironmentVersionStatus
+ status_reason: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Failure detail when status is failed; null otherwise.
+ """
+
+ updated_at: dt.datetime = pydantic.Field()
+ """
+ ISO-8601 last update time.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_image.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_image.py
new file mode 100644
index 000000000..6d1b3cfa5
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_image.py
@@ -0,0 +1,27 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class SandboxEnvironmentImage(UncheckedBaseModel):
+ build_script: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Shell script used to build the snapshot.
+ """
+
+ type: typing.Literal["build"] = pydantic.Field(default="build")
+ """
+ Build a snapshot from a script.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_lifecycle_stage.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_lifecycle_stage.py
new file mode 100644
index 000000000..ca0f822a3
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_lifecycle_stage.py
@@ -0,0 +1,38 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core import enum
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class SandboxEnvironmentLifecycleStage(enum.StrEnum):
+ """
+ Soft-delete lifecycle stage.
+ """
+
+ ACTIVE = "active"
+ DELETED = "deleted"
+ _UNKNOWN = "__SANDBOXENVIRONMENTLIFECYCLESTAGE_UNKNOWN__"
+ """
+ This member is used for forward compatibility. If the value is not recognized by the enum, it will be stored here, and the raw value is accessible through `.value`.
+ """
+
+ @classmethod
+ def _missing_(cls, value: typing.Any) -> "SandboxEnvironmentLifecycleStage":
+ unknown = cls._UNKNOWN
+ unknown._value_ = value
+ return unknown
+
+ def visit(
+ self,
+ active: typing.Callable[[], T_Result],
+ deleted: typing.Callable[[], T_Result],
+ _unknown_member: typing.Callable[[str], T_Result],
+ ) -> T_Result:
+ if self is SandboxEnvironmentLifecycleStage.ACTIVE:
+ return active()
+ if self is SandboxEnvironmentLifecycleStage.DELETED:
+ return deleted()
+ return _unknown_member(self._value_)
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest.py
new file mode 100644
index 000000000..2119d2517
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest.py
@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .resource_name import ResourceName
+from .sandbox_environment_image import SandboxEnvironmentImage
+from .sandbox_environment_networking import SandboxEnvironmentNetworking
+from .sandbox_environment_resources import SandboxEnvironmentResources
+
+
+class SandboxEnvironmentManifest(UncheckedBaseModel):
+ description: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Optional human-readable description.
+ """
+
+ environment_variables: typing.Optional[typing.Dict[str, str]] = None
+ image: typing.Optional[SandboxEnvironmentImage] = None
+ name: ResourceName
+ networking: typing.Optional[SandboxEnvironmentNetworking] = None
+ resources: typing.Optional[SandboxEnvironmentResources] = None
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_networking.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_networking.py
new file mode 100644
index 000000000..cf04c7d44
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_networking.py
@@ -0,0 +1,33 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .sandbox_environment_secret import SandboxEnvironmentSecret
+
+
+class SandboxEnvironmentNetworking(UncheckedBaseModel):
+ domain_allow_list: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Comma-separated allowed domains.
+ """
+
+ network_block_all: typing.Optional[bool] = pydantic.Field(default=None)
+ """
+ Block all outbound network access. When true, domain_allow_list and secrets are not used.
+ """
+
+ secrets: typing.Optional[typing.List[SandboxEnvironmentSecret]] = pydantic.Field(default=None)
+ """
+ Network-scoped secrets.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_resources.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_resources.py
new file mode 100644
index 000000000..74f0491f1
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_resources.py
@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class SandboxEnvironmentResources(UncheckedBaseModel):
+ cpu: typing.Optional[float] = pydantic.Field(default=1.0)
+ """
+ CPU allocation in cores.
+ """
+
+ disk: typing.Optional[float] = pydantic.Field(default=3.0)
+ """
+ Disk allocation in GiB.
+ """
+
+ memory: typing.Optional[float] = pydantic.Field(default=1.0)
+ """
+ Memory allocation in GiB.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_secret.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_secret.py
new file mode 100644
index 000000000..55641113d
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_secret.py
@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class SandboxEnvironmentSecret(UncheckedBaseModel):
+ env: str = pydantic.Field()
+ """
+ Environment variable name injected into the sandbox.
+ """
+
+ hosts: typing.List[str] = pydantic.Field()
+ """
+ Hosts this secret may be sent to.
+ """
+
+ value: str = pydantic.Field()
+ """
+ Secret value; GET responses use a redacted stand-in.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py
new file mode 100644
index 000000000..c354f4825
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py
@@ -0,0 +1,42 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core import enum
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class SandboxEnvironmentVersionStatus(enum.StrEnum):
+ """
+ Readiness of the environment.
+ """
+
+ PENDING = "pending"
+ ACTIVE = "active"
+ FAILED = "failed"
+ _UNKNOWN = "__SANDBOXENVIRONMENTVERSIONSTATUS_UNKNOWN__"
+ """
+ This member is used for forward compatibility. If the value is not recognized by the enum, it will be stored here, and the raw value is accessible through `.value`.
+ """
+
+ @classmethod
+ def _missing_(cls, value: typing.Any) -> "SandboxEnvironmentVersionStatus":
+ unknown = cls._UNKNOWN
+ unknown._value_ = value
+ return unknown
+
+ def visit(
+ self,
+ pending: typing.Callable[[], T_Result],
+ active: typing.Callable[[], T_Result],
+ failed: typing.Callable[[], T_Result],
+ _unknown_member: typing.Callable[[str], T_Result],
+ ) -> T_Result:
+ if self is SandboxEnvironmentVersionStatus.PENDING:
+ return pending()
+ if self is SandboxEnvironmentVersionStatus.ACTIVE:
+ return active()
+ if self is SandboxEnvironmentVersionStatus.FAILED:
+ return failed()
+ return _unknown_member(self._value_)