Skip to content

Synodes

Main class for interacting with the Synodes API. Provides methods for creating, managing, and interacting with Synodes Sandboxes. Can be initialized either with explicit configuration or using environment variables.

Properties:

  • snapshot SnapshotService - Service for managing Synodes Snapshots
  • volume VolumeService - Service for managing Synodes Volumes

Examples:

// Using environment variables
// Uses SYNODES_API_KEY, SYNODES_API_URL, SYNODES_TARGET
const synodes = new Synodes();
const sandbox = await synodes.create();
// Using explicit configuration
const config: SynodesConfig = {
    apiKey: "your-api-key",
    apiUrl: "https://your-api.com",
    target: "us"
};
const synodes = new Synodes(config);


@class

Constructors

new Synodes()

new Synodes(config?: SynodesConfig): Synodes

Creates a new Synodes client instance.

Parameters:

  • config? SynodesConfig - Configuration options

Returns:

  • Synodes

Throws:

  • SynodesError - When API key is missing

Methods

create()

Call Signature
create(params?: CreateSandboxFromSnapshotParams, options?: {
  timeout: number;
}): Promise<Sandbox>

Creates Sandboxes from specified or default snapshot. You can specify various parameters, including language, image, environment variables, and volumes.

Parameters:

  • params? CreateSandboxFromSnapshotParams - Parameters for Sandbox creation from snapshot
  • options? Options for the create operation
  • timeout? number - Timeout in seconds (0 means no timeout, default is 60)

Returns:

  • Promise<Sandbox> - The created Sandbox instance

Examples:

const sandbox = await synodes.create();
// Create a custom sandbox
const params: CreateSandboxFromSnapshotParams = {
    language: 'typescript',
    snapshot: 'my-snapshot-id',
    envVars: {
        NODE_ENV: 'development',
        DEBUG: 'true'
    },
    autoStopInterval: 60
};
const sandbox = await synodes.create(params, { timeout: 100 });
Call Signature
create(params?: CreateSandboxFromImageParams, options?: {
  onSnapshotCreateLogs: (chunk: string) => void;
  timeout: number;
}): Promise<Sandbox>

Creates Sandboxes from specified image available on some registry or declarative Synodes Image. You can specify various parameters, including resources, language, image, environment variables, and volumes. Synodes creates snapshot from provided image and uses it to create Sandbox.

Parameters:

  • params? CreateSandboxFromImageParams - Parameters for Sandbox creation from image
  • options? Options for the create operation
  • onSnapshotCreateLogs? (chunk: string) => void - Callback function to handle snapshot creation logs.
  • timeout? number - Timeout in seconds (0 means no timeout, default is 60)

Returns:

  • Promise<Sandbox> - The created Sandbox instance

Examples:

const sandbox = await synodes.create({ image: 'debian:12.9' }, { timeout: 90, onSnapshotCreateLogs: console.log });
// Create a custom sandbox
const image = Image.base('alpine:3.18').pipInstall('numpy');
const params: CreateSandboxFromImageParams = {
    language: 'typescript',
    image,
    envVars: {
        NODE_ENV: 'development',
        DEBUG: 'true'
    },
    resources: {
        cpu: 2,
        memory: 4 // 4GB RAM
    },
    autoStopInterval: 60
};
const sandbox = await synodes.create(params, { timeout: 100, onSnapshotCreateLogs: console.log });

delete()

delete(sandbox: Sandbox, timeout: number): Promise<void>

Deletes a Sandbox.

Parameters:

  • sandbox Sandbox - The Sandbox to delete
  • timeout number = 60 - Timeout in seconds (0 means no timeout, default is 60)

Returns:

  • Promise<void>

Example:

const sandbox = await synodes.get('my-sandbox-id');
await synodes.delete(sandbox);

findOne()

findOne(filter: SandboxFilter): Promise<Sandbox>

Finds a Sandbox by its ID or labels.

Parameters:

  • filter SandboxFilter - Filter for Sandboxes

Returns:

  • Promise<Sandbox> - First Sandbox that matches the ID or labels.

Example:

const sandbox = await synodes.findOne({ labels: { 'my-label': 'my-value' } });
console.log(`Sandbox ID: ${sandbox.id}, State: ${sandbox.state}`);

get()

get(sandboxId: string): Promise<Sandbox>

Gets a Sandbox by its ID.

Parameters:

  • sandboxId string - The ID of the Sandbox to retrieve

Returns:

  • Promise<Sandbox> - The Sandbox

Example:

const sandbox = await synodes.get('my-sandbox-id');
console.log(`Sandbox state: ${sandbox.state}`);

list()

list(labels?: Record<string, string>): Promise<Sandbox[]>

Lists all Sandboxes filtered by labels.

Parameters:

  • labels? Record<string, string> - Labels to filter Sandboxes

Returns:

  • Promise<Sandbox[]> - Array of Sandboxes that match the labels.

Example:

const sandboxes = await synodes.list({ 'my-label': 'my-value' });
for (const sandbox of sandboxes) {
    console.log(`${sandbox.id}: ${sandbox.state}`);
}

start()

start(sandbox: Sandbox, timeout?: number): Promise<void>

Starts a Sandbox and waits for it to be ready.

Parameters:

  • sandbox Sandbox - The Sandbox to start
  • timeout? number - Optional timeout in seconds (0 means no timeout)

Returns:

  • Promise<void>

Example:

const sandbox = await synodes.get('my-sandbox-id');
// Wait up to 60 seconds for the sandbox to start
await synodes.start(sandbox, 60);

stop()

stop(sandbox: Sandbox): Promise<void>

Stops a Sandbox.

Parameters:

  • sandbox Sandbox - The Sandbox to stop

Returns:

  • Promise<void>

Example:

const sandbox = await synodes.get('my-sandbox-id');
await synodes.stop(sandbox);

CodeLanguage

Supported programming languages for code execution

Enum Members:

  • JAVASCRIPT (“javascript”)
  • PYTHON (“python”)
  • TYPESCRIPT (“typescript”)

CreateSandboxBaseParams

Base parameters for creating a new Sandbox.

Properties:

  • autoArchiveInterval? number - Auto-archive interval in minutes (0 means the maximum interval will be used). Default is 7 days.
  • autoStopInterval? number - Auto-stop interval in minutes (0 means disabled). Default is 15 minutes.
  • envVars? Record<string, string> - Optional environment variables to set in the Sandbox
  • labels? Record<string, string> - Sandbox labels
  • language? string - Programming language for direct code execution
  • public? boolean - Is the Sandbox port preview public
  • user? string - Optional os user to use for the Sandbox
  • volumes? VolumeMount[]

CreateSandboxFromImageParams

Parameters for creating a new Sandbox.

Properties:

  • autoArchiveInterval? number
  • autoStopInterval? number
  • envVars? Record<string, string>
  • image string | Image - Custom Docker image to use for the Sandbox. If an Image object is provided, the image will be dynamically built.
  • labels? Record<string, string>
  • language? string
  • public? boolean
  • resources? Resources - Resource allocation for the Sandbox. If not provided, sandbox will have default resources.
  • user? string
  • volumes? VolumeMount[]

CreateSandboxFromSnapshotParams

Parameters for creating a new Sandbox from a snapshot.

Properties:

  • autoArchiveInterval? number
  • autoStopInterval? number
  • envVars? Record<string, string>
  • labels? Record<string, string>
  • language? string
  • public? boolean
  • snapshot? string - Name of the snapshot to use for the Sandbox.
  • user? string
  • volumes? VolumeMount[]

SynodesConfig

Configuration options for initializing the Synodes client.

Properties:

  • apiKey? string - API key for authentication with the Synodes API
  • apiUrl? string - URL of the Synodes API. Defaults to ’https://app.synodes.io/api’ if not set here and not set in environment variable SYNODES_API_URL.
  • jwtToken? string - JWT token for authentication with the Synodes API. If not set, it must be provided via the environment variable SYNODES_JWT_TOKEN, or an API key must be provided instead.
  • organizationId? string - Organization ID used for JWT-based authentication. Required if a JWT token is provided, and must be set either here or in the environment variable SYNODES_ORGANIZATION_ID.
  • serverUrl? string - Deprecated - Use apiUrl instead. This property will be removed in future versions.
  • target? string - Target location for Sandboxes

Example:

const config: SynodesConfig = {
    apiKey: "your-api-key",
    apiUrl: "https://your-api.com",
    target: "us"
};
const synodes = new Synodes(config);

Resources

Resource allocation for a Sandbox.

Properties:

  • cpu? number - CPU allocation for the Sandbox in cores
  • disk? number - Disk space allocation for the Sandbox in GiB
  • gpu? number - GPU allocation for the Sandbox in units
  • memory? number - Memory allocation for the Sandbox in GiB

Example:

const resources: SandboxResources = {
    cpu: 2,
    memory: 4,  // 4GiB RAM
    disk: 20    // 20GiB disk
};

SandboxFilter

Filter for Sandboxes.

Properties:

  • id? string - The ID of the Sandbox to retrieve
  • labels? Record<string, string> - Labels to filter Sandboxes

VolumeMount

Represents a volume mount for a Sandbox.

Properties:

  • mountPath string - Path on the Sandbox to mount the Volume

  • volumeId string - ID of the Volume to mount

Extends:

  • SandboxVolume