Skip to content

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

4.7 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.

/**
 * Domain models for fsb (fast-sandbox) golden-image template management.
 *
 * Templates declare an asynchronous golden-image build; only `Succeeded`
 * templates can back template-based sandbox creation. Template management
 * requires a Kubernetes-backed runtime.
 */

import type { PaginationInfo, ResourceLimits } from "./sandboxes.js";

/**
 * Storage encoding of the produced snapshot set.
 */
export type TemplateFormat = "native" | "overlaybd";

/**
 * High-level lifecycle phase of a fsb template build.
 *
 * The server may introduce new phases in future versions; handle unknown
 * values gracefully.
 */
export type TemplatePhase = "Pending" | "Building" | "Succeeded" | "Failed" | string;

export interface TemplateReadiness extends Record<string, unknown> {
  /**
   * Readiness probe checked first during the golden-image build;
   * e.g. `tcp://127.0.0.1:44772` or `cmd://<command>`.
   */
  probe?: string;
  /**
   * Fallback warmup window in seconds (default 60).
   */
  warmupSeconds?: number;
}

export interface TemplateStatus extends Record<string, unknown> {
  /**
   * Build lifecycle phase.
   */
  phase: TemplatePhase;
  /**
   * Published S3 manifest reference or immutable OCI reference; present when the phase is `Succeeded`.
   */
  manifestRef?: string;
  /**
   * Failure reason when the phase is `Failed`.
   */
  message?: string;
}

export interface CreateTemplateRequest extends Record<string, unknown> {
  /**
   * Source OCI image reference the golden image is built from.
   */
  image: string;
  /**
   * Publish destination: `s3://bucket/publish` (native) or `oci://registry/repository` (overlaybd, no tag or digest).
   */
  publish: string;
  /**
   * Guest machine sizing, e.g. `{ cpu: "1", memory: "512Mi", disk: "2Gi" }`.
   * Defaults when omitted: cpu `1`, memory `512Mi`, disk `2Gi`.
   */
  resourceLimits?: ResourceLimits;
  /**
   * Guest business command (argv); empty defaults to `["tail", "-f", "/dev/null"]`.
   */
  entrypoint?: string[];
  /**
   * Environment variables baked into the golden image (injected as
   * `/etc/sandbox-init.env` in the guest; literal values only). The source
   * image's own OCI `Config.Env` is inherited; an env with the same name
   * overrides the inherited value. Names must be valid shell variable names.
   */
  env?: Record<string, string>;
  /**
   * Custom key-value metadata for management, filtering, and tagging.
   */
  metadata?: Record<string, string>;
  /**
   * Build-side readiness gate.
   */
  readiness?: TemplateReadiness;
  /**
   * Storage encoding of the produced snapshot set. Defaults to `overlaybd`.
   */
  format?: TemplateFormat;
}

export interface TemplateInfo extends Record<string, unknown> {
  /**
   * Server-generated template ID (`tpl_<uuid>`).
   */
  templateId: string;
  /**
   * Source OCI image reference.
   */
  image: string;
  /**
   * S3-compatible or repository-only OCI publish target.
   */
  publish: string;
  /**
   * Snapshot storage encoding.
   */
  format: TemplateFormat;
  /**
   * Current build status.
   */
  status: TemplateStatus;
  /**
   * Creation timestamp (RFC 3339 UTC).
   */
  createdAt: Date;
  /**
   * Last update timestamp (RFC 3339 UTC).
   */
  updatedAt: Date;
  /**
   * Guest machine sizing (cpu/memory/disk).
   */
  resourceLimits?: ResourceLimits;
  /**
   * Guest business command (argv).
   */
  entrypoint?: string[];
  /**
   * Environment variables baked into the golden image.
   */
  env?: Record<string, string>;
  /**
   * Custom metadata from the creation request.
   */
  metadata?: Record<string, string>;
  /**
   * Build-side readiness gate.
   */
  readiness?: TemplateReadiness;
}

export interface ListTemplatesParams {
  /**
   * Filter by metadata key-value pairs (AND logic).
   * NOTE: This will be encoded to a single `metadata` query parameter as described in the spec.
   */
  metadata?: Record<string, string>;
  /**
   * Pagination page number (1-indexed).
   */
  page?: number;
  /**
   * Number of items per page (1-200).
   */
  pageSize?: number;
}

export interface ListTemplatesResponse extends Record<string, unknown> {
  items: TemplateInfo[];
  pagination?: PaginationInfo;
}