Skip to content

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

Add environment table along with dummy APIs (#884)

Sujai Kumar Guptac0235178fe4e
diff --git a/.changeset/sandbox-environments-dummy.md b/.changeset/sandbox-environments-dummy.md
new file mode 100644
index 000000000..d40980440
--- /dev/null
+++ b/.changeset/sandbox-environments-dummy.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge': patch
+---
+
+Add sandbox_environment / sandbox_environment_version tables and dummy CRUD APIs at `/api/v1/sandbox-environments`.
diff --git a/packages/trueforge/src/apis/sandboxEnvironments.ts b/packages/trueforge/src/apis/sandboxEnvironments.ts
new file mode 100644
index 000000000..9039e3948
--- /dev/null
+++ b/packages/trueforge/src/apis/sandboxEnvironments.ts
@@ -0,0 +1,107 @@
+/**
+ * Sandbox environments API (mounted at /api/v1/sandbox-environments).
+ * Handlers return properly shaped dummy data; no DB persistence yet.
+ * OpenAPI / Fern registration intentionally deferred.
+ */
+import { OpenAPIHono, z } from '@hono/zod-openapi';
+import type { Context } from 'hono';
+import { PAGE_LIMIT } from '../schemas/common';
+import {
+ CreateSandboxEnvironmentRequestSchema,
+ UpdateSandboxEnvironmentRequestSchema,
+ type SandboxEnvironment,
+ type SandboxEnvironmentManifest,
+} from '../schemas/sandboxEnvironment';
+import { zodErrorResponse } from '../zodErrorResponse';
+
+const DUMMY_CREATED_AT = '2026-09-26T00:00:00.000Z';
+
+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'] }],
+ },
+};
+
+function dummyEnvironment(manifest: SandboxEnvironmentManifest = DUMMY_BASE_MANIFEST): SandboxEnvironment {
+ 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,
+ };
+}
+
+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 };
+}
+
+/** Dummy CRUD for sandbox environments (no OpenAPI registration yet). */
+export function createSandboxEnvironmentsRouter(): OpenAPIHono {
+ const router = new OpenAPIHono();
+
+ router.get('/', c => {
+ return c.json({
+ data: [dummyEnvironment()],
+ pagination: { limit: PAGE_LIMIT },
+ });
+ });
+
+ router.get('/:name', c => {
+ return c.json({ data: dummyEnvironment() });
+ });
+
+ router.post('/', async c => {
+ const body = await validateJsonBody(c, CreateSandboxEnvironmentRequestSchema);
+ if (!body.ok) {
+ return body.response;
+ }
+ return c.json({ data: dummyEnvironment(body.data.manifest) }, 201);
+ });
+
+ router.put('/:name', async c => {
+ const body = await validateJsonBody(c, UpdateSandboxEnvironmentRequestSchema);
+ if (!body.ok) {
+ return body.response;
+ }
+ return c.json({ data: dummyEnvironment(body.data.manifest) });
+ });
+
+ router.delete('/:name', c => {
+ return c.json({});
+ });
+
+ return router;
+}
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index e3a0c67c7..99c47a44f 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -18,6 +18,7 @@ import { createMcpOAuthRouter } from './apis/mcpOAuth';
import { createMcpServersRouter } from './apis/mcpServers';
import { createModelsRouter } from './apis/models';
import { createPermissionsRouter } from './apis/permissions';
+import { createSandboxEnvironmentsRouter } from './apis/sandboxEnvironments';
import { createScheduleExecutionRouter, createSchedulesRouter } from './apis/schedules';
import { createInternalMetricsRouter } from './apis/sessionMetrics';
import { createInternalSessionsRouter, createSessionsRouter } from './apis/sessions';
@@ -350,6 +351,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
authMiddleware,
),
);
+ app.route('/api/v1/sandbox-environments', withAuth(createSandboxEnvironmentsRouter(), authMiddleware));
app.route(
'/api/internal/schedules',
withAuth(createScheduleExecutionRouter(scheduleTurnDeps), scheduleExecutionAuthMiddleware),
diff --git a/packages/trueforge/src/db/indexes.ts b/packages/trueforge/src/db/indexes.ts
index 36eefa9ee..69291752c 100644
--- a/packages/trueforge/src/db/indexes.ts
+++ b/packages/trueforge/src/db/indexes.ts
@@ -27,3 +27,12 @@ export const SCHEDULE_AGENT_ID_IDX = 'schedule_agent_id_idx';
/** `(tenant_id, created_by_subject.subject_id)` on schedule_run. */
export const SCHEDULE_RUN_CREATED_BY_SUBJECT_ID_IDX = 'schedule_run_created_by_subject_id_idx';
+
+/** Partial unique `(tenant_id, name) WHERE lifecycle_stage = 'active'` on sandbox_environment. */
+export const SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ = 'sandbox_environment_tenant_name_active_uq';
+
+/** Unique `(environment_id, version)` on sandbox_environment_version. */
+export const SANDBOX_ENVIRONMENT_VERSION_UQ = 'sandbox_environment_version_uq';
+
+/** `(tenant_id, created_by_subject.subject_id)` on sandbox_environment. */
+export const SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX = 'sandbox_environment_created_by_subject_id_idx';
diff --git a/packages/trueforge/src/db/postgres/migrations/20260926_000001_sandbox_environment.ts b/packages/trueforge/src/db/postgres/migrations/20260926_000001_sandbox_environment.ts
new file mode 100644
index 000000000..54b6ac4ec
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260926_000001_sandbox_environment.ts
@@ -0,0 +1,73 @@
+import { sql, type Kysely } from 'kysely';
+import {
+ SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX,
+ SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ,
+ SANDBOX_ENVIRONMENT_VERSION_UQ,
+} from '../../indexes';
+
+/**
+ * Versioned sandbox environments: parent row + immutable version rows.
+ *
+ * - Partial unique (tenant_id, name) among lifecycle_stage = 'active' (soft-delete reclaim).
+ * - Unique (environment_id, version) on version children.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+
+ await db.schema
+ .createTable('sandbox_environment')
+ .addColumn('id', 'text', col => col.notNull())
+ .addColumn('tenant_id', 'text', col => col.notNull())
+ .addColumn('name', 'text', col => col.notNull())
+ .addColumn('description', 'text', col => col.notNull())
+ .addColumn('active_version', 'integer', col => col.notNull())
+ .addColumn('lifecycle_stage', 'text', col => col.notNull())
+ .addColumn('created_by_subject', 'jsonb', col => col.notNull())
+ .addColumn('created_at', 'timestamptz', col => col.notNull())
+ .addColumn('updated_at', 'timestamptz', col => col.notNull())
+ .addPrimaryKeyConstraint('sandbox_environment_pkey', ['id'])
+ .execute();
+
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw(SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)}
+ ON sandbox_environment (tenant_id, name)
+ WHERE lifecycle_stage = 'active'
+ `.execute(db);
+
+ await sql`
+ CREATE INDEX ${sql.raw(SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX)}
+ ON sandbox_environment (tenant_id, (created_by_subject->>'subject_id'))
+ `.execute(db);
+
+ await db.schema
+ .createTable('sandbox_environment_version')
+ .addColumn('id', 'text', col => col.notNull())
+ .addColumn('environment_id', 'text', col => col.notNull())
+ .addColumn('version', 'integer', col => col.notNull())
+ .addColumn('manifest', 'jsonb', col => col.notNull())
+ .addColumn('status', 'text', col => col.notNull())
+ .addColumn('status_reason', 'text')
+ .addColumn('external_ref', 'text', col => col.notNull())
+ .addColumn('internal_metadata', 'jsonb', col => col.notNull())
+ .addColumn('created_by_subject', 'jsonb', col => col.notNull())
+ .addColumn('created_at', 'timestamptz', col => col.notNull())
+ .addColumn('updated_at', 'timestamptz', col => col.notNull())
+ .addPrimaryKeyConstraint('sandbox_environment_version_pkey', ['id'])
+ .addUniqueConstraint(SANDBOX_ENVIRONMENT_VERSION_UQ, ['environment_id', 'version'])
+ .addForeignKeyConstraint(
+ 'sandbox_environment_version_environment_id_fkey',
+ ['environment_id'],
+ 'sandbox_environment',
+ ['id'],
+ cb => cb.onDelete('cascade'),
+ )
+ .execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.dropTable('sandbox_environment_version').ifExists().execute();
+ await sql`DROP INDEX IF EXISTS ${sql.raw(SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX)}`.execute(db);
+ await sql`DROP INDEX IF EXISTS ${sql.raw(SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)}`.execute(db);
+ await db.schema.dropTable('sandbox_environment').ifExists().execute();
+}
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 1dbeabf1a..2946c9737 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -26,6 +26,12 @@ import type { CurrentContextUsage } from '@truefoundry/trueforge-core/core/runti
import type { ColumnType, Generated, JSONColumnType } from 'kysely';
import type { McpServerManifest } from '../../schemas/mcpServer';
import type { ModelProviderManifest } from '../../schemas/modelProvider';
+import type {
+ SandboxEnvironmentLifecycleStage,
+ SandboxEnvironmentVersionInternalMetadata,
+ SandboxEnvironmentVersionStatus,
+ StoredSandboxEnvironmentManifest,
+} from '../../schemas/sandboxEnvironment';
import type {
SandboxBuildMetadata,
SandboxBuildStatus,
@@ -422,6 +428,48 @@ export interface AgentTable {
updated_at: Date;
}
+/**
+ * Sandbox environments — immutable ULID `id` PK.
+ * Partial unique (tenant_id, name) WHERE lifecycle_stage = 'active'.
+ */
+export interface SandboxEnvironmentTable {
+ id: string;
+ tenant_id: string;
+ name: string;
+ description: string;
+ active_version: number;
+ lifecycle_stage: SandboxEnvironmentLifecycleStage;
+ created_by_subject: JSONColumnType<CreatedBySubject, CreatedBySubject, CreatedBySubject>;
+ created_at: Date;
+ updated_at: Date;
+}
+
+/**
+ * Immutable sandbox environment versions.
+ * UNIQUE (environment_id, version); FK → sandbox_environment ON DELETE CASCADE.
+ */
+export interface SandboxEnvironmentVersionTable {
+ id: string;
+ environment_id: string;
+ version: number;
+ manifest: JSONColumnType<
+ StoredSandboxEnvironmentManifest,
+ StoredSandboxEnvironmentManifest,
+ StoredSandboxEnvironmentManifest
+ >;
+ status: SandboxEnvironmentVersionStatus;
+ status_reason: string | null;
+ external_ref: string;
+ internal_metadata: JSONColumnType<
+ SandboxEnvironmentVersionInternalMetadata,
+ SandboxEnvironmentVersionInternalMetadata,
+ SandboxEnvironmentVersionInternalMetadata
+ >;
+ created_by_subject: JSONColumnType<CreatedBySubject, CreatedBySubject, CreatedBySubject>;
+ created_at: Date;
+ updated_at: Date;
+}
+
/**
* Configured schedules — immutable ULID `id` PK.
* PRIMARY KEY (id)
@@ -556,6 +604,8 @@ export interface Database {
skill: SkillTable;
sandbox_provider: SandboxProviderTable;
agent: AgentTable;
+ sandbox_environment: SandboxEnvironmentTable;
+ sandbox_environment_version: SandboxEnvironmentVersionTable;
schedule: ScheduleTable;
schedule_run: ScheduleRunTable;
mcp_server: McpServerTable;
diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.ts
index ce6dc9407..cb416bc18 100644
--- a/packages/trueforge/src/db/sqlite/client.ts
+++ b/packages/trueforge/src/db/sqlite/client.ts
@@ -144,6 +144,7 @@ const JSON_RESULT_COLUMNS = new Set([
'payload',
'manifest',
'metadata',
+ 'internal_metadata',
'build_metadata',
'oauth_server',
'oauth_client',
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260926_000001_sandbox_environment.ts b/packages/trueforge/src/db/sqlite/migrations/20260926_000001_sandbox_environment.ts
new file mode 100644
index 000000000..4b79da576
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260926_000001_sandbox_environment.ts
@@ -0,0 +1,77 @@
+import { sql, type Kysely } from 'kysely';
+import {
+ SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX,
+ SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ,
+ SANDBOX_ENVIRONMENT_VERSION_UQ,
+} from '../../indexes';
+
+/**
+ * Versioned sandbox environments for SQLite (mirrors Postgres).
+ * STRICT tables; jsonb as BLOB; timestamps as ISO TEXT.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`
+ CREATE TABLE sandbox_environment (
+ id TEXT NOT NULL,
+ tenant_id TEXT NOT NULL,
+ name TEXT NOT NULL,
+ description TEXT NOT NULL,
+ active_version INTEGER NOT NULL,
+ lifecycle_stage TEXT NOT NULL,
+ created_by_subject BLOB NOT NULL,
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (id)
+ ) STRICT
+ `.execute(trx);
+
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw(SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)}
+ ON sandbox_environment (tenant_id, name)
+ WHERE lifecycle_stage = 'active'
+ `.execute(trx);
+
+ await sql`
+ CREATE INDEX ${sql.raw(SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX)}
+ ON sandbox_environment (tenant_id, json_extract(created_by_subject, '$.subject_id'))
+ `.execute(trx);
+
+ await sql`
+ CREATE TABLE sandbox_environment_version (
+ id TEXT NOT NULL,
+ environment_id TEXT NOT NULL,
+ version INTEGER NOT NULL,
+ manifest BLOB NOT NULL,
+ status TEXT NOT NULL,
+ status_reason TEXT,
+ external_ref TEXT NOT NULL,
+ internal_metadata BLOB NOT NULL,
+ created_by_subject BLOB NOT NULL,
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (id),
+ FOREIGN KEY (environment_id) REFERENCES sandbox_environment (id) ON DELETE CASCADE
+ ) STRICT
+ `.execute(trx);
+
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw(SANDBOX_ENVIRONMENT_VERSION_UQ)}
+ ON sandbox_environment_version (environment_id, version)
+ `.execute(trx);
+ });
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`PRAGMA foreign_keys = OFF`.execute(db);
+ try {
+ await db.transaction().execute(async trx => {
+ await sql`DROP TABLE IF EXISTS sandbox_environment_version`.execute(trx);
+ await sql`DROP INDEX IF EXISTS ${sql.raw(SANDBOX_ENVIRONMENT_CREATED_BY_SUBJECT_ID_IDX)}`.execute(trx);
+ await sql`DROP INDEX IF EXISTS ${sql.raw(SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)}`.execute(trx);
+ await sql`DROP TABLE IF EXISTS sandbox_environment`.execute(trx);
+ });
+ } finally {
+ await sql`PRAGMA foreign_keys = ON`.execute(db);
+ }
+}
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index 70ca6f716..e413e25ae 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -29,6 +29,12 @@ import type { CurrentContextUsage } from '@truefoundry/trueforge-core/core/runti
import type { ColumnType, Generated, JSONColumnType } from 'kysely';
import type { McpServerManifest } from '../../schemas/mcpServer';
import type { ModelProviderManifest } from '../../schemas/modelProvider';
+import type {
+ SandboxEnvironmentLifecycleStage,
+ SandboxEnvironmentVersionInternalMetadata,
+ SandboxEnvironmentVersionStatus,
+ StoredSandboxEnvironmentManifest,
+} from '../../schemas/sandboxEnvironment';
import type {
SandboxBuildMetadata,
SandboxBuildStatus,
@@ -267,6 +273,40 @@ export interface AgentTable {
updated_at: string;
}
+/**
+ * Sandbox environments — mirrors Postgres `sandbox_environment`.
+ * Partial unique (tenant_id, name) WHERE lifecycle_stage = 'active'.
+ */
+export interface SandboxEnvironmentTable {
+ id: string;
+ tenant_id: string;
+ name: string;
+ description: string;
+ active_version: number;
+ lifecycle_stage: SandboxEnvironmentLifecycleStage;
+ created_by_subject: JsonbColumn<CreatedBySubject>;
+ created_at: string;
+ updated_at: string;
+}
+
+/**
+ * Immutable sandbox environment versions — mirrors Postgres.
+ * UNIQUE (environment_id, version); FK → sandbox_environment ON DELETE CASCADE.
+ */
+export interface SandboxEnvironmentVersionTable {
+ id: string;
+ environment_id: string;
+ version: number;
+ manifest: JsonbColumn<StoredSandboxEnvironmentManifest>;
+ status: SandboxEnvironmentVersionStatus;
+ status_reason: string | null;
+ external_ref: string;
+ internal_metadata: JsonbColumn<SandboxEnvironmentVersionInternalMetadata>;
+ created_by_subject: JsonbColumn<CreatedBySubject>;
+ created_at: string;
+ updated_at: string;
+}
+
/**
* Configured schedules.
* PRIMARY KEY (id).
@@ -377,6 +417,8 @@ export interface Database {
skill: SkillTable;
sandbox_provider: SandboxProviderTable;
agent: AgentTable;
+ sandbox_environment: SandboxEnvironmentTable;
+ sandbox_environment_version: SandboxEnvironmentVersionTable;
schedule: ScheduleTable;
schedule_run: ScheduleRunTable;
mcp_server: McpServerTable;
diff --git a/packages/trueforge/src/schemas/sandboxEnvironment.ts b/packages/trueforge/src/schemas/sandboxEnvironment.ts
new file mode 100644
index 000000000..c8e741544
--- /dev/null
+++ b/packages/trueforge/src/schemas/sandboxEnvironment.ts
@@ -0,0 +1,199 @@
+/**
+ * Sandbox environment domain + wire schemas: identity columns plus a nested
+ * SandboxEnvironmentManifest document (JSON key `manifest`).
+ *
+ * `type` / `sandbox_provider` are backend-only on the stored jsonb — omitted from
+ * request and response wire shapes.
+ */
+import { z } from '@hono/zod-openapi';
+import { CreatedBySubjectSchema, TokenPaginationSchema } from '@truefoundry/trueforge-core/agent-session';
+import { NameSchema } from './common';
+
+export const SANDBOX_ENVIRONMENT_DESCRIPTION_MAX_LENGTH = 1024;
+
+const BUILD_SCRIPT_EXAMPLE = 'set -ex\npip install httpx\n';
+
+export const SandboxEnvironmentDescriptionSchema = z
+ .string()
+ .trim()
+ .max(SANDBOX_ENVIRONMENT_DESCRIPTION_MAX_LENGTH)
+ .describe('Optional human-readable description.');
+
+export const SandboxEnvironmentLifecycleStageSchema = z
+ .enum(['active', 'deleted'])
+ .describe('Soft-delete lifecycle stage.')
+ .openapi('SandboxEnvironmentLifecycleStage');
+
+export const SandboxEnvironmentVersionStatusSchema = z
+ .enum(['pending', 'active', 'failed'])
+ .describe('Build/activation status of an environment version.')
+ .openapi('SandboxEnvironmentVersionStatus');
+
+/** Single image variant today; widen with discriminatedUnion when another type lands. */
+export const SandboxEnvironmentImageSchema = z
+ .object({
+ type: z.literal('build').describe('Build a snapshot from a script.'),
+ build_script: z.string().min(1).optional().openapi({
+ description: 'Shell script used to build the snapshot.',
+ example: BUILD_SCRIPT_EXAMPLE,
+ }),
+ })
+ .strict()
+ .openapi('SandboxEnvironmentImage');
+
+export const SandboxEnvironmentResourcesSchema = z
+ .object({
+ cpu: z.number().positive().default(1).describe('CPU allocation in cores.'),
+ memory: z.number().positive().default(1).describe('Memory allocation in GiB.'),
+ disk: z.number().positive().default(3).describe('Disk allocation in GiB.'),
+ })
+ .strict()
+ .openapi('SandboxEnvironmentResources');
+
+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.'),
+ hosts: z.array(z.string().min(1)).describe('Hosts this secret may be sent to.'),
+ })
+ .strict()
+ .openapi('SandboxEnvironmentSecret');
+
+export const SandboxEnvironmentNetworkingSchema = z
+ .object({
+ network_block_all: z
+ .boolean()
+ .optional()
+ .describe('Block all outbound network access. When true, domain_allow_list and secrets are not used.'),
+ domain_allow_list: z.string().min(1).optional().describe('Comma-separated allowed domains.'),
+ secrets: z.array(SandboxEnvironmentSecretSchema).optional().describe('Network-scoped secrets.'),
+ })
+ .strict()
+ .superRefine((value, ctx) => {
+ if (value.network_block_all !== true) {
+ return;
+ }
+ if (value.domain_allow_list !== undefined) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['domain_allow_list'],
+ message: 'domain_allow_list is not allowed when network_block_all is true',
+ });
+ }
+ if (value.secrets !== undefined) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['secrets'],
+ message: 'secrets is not allowed when network_block_all is true',
+ });
+ }
+ })
+ .openapi('SandboxEnvironmentNetworking');
+
+/** Wire + request/response document — no `type` / `sandbox_provider`. */
+export const SandboxEnvironmentManifestSchema = z
+ .object({
+ name: NameSchema,
+ description: SandboxEnvironmentDescriptionSchema.optional(),
+ image: SandboxEnvironmentImageSchema.optional(),
+ resources: SandboxEnvironmentResourcesSchema.default({ cpu: 1, memory: 1, disk: 3 }),
+ environment_variables: z.record(z.string().min(1), z.string()).optional(),
+ networking: SandboxEnvironmentNetworkingSchema.optional(),
+ })
+ .strict()
+ .openapi('SandboxEnvironmentManifest');
+
+/**
+ * Persisted version jsonb — wire fields plus backend-resolved provider identity.
+ * Not exposed on request/response wire types.
+ */
+export const StoredSandboxEnvironmentManifestSchema = z
+ .object({
+ ...SandboxEnvironmentManifestSchema.shape,
+ type: z.enum(['daytona', 'truefoundry']),
+ sandbox_provider: z.enum(['daytona', 'truefoundry']),
+ })
+ .strict();
+
+export const SandboxEnvironmentVersionSecretSchema = z
+ .object({
+ key: z.string().min(1).describe('Env var name.'),
+ id: z.string().min(1).describe('Secret store reference id.'),
+ })
+ .strict();
+
+/** 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.'),
+ })
+ .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');
+
+export const UpdateSandboxEnvironmentRequestSchema = z
+ .object({
+ manifest: SandboxEnvironmentManifestSchema,
+ })
+ .strict()
+ .openapi('UpdateSandboxEnvironmentRequest');
+
+const IsoTimestamp = z.iso.datetime().openapi({ type: 'string', format: 'date-time' });
+
+export const SandboxEnvironmentSchema = z
+ .object({
+ 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,
+ 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.'),
+ })
+ .strict()
+ .openapi('SandboxEnvironment');
+
+export const GetSandboxEnvironmentResponseSchema = z
+ .object({ data: SandboxEnvironmentSchema })
+ .openapi('GetSandboxEnvironmentResponse');
+
+export const ListSandboxEnvironmentsResponseSchema = z
+ .object({
+ data: z.array(SandboxEnvironmentSchema),
+ pagination: TokenPaginationSchema,
+ })
+ .openapi('ListSandboxEnvironmentsResponse');
+
+export const DeleteSandboxEnvironmentResponseSchema = z.object({}).openapi('DeleteSandboxEnvironmentResponse');
+
+export type SandboxEnvironmentLifecycleStage = z.infer<typeof SandboxEnvironmentLifecycleStageSchema>;
+export type SandboxEnvironmentVersionStatus = z.infer<typeof SandboxEnvironmentVersionStatusSchema>;
+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>;