Create your first Sandbox

Learn how to build your first sandbox using the Decentra Sandbox Platform API.

Using the TypeScript SDK

The simplest approach to setting up a sandbox is through our official TypeScript SDK.

1

Create a sandbox (TypeScript SDK)

import SandboxSDK from '@avmcodes/sandbox-sdk';

const client = new SandboxSDK({
  apiKey: process.env['SANDBOX_SDK_API_KEY'],
});

// Create a sandbox with default settings
const sandbox = await client.sandboxes.create({
  name: 'My First Sandbox',
});

console.log('Sandbox created:', sandbox.id);

2

Customizing Resources

You’re able to adjust processor and memory resources as required.

const sandbox = await client.sandboxes.create({
  name: 'High Performance Sandbox',
  resources: {
    cpus: 4,
    memory: 2048, // Memory in MiB
  },
});

3

Using a Custom Docker Image

A standard Decentra sandbox image is used automatically, but you can point to a different image if needed.

const sandbox = await client.sandboxes.create({
  name: 'Custom Image Sandbox',
  image: 'avmcodes/avm-default-sandbox',
  resources: {
    cpus: 2,
    memory: 512,
  },
});

4

Attaching Volumes

You can mount persistent storage to retain data across sandbox sessions.

const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Volume',
  volumes: [
    {
      volume_id: 'vol_x1y2z3a4b5c6d7e8',
      mount_path: '/data',
    },
  ],
});

5

Setting Environment Variables

Environment variables can be injected into your sandbox configuration.

const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Env Vars',
  env_vars: {
    API_KEY: 'your-api-key',
    DEBUG: 'true',
  },
});

---

Response Structure

The create() method returns a SandboxCreateResponse object:

const sandbox = await client.sandboxes.create({
  name: 'My First Sandbox',
  resources: {
    cpus: 2,
    memory: 512,
  },
});

// sandbox contains:
console.log(sandbox.id);         // "sbx_x1y2z3a4b5c6d7e8"
console.log(sandbox.name);       // "My First Sandbox"
console.log(sandbox.status);     // "creating"
console.log(sandbox.cpu);        // 2
console.log(sandbox.memory);     // 512
console.log(sandbox.created_at); // "2024-01-15T12:00:00Z"
console.log(sandbox.volumes);    // Array of mounted volumes (if any)

---

Parameters

name string

A clear label used to identify the sandbox.

image string default:"dvmcodes/avm-default-sandbox"

The Docker image that will be used to run the sandbox.

rsources object

Compute and memory resources assigned to the sandbox.

rsources.cpus integer default:"2"

Compute and memory resources assigned to the sandbox.

rsources.memory object default:"512"

Memory size in MiB (128-32768)

---

---

env_vars object

Key–value environment settings applied to the sandbox.

volumes array

A list of storage volumes to be mounted to the sandbox.

volumes[].volume_id string required

A list of storage volumes to be mounted to the sandbox.

volumes[].mounth_path string required

The directory inside the container where the volume is mounted (e.g., /data).

---

---

Next Steps

Once your sandbox is created, you can:

• Execute commands in your sandbox

• List all sandboxes in your account

• Check the API Reference for file upload and download operations