Sandbox Management

Sandboxes are isolated development environments managed by Synodes. This guide covers how to create, manage, and remove Sandboxes using the SDK. By default, Sandboxes auto-stop after 15 minutes of inactivity and use 1 vCPU, 1GB RAM, and 3GiB disk.

Sandbox Lifecycle

Throughout its lifecycle, a Synodes Sandbox can have several different states. The diagram below shows the states and possible transitions between them.

By default, sandboxes auto-stop after 15 minutes of inactivity and auto-archive after 7 days of being stopped. To keep the Sandbox running indefinitely without interruption, set the auto-stop value to 0 during creation.

Creating Sandboxes

The Synodes SDK provides an option to create Sandboxes with default or custom configurations. You can specify the language, Snapshot, resources, environment variables, and volumes for the Sandbox. Running Sandboxes utilize CPU, memory, and disk storage. Every resource is charged per second of usage.

Basic Sandbox Creation

The Synodes SDK provides methods to create Sandboxes with default configurations, specific languages, or custom labels using Python and TypeScript.

Python
TypeScript

from synodes import Synodes, CreateSandboxFromSnapshotParams

synodes = Synodes()

# Create a basic Sandbox

sandbox = synodes.create()

# Create a Sandbox with specific language

params = CreateSandboxFromSnapshotParams(language="python")
sandbox = synodes.create(params)

# Create a Sandbox with custom labels

params = CreateSandboxFromSnapshotParams(labels={"SOME_LABEL": "my-label"})
sandbox = synodes.create(params)

import { Synodes } from '@synodesio/sdk';

const synodes = new Synodes();

// Create a basic Sandbox
const sandbox = await synodes.create();

// Create a Sandbox with specific language
const sandbox = await synodes.create({ language: 'typescript' });

// Create a Sandbox with custom labels
const sandbox = await synodes.create({ labels: { SOME_LABEL: 'my-label' } });

When Sandboxes are not actively used, it is recommended that they be stopped. This can be done manually using the stop command or automatically by setting the auto-stop interval.

Sandbox Resources

Synodes Sandboxes come with 1 vCPU, 1GB RAM, and 3GiB disk by default.

Need more power? Use the Resources class to define exactly what you need: CPU, memory, and disk space are all customizable.

Check your available resources and limits in the dashboard.

Python
TypeScript

from synodes import Synodes, Resources, CreateSandboxFromImageParams, Image

synodes = Synodes()

# Create a Sandbox with custom resources

resources = Resources(
    cpu=2,  # 2 CPU cores
    memory=4,  # 4GB RAM
    disk=8,  # 8GB disk space
)

params = CreateSandboxFromImageParams(
    image=Image.debian_slim("3.12"),
    resources=resources
)

sandbox = synodes.create(params)

import { Synodes, Image } from "@synodesio/sdk";

async function main() {
  const synodes = new Synodes();

  // Create a Sandbox with custom resources
  const sandbox = await synodes.create({
    image: Image.debianSlim("3.13"),
    resources: {
      cpu: 2, // 2 CPU cores
      memory: 4, // 4GB RAM
      disk: 8, // 8GB disk space
    },
  });
}

main();

Sandbox Information

The Synodes SDK provides methods to get information about a Sandbox, such as ID, root directory, and status using Python and TypeScript.

Python
TypeScript

# Get Sandbox ID
sandbox_id = sandbox.id

# Get the root directory of the Sandbox user

root_dir = sandbox.get_user_root_dir()

# Get the Sandbox id, auto-stop interval and state

print(sandbox.id)
print(sandbox.auto_stop_interval)
print(sandbox.state)

// Get Sandbox ID
const sandboxId = sandbox.id;

// Get the root directory of the Sandbox user
const rootDir = await sandbox.getUserRootDir();

// Get the Sandbox id, auto-stop interval and state
console.log(sandbox.id)
console.log(sandbox.autoStopInterval)
console.log(sandbox.state)

To get the preview URL for a specific port, check out Preview & Authentication.

Stop and Start Sandbox

The Synodes SDK provides methods to stop and start Sandboxes using Python and TypeScript.

Stopped Sandboxes maintain filesystem persistence while their memory state is cleared. They incur only disk usage costs and can be started again when needed.

Python
TypeScript

sandbox = synodes.create(CreateSandboxParams(language="python"))

# Stop Sandbox

sandbox.stop()

print(sandbox.id) # 7cd11133-96c1-4cc8-9baa-c757b8f8c916

# The sandbox ID can later be used to find the sandbox and start it

sandbox = synodes.find_one("7cd11133-96c1-4cc8-9baa-c757b8f8c916")

# Start Sandbox

sandbox.start()

const sandbox = await synodes.create({ language: 'typescript' });

// Stop Sandbox
await sandbox.stop();

console.log(sandbox.id) // 7cd11133-96c1-4cc8-9baa-c757b8f8c916

// The sandbox ID can later be used to find the sandbox and start it

const sandbox = await synodes.findOne("7cd11133-96c1-4cc8-9baa-c757b8f8c916");

// Start Sandbox
await sandbox.start();

The stopped state should be used when the Sandbox is expected to be started again soon. Otherwise, it is recommended to stop and then archive the Sandbox to eliminate disk usage costs.

Archive Sandbox

The Synodes SDK provides methods to archive Sandboxes using Python and TypeScript.

When Sandboxes are archived, the entire filesystem state is moved to very cost-effective object storage, making it possible to keep Sandboxes available for an extended period. Starting an archived Sandbox takes more time than starting a stopped Sandbox, depending on its size.

A Sandbox must be stopped before it can be archived, and can be started again in the same way as a stopped Sandbox.

Python
TypeScript

# Archive Sandbox
sandbox.archive()

// Archive Sandbox
await sandbox.archive();

Delete Sandbox

The Synodes SDK provides methods to delete Sandboxes using Python and TypeScript.

Python
TypeScript

# Delete Sandbox
sandbox.delete()

// Delete Sandbox
await sandbox.delete();

Check out the Synodes CLI if you prefer managing Sandboxes through the terminal:

synodes sandbox list

    Sandbox               State           Region        Last Event
    ────────────────────────────────────────────────────────────────────────────────────
    ugliest_quokka        STARTED         us            1 hour ago

    associated_yak        STARTED         us            14 hours ago

    developed_lemur       STARTED         us            17 hours ago

synodes sandbox start|stop|remove --all

All sandboxes have been deleted

Auto-stop and Auto-archive

Synodes Sandboxes can be automatically stopped and archived based on user-defined intervals.

Auto-stop Interval

The auto-stop interval parameter sets the amount of time after which a running Sandbox will be automatically stopped.

The parameter can either be set to:

a time interval in minutes
0, which disables the auto-stop functionality, allowing the sandbox to run indefinitely

If the parameter is not set, the default interval of 15 minutes will be used.

:::

Python
TypeScript

sandbox = synodes.create(CreateSandboxFromSnapshotParams(
    snapshot="my-snapshot-name",
    auto_stop_interval=0,  # Disables the auto-stop feature - default is 15 minutes
))

const sandbox = await synodes.create({
    snapshot: "my-snapshot-name",
    autoStopInterval: 0, // Disables the auto-stop feature - default is 15 minutes
});

Auto-archive Interval

The auto-archive interval parameter sets the amount of time after which a continuously stopped Sandbox will be automatically archived.

The parameter can either be set to:

a time interval in minutes
0, which means the maximum interval of 30 days will be used

If the parameter is not set, the default interval of 7 days days will be used.

Python
TypeScript

sandbox = synodes.create(CreateSandboxFromSnapshotParams(
    snapshot="my-snapshot-name",
    auto_archive_interval=60 # Auto-archive after a Sandbox has been stopped for 1 hour
))

const sandbox = await synodes.create({
    snapshot: "my-snapshot-name",
    autoArchiveInterval: 60 // Auto-archive after a Sandbox has been stopped for 1 hour
});

Run Indefinitely

By default, Sandboxes auto-stop after 15 minutes of inactivity. To keep a Sandbox running without interruption, set the auto-stop interval to 0 when creating a new Sandbox:

Python
TypeScript

sandbox = synodes.create(CreateSandboxFromSnapshotParams(
    snapshot="my-snapshot-name",
    auto_stop_interval=0,  # Disables the auto-stop feature - default is 15 minutes
))

const sandbox = await synodes.create({
    snapshot: "my-snapshot-name",
    autoStopInterval: 0, // Disables the auto-stop feature - default is 15 minutes
});