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.
export interface IsolatedWorkspaceSpec {
path: string;
mode?: "rw" | "overlay" | "ro";
}
export interface IsolatedOverlaySpec {
/** Mount destination inside the namespace (absolute). */
path: string;
/** Mount mode. Defaults to "overlay". */
mode?: "rw" | "overlay" | "ro";
/** Overlay mode only. Defaults to true; false uses an ephemeral tmpfs upper. */
persist?: boolean;
}
export interface EnvPassthroughSpec {
mode?: "allow" | "deny";
keys?: string[];
}
export interface BindMount {
source: string;
dest?: string;
readonly?: boolean;
}
export interface CreateIsolatedSessionRequest {
/** Legacy sugar, prepended to `overlays`; at least one is required. */
workspace?: IsolatedWorkspaceSpec;
/** Independent overlay mounts inside one namespace. */
overlays?: IsolatedOverlaySpec[];
profile?: "strict" | "balanced";
extra_writable?: string[];
binds?: BindMount[];
share_net?: boolean;
env_passthrough?: EnvPassthroughSpec;
uid?: number;
gid?: number;
uid_mode?: "setpriv" | "userns";
idle_timeout_seconds?: number;
}
export interface IsolatedSessionInfo {
session_id: string;
created_at: string;
// Creation-parameter fields echoed by execd (may be absent on older builds).
profile?: "strict" | "balanced";
workspace?: IsolatedWorkspaceSpec;
overlays?: IsolatedOverlaySpec[];
extra_writable?: string[];
binds?: BindMount[];
share_net?: boolean;
env_passthrough?: EnvPassthroughSpec;
uid?: number;
gid?: number;
uid_mode?: "setpriv" | "userns";
idle_timeout_seconds?: number;
}
export interface IsolatedSessionState {
status: "active" | "destroyed";
created_at?: string;
last_run_at?: string;
idle_remaining_seconds?: number | null;
// Creation-parameter fields echoed by execd (may be absent on older builds).
// Mirrors IsolatedSessionInfo so callers of session.get() can recover the
// parameters the session was created with — useful for stateless clients
// (e.g. serverless workers) that only persist a session ID.
profile?: "strict" | "balanced";
workspace?: IsolatedWorkspaceSpec;
overlays?: IsolatedOverlaySpec[];
extra_writable?: string[];
binds?: BindMount[];
share_net?: boolean;
env_passthrough?: EnvPassthroughSpec;
uid?: number;
gid?: number;
uid_mode?: "setpriv" | "userns";
idle_timeout_seconds?: number;
}
export interface IsolatedRunOpts {
envs?: Record<string, string>;
timeout_seconds?: number;
}
/**
* Handle returned when a run is started with `background: true`.
*/
export interface IsolatedBackgroundRun {
session_id: string;
run_id: string;
started_at?: string;
}
/**
* Lifecycle state of an isolated background run.
*/
export interface IsolatedRunStatus {
session_id: string;
run_id: string;
running: boolean;
exit_code?: number | null;
error?: string;
started_at?: string;
finished_at?: string | null;
}
/**
* Incremental log read of an isolated background run.
*/
export interface IsolatedRunLogs {
text: string;
cursor: number;
}
export interface HardeningLayerState {
state: "active" | "disabled" | "degraded" | "unsupported" | string;
message?: string;
}
export interface HardeningStatus {
init_mode: "pid1" | "subreaper" | "none" | string;
signal_shield: boolean;
cap_drop?: HardeningLayerState;
seccomp?: HardeningLayerState;
landlock?: HardeningLayerState;
ebpf?: HardeningLayerState;
}
export interface IsolatedCapabilities {
available: boolean;
isolator?: string;
version?: string;
message?: string;
setpriv_available?: boolean;
userns_available?: boolean;
commit_supported: boolean;
diff_supported: boolean;
hardening?: HardeningStatus;
}
export interface IsolatedSessionSummary {
session_id: string;
status: string;
created_at?: string;
last_run_at?: string;
idle_remaining_seconds?: number;
}
export interface ListIsolatedSessionsResponse {
sessions?: IsolatedSessionSummary[];
}