Sandbox Management

Learn how to create, configure, monitor, and manage GravixLayer sandboxes for optimal performance and resource utilization.

Sandbox Lifecycle

Creation Methods

Method 1: Simple Creation

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox create --provider gravix --region eu-west-1

Output:

Created sandbox: 1d1a0726-b9ce-49e0-944b-7e233fe3fe5d
Template: python-base-v1
Status: running
Resources: 2 CPU, 1024MB RAM
Started: 2025-10-28T10:33:43.670513028Z
Timeout: 2025-10-28T10:38:43.670513028Z

from gravixlayer import Sandbox

sandbox = Sandbox.create()
print(f"Created: {sandbox.sandbox_id}")
sandbox.kill()

with Sandbox.create() as sandbox:
    result = sandbox.run_code("print('Auto-cleanup!')")
    print(result.logs['stdout'][0])

Output:

Created: 550e8400-e29b-41d4-a716-446655440000
Auto-cleanup!

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create();
console.log(`Created: ${sandbox.sandbox_id}`);

try {
    const result = await sandbox.runCode("print('Manual cleanup!')");
    console.log(result.logs.stdout[0]);
} finally {
    await sandbox.kill();
}

Output:

Created: 550e8400-e29b-41d4-a716-446655440000
Manual cleanup!

Method 2: Advanced Configuration

CLI Command
Python SDK
JavaScript SDK

# Advanced configuration with all options
gravixlayer sandbox create --provider gravix --region eu-west-1 --template python-base-v1 --timeout 1800 --metadata '{\"project\":\"my-app\",\"env\":\"production\",\"user_id\":\"user123\"}'

Output:

Created sandbox: 6307baf7-8824-4f07-bd43-a87c80606d3f
   Template: python-base-v1
   Status: running
   Resources: 2 CPU, 1024MB RAM
   Started: 2025-10-28T11:06:41.45328687Z
   Timeout: 2025-10-28T11:36:41.45328687Z

from gravixlayer import Sandbox

sandbox = Sandbox.create(
    template="python-base-v1",
    provider="gravix",
    region="eu-west-1",
    timeout=1800,
    metadata={
        "project": "my-app",
        "env": "production",
        "user_id": "user123"
    }
)

print(f"Created: {sandbox.sandbox_id}")
print(f"Template: {sandbox.template}")
print(f"Timeout: {sandbox.timeout}s")

Output:

Created: 770f8511-g4bd-63f6-c938-668877662222
Template: python-base-v1
Timeout: 1800s

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create({
    template: "python-base-v1",
    provider: "gravix",
    region: "eu-west-1",
    timeout: 1800,
    metadata: {
        project: "my-app",
        env: "production",
        user_id: "user123"
    }
});

console.log(`Created: ${sandbox.sandbox_id}`);
console.log(`Template: ${sandbox.template}`);
console.log(`Timeout: ${sandbox.timeout}s`);

Output:

Created: 770f8511-g4bd-63f6-c938-668877662222
Template: python-base-v1
Timeout: 1800s

Monitoring and Status

Check Sandbox Status

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox get 550e8400-e29b-41d4-a716-446655440000

Output:

Sandbox: 0f0ec8df-9133-435a-b652-90a6c084a2fd
   Template: python-base-v1 (None)
   Status: running
   Resources: Unknown CPU, Unknown RAM
   Started: 2025-10-28T11:14:04.839134Z
   Timeout: 2025-10-28T11:44:04.839134Z
   Metadata: {'env': 'production', 'project': 'my-app', 'user_id': 'user123'}

from gravixlayer import GravixLayer

client = GravixLayer()
sandbox_info = client.sandbox.sandboxes.get("Sandbox_id")

print(f"Status: {sandbox_info.status}")
print(f"Started: {sandbox_info.started_at}")
print(f"Template: {sandbox_info.template}")

Output:

Status: running
Started: 2025-01-27T10:30:00Z
Template: python-base-v1

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandboxInfo = await client.sandbox.sandboxes.get("sandbox_id");

console.log(`Status: ${sandboxInfo.status}`);
console.log(`Started: ${sandboxInfo.started_at}`);
console.log(`Template: ${sandboxInfo.template}`);

Output:

Status: running
Started: 2025-01-27T10:30:00Z
Template: python-base-v1

List All Sandboxes

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox list

Output:

Total sandboxes: 2

Sandbox ID: 0f0ec8df-9133-435a-b652-90a6c084a2fd
   Template: python-base-v1
   Status: running
   Resources: 2 CPU, 1024MB RAM
   Started: 2025-10-28T11:14:04.839134Z
   Timeout: 2025-10-28T11:44:04.839134Z

Sandbox ID: 07a2dd11-2afe-4512-8e01-3fc88e9fd252
   Template: python-base-v1
   Status: running
   Resources: 2 CPU, 1024MB RAM
   Started: 2025-10-28T11:13:27.30236Z
   Timeout: 2025-10-28T11:43:27.30236Z

from gravixlayer import GravixLayer

client = GravixLayer()
sandbox_list = client.sandbox.sandboxes.list()

print(f"Total sandboxes: {len(sandbox_list.sandboxes)}")
for sb in sandbox_list.sandboxes:
    print(f"- {sb.sandbox_id}: {sb.status}")

Output:

Total sandboxes: 2
- 550e8400-e29b-41d4-a716-446655440000: running
- 660f9511-f3ac-52e5-b827-557766551111: stopped

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandboxList = await client.sandbox.sandboxes.list();

console.log(`Total sandboxes: ${sandboxList.sandboxes.length}`);
for (const sb of sandboxList.sandboxes) {
    console.log(`- ${sb.sandbox_id}: ${sb.status}`);
}

Output:

Total sandboxes: 2
- 550e8400-e29b-41d4-a716-446655440000: running
- 660f9511-f3ac-52e5-b827-557766551111: stopped

Timeout Management

Setting Timeouts

CLI Command
Python SDK
JavaScript SDK

# Set timeout during creation
gravixlayer sandbox create --provider gravix --region eu-west-1 --timeout 1800

# Update timeout for running sandbox
gravixlayer sandbox timeout 550e8400-e29b-41d4-a716-446655440000 --timeout 3600

# Check updated timeout
gravixlayer sandbox get 550e8400-e29b-41d4-a716-446655440000

Output:

Created sandbox: 550e8400-e29b-41d4-a716-446655440000
Timeout: 1800s (30 minutes)

Timeout updated successfully
New timeout: 3600s (1 hour)

ID: 550e8400-e29b-41d4-a716-446655440000
Status: running
Timeout: 2025-01-27T11:30:00Z (1 hour from now)

from gravixlayer import GravixLayer

client = GravixLayer()

sandbox_id = "your-sandbox-id"

# Get current timeout
current_info = client.sandbox.sandboxes.get(sandbox_id)
print(f"Previous timeout: {current_info.timeout_at}")

# Update timeout to 1 hour
timeout_response = client.sandbox.sandboxes.set_timeout(
    sandbox_id,
    timeout=3600  # 1 hour in seconds
)
print(f"Update status: {timeout_response.message}")

# Get new timeout
updated_info = client.sandbox.sandboxes.get(sandbox_id)
print(f"New timeout: {updated_info.timeout_at}")

Output:

Previous timeout: 2025-11-01T19:02:13.065194Z
Update status: Timeout updated successfully
New timeout: 2025-11-01T19:03:35.320585Z

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer({
  apiKey: process.env.GRAVIXLAYER_API_KEY
});

const sandboxId = "your-sandbox-id";

// Get current timeout
const currentInfo = await client.sandbox.sandboxes.get(sandboxId);
console.log(`Previous timeout: ${currentInfo.timeout_at}`);

// Update timeout to 1 hour
const timeoutResponse = await client.sandbox.sandboxes.setTimeout(
  sandboxId,
  3600  // 1 hour in seconds
);
console.log(`Update status: ${timeoutResponse.message}`);

// Get new timeout
const updatedInfo = await client.sandbox.sandboxes.get(sandboxId);
console.log(`New timeout: ${updatedInfo.timeout_at}`);

Output:

Previous timeout: 2025-11-01T19:02:13.065194Z
Update status: Timeout updated successfully
New timeout: 2025-11-01T19:03:35.320585Z

Timeout Limits

Timeout	Limit	Use Case
Default	300 seconds (5 minutes)	Quick operations
Extended	1800 seconds (30 minutes)	Data processing
Maximum	3600 seconds (1 hour)	Long-running tasks

Getting Metrics (Coming Soon)

Python
JavaScript

from gravixlayer import GravixLayer

client = GravixLayer()

# Note: Metrics endpoint may have server-side issues
try:
    metrics = client.sandbox.sandboxes.get_metrics(sandbox_id)
    print(f"CPU Usage: {metrics.cpu_usage}%")
    print(f"Memory: {metrics.memory_usage}/{metrics.memory_total} MB")
    print(f"Disk Read: {metrics.disk_read} bytes")
    print(f"Disk Write: {metrics.disk_write} bytes")
    print(f"Network RX: {metrics.network_rx} bytes")
    print(f"Network TX: {metrics.network_tx} bytes")
except Exception as e:
    print(f"Metrics unavailable: {e}")
    # Continue without metrics - all other functionality works

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();

// Note: Metrics endpoint may have server-side issues
try {
    const metrics = await client.sandbox.sandboxes.getMetrics(sandboxId);
    console.log(`CPU Usage: ${metrics.cpu_usage}%`);
    console.log(`Memory: ${metrics.memory_usage}/${metrics.memory_total} MB`);
    console.log(`Disk Read: ${metrics.disk_read} bytes`);
    console.log(`Disk Write: ${metrics.disk_write} bytes`);
    console.log(`Network RX: ${metrics.network_rx} bytes`);
    console.log(`Network TX: ${metrics.network_tx} bytes`);
} catch (error) {
    console.log(`Metrics unavailable: ${error.message}`);
    // Continue without metrics - all other functionality works
}

Sandbox Termination

Manual Termination

CLI Command
Python SDK
JavaScript SDK

# Terminate specific sandbox
gravixlayer sandbox kill 550e8400-e29b-41d4-a716-446655440000

# Verify termination
gravixlayer sandbox get 550e8400-e29b-41d4-a716-446655440000

Output:

Sandbox killed successfully

🔴 Sandbox: 0f0ec8df-9133-435a-b652-90a6c084a2fd
   Template: python-base-v1 (None)
   Status: terminated
   Resources: Unknown CPU, Unknown RAM
   Started: 2025-10-28T11:14:04.839134Z
   Ended: 2025-10-28T11:20:14.137745Z
   Timeout: 2025-10-28T11:44:04.839134Z
   Metadata: {'env': 'production', 'project': 'my-app', 'user_id': 'user123'}

from gravixlayer import Sandbox, GravixLayer

# Using Sandbox class
sandbox = Sandbox.create()
print(f"Created: {sandbox.sandbox_id}")
sandbox.kill()
print("Sandbox terminated")

# Using client directly
client = GravixLayer()
client.sandbox.sandboxes.kill("550e8400-e29b-41d4-a716-446655440000")
print("Sandbox terminated via client")

Output:

Created: 550e8400-e29b-41d4-a716-446655440000
Sandbox terminated
Sandbox terminated via client

import { Sandbox, GravixLayer } from 'gravixlayer';

// Using Sandbox class
const sandbox = await Sandbox.create();
console.log(`Created: ${sandbox.sandbox_id}`);
await sandbox.kill();
console.log("Sandbox terminated");

// Using client directly
const client = new GravixLayer();
await client.sandbox.sandboxes.kill("550e8400-e29b-41d4-a716-446655440000");
console.log("Sandbox terminated via client");

Output:

Created: 550e8400-e29b-41d4-a716-446655440000
Sandbox terminated
Sandbox terminated via client

Automatic Cleanup

Python
JavaScript

# ✅ Recommended: Context manager (automatic cleanup)
with Sandbox.create() as sandbox:
    # Work with sandbox
    pass  # Automatic cleanup when exiting

# ✅ Manual cleanup pattern
sandbox = Sandbox.create()
try:
    # Work with sandbox
    pass
finally:
    sandbox.kill()  # Ensure cleanup

// ✅ Recommended: Try-finally pattern
const sandbox = await Sandbox.create();
try {
    // Work with sandbox
} finally {
    await sandbox.kill();  // Ensure cleanup
}

Next Steps

Code Execution

Learn advanced code execution patterns

File Operations

Manage files and directories

Context Management

Use isolated execution contexts

Templates

Explore available environment templates

Getting Started

Core Features

Advanced Usage

Resources

Sandbox Management

Sandbox Lifecycle

Creation Methods

Method 1: Simple Creation

Method 2: Advanced Configuration

Monitoring and Status

Check Sandbox Status

List All Sandboxes

Timeout Management

Setting Timeouts

Timeout Limits

Getting Metrics (Coming Soon)

Sandbox Termination

Manual Termination

Automatic Cleanup

Next Steps

Code Execution

File Operations

Context Management

Templates

Getting Started

Core Features

Advanced Usage

Resources

​Sandbox Lifecycle

​Creation Methods

​Method 1: Simple Creation

​Method 2: Advanced Configuration

​Monitoring and Status

​Check Sandbox Status

​List All Sandboxes

​Timeout Management

​Setting Timeouts

​Timeout Limits

​Getting Metrics (Coming Soon)

​Sandbox Termination

​Manual Termination

​Automatic Cleanup

​Next Steps

Code Execution

File Operations

Context Management

Templates

Sandbox Lifecycle

Creation Methods

Method 1: Simple Creation

Method 2: Advanced Configuration

Monitoring and Status

Check Sandbox Status

List All Sandboxes

Timeout Management

Setting Timeouts

Timeout Limits

Getting Metrics (Coming Soon)

Sandbox Termination

Manual Termination

Automatic Cleanup

Next Steps