Getting Started

Get up and running with GravixLayer Sandbox in minutes. This guide covers installation, authentication, and your first sandbox execution.

Prerequisites

Python 3.7+ or Node.js 16+
GravixLayer API key

Installation

Python
JavaScript/Node.js

# Install via pip
pip install gravixlayer

# Verify installation
python -c "import gravixlayer; print(gravixlayer.__version__)"

# Install via npm
npm install gravixlayer

# Install via yarn
yarn add gravixlayer

# Verify installation
node -e "const { GravixLayer } = require('gravixlayer'); console.log('GravixLayer SDK loaded');"

Authentication

Set your API key as an environment variable:

Windows (CMD)
Windows (PowerShell)
Linux/macOS

set GRAVIXLAYER_API_KEY=your_api_key_here

$env:GRAVIXLAYER_API_KEY="your_api_key_here"

export GRAVIXLAYER_API_KEY=your_api_key_here

Security Best Practice: Always use environment variables for API keys. Never hardcode them in your source code or commit them to version control.

Your First Sandbox

Method 1: Simple Creation

CLI Command
Python SDK
JavaScript SDK

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

# Run code (replace YOUR_SANDBOX_ID)
gravixlayer sandbox code YOUR_SANDBOX_ID "print('Hello, GravixLayer!')"

Output:

Created sandbox: 550e8400-e29b-41d4-a716-446655440000
Hello, GravixLayer!

from gravixlayer import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.run_code("print('Hello, GravixLayer!')")
    print(result.logs['stdout'][0])

Output:

Hello, GravixLayer!

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create();
try {
    const result = await sandbox.runCode("print('Hello, GravixLayer!')");
    console.log(result.logs.stdout[0]);
} finally {
    await sandbox.kill();
}

Output:

Hello, GravixLayer!

Method 2: Custom Configuration

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox create --provider gravix --region eu-west-1 --timeout 600 --template python-base-v1

Output:

Created sandbox: 5a44cb3f-76b3-4398-9a9a-4898c036bf19
   Template: python-base-v1
   Status: running
   Resources: 2 CPU, 1024MB RAM
   Started: 2025-10-28T09:55:28.349147173Z
   Timeout: 2025-10-28T10:05:28.349147173Z

from gravixlayer import Sandbox

# Create sandbox - will automatically display creation info
sandbox = Sandbox.create(
    template="python-base-v1",
    timeout=600,
    metadata={"project": "my-app"}
)

# Run code
result = sandbox.run_code("import sys; print(sys.version)")
print(result.logs['stdout'][0])

Output:

Created sandbox: 45872211-7212-4f54-be2a-584c87c59ca3
Template: python-base-v1
Status: running
Resources: 2 CPU, 1024MB RAM
Started: 2025-10-28T09:58:56.18008506Z
Timeout: 2025-10-28T10:08:56.18008506Z
3.11.14 (main, Oct 10 2025, 13:38:24) [GCC 13.2.1 20231014]

import { Sandbox } from 'gravixlayer';

// Create sandbox - will automatically display creation info
const sandbox = await Sandbox.create({
    template: "python-base-v1",
    timeout: 600,
    metadata: { project: "my-app" }
});

// Run code
const result = await sandbox.runCode("import sys; print(sys.version)");
console.log(result.logs.stdout[0]);

Output:

Created sandbox: 78af4b7d-9415-4e2d-a067-f76544d6cfd5
Template: python-base-v1
Status: running
Resources: 2 CPU, 1024MB RAM
Started: 2025-10-28T10:00:15.644750914Z
Timeout: 2025-10-28T10:10:15.644750914Z
3.11.14 (main, Oct 10 2025, 13:38:24) [GCC 13.2.1 20231014]

Basic Operations

Running Code

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox code YOUR_SANDBOX_ID "print('Hello World!')"

gravixlayer sandbox code YOUR_SANDBOX_ID "
import math
result = math.sqrt(16)
print(f'Square root of 16 is {result}')
"

Output:

Hello World!
Square root of 16 is 4.0

from gravixlayer import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.run_code("print('Hello World!')")
    print(result.logs['stdout'])
    
    code = """
import math
result = math.sqrt(16)
print(f"Square root of 16 is {result}")
"""
    result = sandbox.run_code(code)
    for line in result.logs['stdout']:
        print(line)

Output:

['Hello World!']
Square root of 16 is 4.0

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create();

const result = await sandbox.runCode("print('Hello World!')");
console.log(result.logs.stdout);

const code = `
import math
result = math.sqrt(16)
print(f"Square root of 16 is {result}")
`;

const result2 = await sandbox.runCode(code);
for (const line of result2.logs.stdout) {
    console.log(line);
}

Output:

['Hello World!']
Square root of 16 is 4.0

Executing Commands

Python SDK
JavaScript SDK

with Sandbox.create() as sandbox:
    result = sandbox.run_command("python", ["--version"])
    print(result.stdout)
    
    result = sandbox.run_command("ls", ["-la", "/home/user"])
    print(result.stdout)

Output:

Python 3.11.14

ls: /home/user: No such file or directory

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create();
try {
    const result = await sandbox.runCommand("python", ["--version"]);
    console.log(result.stdout);
    
    const result2 = await sandbox.runCommand("ls", ["-la", "/home/user"]);
    console.log(result2.stdout);
} finally {
    await sandbox.kill();
}

Output:

Python 3.11.14

ls: /home/user: No such file or directory

Working with Files

Python SDK
JavaScript SDK
CLI Command

from gravixlayer import Sandbox

with Sandbox.create() as sandbox:
    sandbox.write_file("/home/user/hello.txt", "Hello, World!")
    
    content = sandbox.read_file("/home/user/hello.txt")
    print(content)
    
    files = sandbox.list_files("/home/user")
    print(files)

Output:

Hello, World!
['hello.txt']

import { Sandbox } from 'gravixlayer';
const sandbox = await Sandbox.create();
try {
    await sandbox.writeFile("/home/user/hello.txt", "Hello, World!");
    
    const content = await sandbox.readFile("/home/user/hello.txt");
    console.log(content);
    
    const files = await sandbox.listFiles("/home/user");
    console.log(files);
} finally {
    await sandbox.kill();
}

Output:

Hello, World!
['hello.txt']

gravixlayer sandbox file write YOUR_SANDBOX_ID "/home/user/hello.txt" "Hello, World!"
gravixlayer sandbox file read YOUR_SANDBOX_ID "/home/user/hello.txt"
gravixlayer sandbox file list YOUR_SANDBOX_ID "/home/user"

Output:

Hello, World!
['hello.txt']

Next Steps

Sandbox Management

Advanced configuration and lifecycle management

Code Execution

Advanced code execution patterns

File Operations

File upload, download, and management

Context Management

Isolated execution contexts

Getting Started

Core Features

Advanced Usage

Resources

Getting Started

Prerequisites

Installation

Authentication

Your First Sandbox

Method 1: Simple Creation

Method 2: Custom Configuration

Basic Operations

Running Code

Executing Commands

Working with Files

Next Steps

Sandbox Management

Code Execution

File Operations

Context Management

Getting Started

Core Features

Advanced Usage

Resources

​Prerequisites

​Installation

​Authentication

​Your First Sandbox

​Method 1: Simple Creation

​Method 2: Custom Configuration

​Basic Operations

​Running Code

​Executing Commands

​Working with Files

​Next Steps

Sandbox Management

Code Execution

File Operations

Context Management

Prerequisites

Installation

Authentication

Your First Sandbox

Method 1: Simple Creation

Method 2: Custom Configuration

Basic Operations

Running Code

Executing Commands

Working with Files

Next Steps