Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

3.6 KB
Raw Blame
// 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 {
  CreateSnapshotRequest,
  CreateSandboxFromTemplateRequest,
  CreateSandboxRequest,
  CreateSandboxResponse,
  Endpoint,
  ListSnapshotsParams,
  ListSnapshotsResponse,
  ListSandboxesParams,
  ListSandboxesResponse,
  RenewSandboxExpirationRequest,
  RenewSandboxExpirationResponse,
  SnapshotInfo,
  SandboxId,
  SandboxInfo,
  SandboxMetadataPatch,
} from "../models/sandboxes.js";
import type {
  CreateTemplateRequest,
  ListTemplatesParams,
  ListTemplatesResponse,
  TemplateInfo,
} from "../models/templates.js";

export interface Sandboxes {
  createSandbox(
    req: CreateSandboxRequest,
    signal?: AbortSignal,
  ): Promise<CreateSandboxResponse>;
  /**
   * Create a sandbox from a `Succeeded` fsb template.
   *
   * Template mode fixes the workload shape on the server: only metadata,
   * network policy and extensions may accompany the template id, and the
   * timeout is required.
   */
  createSandboxFromTemplate(
    req: CreateSandboxFromTemplateRequest,
    signal?: AbortSignal,
  ): Promise<CreateSandboxResponse>;
  getSandbox(sandboxId: SandboxId): Promise<SandboxInfo>;
  listSandboxes(params?: ListSandboxesParams): Promise<ListSandboxesResponse>;
  patchSandboxMetadata(
    sandboxId: SandboxId,
    patch: SandboxMetadataPatch,
  ): Promise<SandboxInfo>;
  /**
   * Request irreversible sandbox termination. Resolves when deletion is accepted;
   * runtime cleanup may continue afterward.
   */
  deleteSandbox(sandboxId: SandboxId, signal?: AbortSignal): Promise<void>;

  pauseSandbox(sandboxId: SandboxId): Promise<void>;
  resumeSandbox(sandboxId: SandboxId): Promise<void>;

  renewSandboxExpiration(
    sandboxId: SandboxId,
    req: RenewSandboxExpirationRequest,
  ): Promise<RenewSandboxExpirationResponse>;

  createSnapshot(
    sandboxId: SandboxId,
    req?: CreateSnapshotRequest,
  ): Promise<SnapshotInfo>;

  getSnapshot(snapshotId: string): Promise<SnapshotInfo>;
  listSnapshots(params?: ListSnapshotsParams): Promise<ListSnapshotsResponse>;
  deleteSnapshot(snapshotId: string): Promise<void>;

  /**
   * Create a fsb template (golden-image build).
   *
   * The build is asynchronous: the response starts at `status.phase: Pending`;
   * poll `getTemplate` until `Succeeded` (or `Failed`).
   */
  createTemplate(req: CreateTemplateRequest): Promise<TemplateInfo>;
  /**
   * Get one template with its latest build status.
   */
  getTemplate(templateId: string): Promise<TemplateInfo>;
  /**
   * List the current tenant's templates with optional metadata filtering
   * (AND logic) and pagination.
   */
  listTemplates(params?: ListTemplatesParams): Promise<ListTemplatesResponse>;
  /**
   * Delete a template. Sandboxes already created from the template are unaffected.
   */
  deleteTemplate(templateId: string): Promise<void>;

  getSandboxEndpoint(
    sandboxId: SandboxId,
    port: number,
    useServerProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<Endpoint>;

  getSignedEndpoint(
    sandboxId: SandboxId,
    port: number,
    expires: number
  ): Promise<Endpoint>;

  invalidateEndpointCache?(sandboxId: SandboxId): void;
}