Secure, Fast, and Extensible Sandbox runtime for AI agents.
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
import type { ConnectionConfig } from "../config/connection.js";
import type { SandboxId } from "../models/sandboxes.js";
import type { SandboxFiles } from "../services/filesystem.js";
import type { CredentialVault, Egress } from "../services/egress.js";
import type { ExecdCommands } from "../services/execdCommands.js";
import type { ExecdHealth } from "../services/execdHealth.js";
import type { ExecdMetrics } from "../services/execdMetrics.js";
import type { IsolationService } from "../services/isolatedSessions.js";
import type { Sandboxes } from "../services/sandboxes.js";
import type { Diagnostics } from "../services/diagnostics.js";
export interface CreateLifecycleStackOptions {
connectionConfig: ConnectionConfig;
lifecycleBaseUrl: string;
}
export interface LifecycleStack {
sandboxes: Sandboxes;
diagnostics?: Diagnostics;
}
export interface CreateExecdStackOptions {
connectionConfig: ConnectionConfig;
execdBaseUrl: string;
endpointHeaders?: Record<string, string>;
}
export interface ExecdStack {
commands: ExecdCommands;
files: SandboxFiles;
health: ExecdHealth;
metrics: ExecdMetrics;
isolation?: IsolationService;
}
export interface CreateEgressStackOptions {
connectionConfig: ConnectionConfig;
egressBaseUrl: string;
endpointHeaders?: Record<string, string>;
}
export interface EgressStack {
egress: Egress;
credentialVault?: CredentialVault;
}
export interface CreateNetworkPolicyStackOptions {
connectionConfig: ConnectionConfig;
lifecycleBaseUrl: string;
sandboxId: SandboxId;
}
/**
* Factory abstraction to keep `Sandbox` and `SandboxManager` decoupled from concrete adapter implementations.
*
* This is primarily useful for advanced integrations (custom transports, dependency injection, testing).
*/
export interface AdapterFactory {
createLifecycleStack(opts: CreateLifecycleStackOptions): LifecycleStack;
createExecdStack(opts: CreateExecdStackOptions): ExecdStack;
createEgressStack(opts: CreateEgressStackOptions): EgressStack;
/**
* Create an egress stack that routes policy operations through the lifecycle
* control plane (`/sandboxes/{sandboxId}/networkpolicy`) instead of the
* sandbox-side egress sidecar.
*
* Used for template-backed sandboxes, which have no sandbox-side sidecar.
* Optional: custom adapter factories may omit it, in which case template
* backed sandboxes fail fast when egress policy operations are attempted.
*/
createNetworkPolicyStack?(opts: CreateNetworkPolicyStackOptions): EgressStack;
}