Command Execution

Execute system commands in GravixLayer sandboxes with full control over arguments, environment variables, and execution context.

Basic Command Execution

Simple Commands

CLI Command
Python SDK
JavaScript SDK

gravixlayer sandbox run YOUR_SANDBOX_ID echo --args="Hello from command line"

Output:

Command executed (exit code: 0)
Duration: 150ms
Success: True

STDOUT:
Hello from command line

from gravixlayer import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.run_command("echo", ["Hello from command line"])
    print(result.stdout)
    print(f"Exit code: {result.exit_code}")

Output:

Hello from command line
Exit code: 0

import { Sandbox } from 'gravixlayer';

const sandbox = await Sandbox.create();
try {
    const result = await sandbox.runCommand("echo", ["Hello from command line"]);
    console.log(result.stdout);
    console.log(`Exit code: ${result.exit_code}`);
} finally {
    await sandbox.kill();
}

Output:

Hello from command line
Exit code: 0

System Information Commands

Python SDK
JavaScript SDK
CLI Command

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

Output:

Python: Python 3.11.14
Directory: /home/user
total 0
drwxr-xr-x 2 user user 4096 Oct 27 10:30 .
drwxr-xr-x 3 root root 4096 Oct 27 10:30 ..

const sandbox = await Sandbox.create();
try {
    const pythonResult = await sandbox.runCommand("python", ["--version"]);
    console.log(`Python: ${pythonResult.stdout}`);
    
    const pwdResult = await sandbox.runCommand("pwd");
    console.log(`Directory: ${pwdResult.stdout}`);
    
    const lsResult = await sandbox.runCommand("ls", ["-la", "/home/user"]);
    console.log(lsResult.stdout);
} finally {
    await sandbox.kill();
}

gravixlayer sandbox run YOUR_SANDBOX_ID python3 --args="-V"
gravixlayer sandbox run YOUR_SANDBOX_ID pwd
gravixlayer sandbox run YOUR_SANDBOX_ID ls --args="/home/sandbox"

Output:

Command executed (exit code: 0)
Duration: 193ms
Success: True

STDOUT:
Python 3.11.14

Command executed (exit code: 0)
Duration: 94ms
Success: True

STDOUT:
/

Command executed (exit code: 0)
Duration: 137ms
Success: True

STDOUT:
bin
dev
etc
home
lib
...

Advanced Command Options

Working Directory

CLI Command
Python SDK
JavaScript SDK

# Create a directory
gravixlayer sandbox run YOUR_SANDBOX_ID mkdir --args="-p" --args="/home/sandbox/project"

# Run command in specific directory
gravixlayer sandbox run YOUR_SANDBOX_ID ls --args="-la" --working-dir="/home/sandbox/project"

# Create file in specific directory
gravixlayer sandbox run YOUR_SANDBOX_ID touch --args="test.txt" --working-dir="/home/sandbox/project"

# Verify file creation
gravixlayer sandbox run YOUR_SANDBOX_ID ls --working-dir="/home/sandbox/project"

Output:

Command executed (exit code: 0)
Duration: 120ms
Success: True

Command executed (exit code: 0)
Duration: 95ms
Success: True

STDOUT:
total 8
drwxr-xr-x 2 user user 4096 Oct 28 10:30 .
drwxr-xr-x 3 user user 4096 Oct 28 10:30 ..
-rw-r--r-- 1 user user    0 Oct 28 10:30 test.txt

Command executed (exit code: 0)
Duration: 85ms
Success: True

STDOUT:
test.txt

with Sandbox.create() as sandbox:
    # Create a directory
    sandbox.run_command("mkdir", ["-p", "/home/user/project"])
    
    # Run command in specific directory
    result = sandbox.run_command(
        "ls", 
        ["-la"], 
        working_dir="/home/user/project"
    )
    print(f"Files in project directory: {result.stdout}")
    
    # Create file in specific directory
    result = sandbox.run_command(
        "touch",
        ["test.txt"],
        working_dir="/home/user/project"
    )
    
    # Verify file creation
    result = sandbox.run_command("ls", working_dir="/home/user/project")
    print(f"Created files: {result.stdout}")

const sandbox = await Sandbox.create();
try {
    // Create a directory
    await sandbox.runCommand("mkdir", ["-p", "/home/user/project"]);
    
    // Run command in specific directory
    const result = await sandbox.runCommand("ls", ["-la"], {
        working_dir: "/home/user/project"
    });
    console.log(`Files in project directory: ${result.stdout}`);
    
    // Create file in specific directory
    await sandbox.runCommand("touch", ["test.txt"], {
        working_dir: "/home/user/project"
    });
    
    // Verify file creation
    const lsResult = await sandbox.runCommand("ls", [], {
        working_dir: "/home/user/project"
    });
    console.log(`Created files: ${lsResult.stdout}`);
} finally {
    await sandbox.kill();
}

Command Timeouts

CLI Command
Python SDK
JavaScript SDK

# Command with timeout (3 second timeout for 10 second sleep - will timeout)
gravixlayer sandbox run YOUR_SANDBOX_ID sleep --args="10" --timeout=3000

# Quick command (should succeed within 1 second timeout)
gravixlayer sandbox run YOUR_SANDBOX_ID echo --args="Quick command" --timeout=1000

Output:

ERROR: {"error":"Failed to execute command: execution timed out"}

Command executed (exit code: 0)
Duration: 95ms
Success: True

STDOUT:
Quick command

with Sandbox.create() as sandbox:
    # Command with timeout (milliseconds)
    try:
        result = sandbox.run_command(
            "sleep", 
            ["10"],  # Sleep for 10 seconds
            timeout=3000  # 3 second timeout
        )
        print("Command completed")
    except Exception as e:
        print(f"Command timed out: {e}")
    
    # Quick command (should succeed)
    result = sandbox.run_command(
        "echo",
        ["Quick command"],
        timeout=1000  # 1 second timeout
    )
    print(f"Quick command result: {result.stdout}")

const sandbox = await Sandbox.create();
try {
    // Command with timeout (milliseconds)
    try {
        const result = await sandbox.runCommand("sleep", ["10"], {
            timeout: 3000  // 3 second timeout
        });
        console.log("Command completed");
    } catch (error) {
        console.log(`Command timed out: ${error.message}`);
    }
    
    // Quick command (should succeed)
    const result = await sandbox.runCommand("echo", ["Quick command"], {
        timeout: 1000  // 1 second timeout
    });
    console.log(`Quick command result: ${result.stdout}`);
} finally {
    await sandbox.kill();
}

Environment Variables

CLI Command
Python SDK
JavaScript SDK

# Note: Environment variables are not directly supported in CLI run command
# Use the Python/JavaScript SDK for environment variable support
# Alternative: Set variables in shell command
gravixlayer sandbox run YOUR_SANDBOX_ID sh --args="-c" --args="export CUSTOM_VAR='custom_value' && echo \$CUSTOM_VAR"

# Check current environment
gravixlayer sandbox run YOUR_SANDBOX_ID env

Output:

Command executed (exit code: 0)
Duration: 110ms
Success: True

STDOUT:
custom_value

Command executed (exit code: 0)
Duration: 95ms
Success: True

STDOUT:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOME=/root
USER=root
...

with Sandbox.create() as sandbox:
    # Command with environment variables
    result = sandbox.run_command(
        "env",
        environment={"CUSTOM_VAR": "custom_value", "DEBUG": "true"}
    )
    
    print("Environment variables:")
    for line in result.stdout.split('\n'):
        if 'CUSTOM_VAR' in line or 'DEBUG' in line:
            print(f"  {line}")
    
    # Use environment variable in command
    result = sandbox.run_command(
        "sh",
        ["-c", "echo $CUSTOM_VAR"],
        environment={"CUSTOM_VAR": "Hello from environment"}
    )
    print(f"Environment variable value: {result.stdout}")

const sandbox = await Sandbox.create();
try {
    // Using client for environment variables
    const client = new GravixLayer();
    
    const result = await client.sandbox.sandboxes.runCommand(
        sandbox.sandbox_id,
        "env",
        { environment: { CUSTOM_VAR: "custom_value", DEBUG: "true" } }
    );
    
    console.log("Environment variables:");
    for (const line of result.stdout.split('\n')) {
        if (line.includes('CUSTOM_VAR') || line.includes('DEBUG')) {
            console.log(`  ${line}`);
        }
    }
    
    // Use environment variable in command
    const envResult = await client.sandbox.sandboxes.runCommand(
        sandbox.sandbox_id,
        "sh",
        { 
            args: ["-c", "echo $CUSTOM_VAR"],
            environment: { CUSTOM_VAR: "Hello from environment" }
        }
    );
    console.log(`Environment variable value: ${envResult.stdout}`);
} finally {
    await sandbox.kill();
}

Simple File Commands

CLI Command
Python SDK
JavaScript SDK

# Create a file
gravixlayer sandbox run YOUR_SANDBOX_ID touch --args="/home/sandbox/hello.txt"

# List files
gravixlayer sandbox run YOUR_SANDBOX_ID ls --args="/home/sandbox"

# Check file exists
gravixlayer sandbox run YOUR_SANDBOX_ID ls --args="-la" --args="/home/sandbox/hello.txt"

# Create directory and file
gravixlayer sandbox run YOUR_SANDBOX_ID mkdir --args="-p" --args="/home/sandbox/test"
gravixlayer sandbox run YOUR_SANDBOX_ID touch --args="/home/sandbox/test/example.txt"
gravixlayer sandbox run YOUR_SANDBOX_ID ls --args="-la" --args="/home/sandbox/test"

Output:

Command executed (exit code: 0)
Duration: 105ms
Success: True

Command executed (exit code: 0)
Duration: 85ms
Success: True

STDOUT:
hello.txt

Command executed (exit code: 0)
Duration: 90ms
Success: True

STDOUT:
-rw-r--r-- 1 root root 0 Oct 28 10:30 /workspace/hello.txt

Command executed (exit code: 0)
Duration: 95ms
Success: True

STDOUT:
total 8
drwxr-xr-x 2 root root 4096 Oct 28 10:30 .
drwxr-xr-x 3 root root 4096 Oct 28 10:30 ..
-rw-r--r-- 1 root root    0 Oct 28 10:30 example.txt

with Sandbox.create() as sandbox:
    # Create a file
    result = sandbox.run_command("touch", ["/workspace/hello.txt"])
    print(f"Create file exit code: {result.exit_code}")
    
    # List files
    result = sandbox.run_command("ls", ["/workspace"])
    print(f"Files: {result.stdout}")
    
    # Check file exists
    result = sandbox.run_command("ls", ["-la", "/workspace/hello.txt"])
    print(f"File details: {result.stdout}")

Output:

Create file exit code: 0
Files: hello.txt
File details: -rw-r--r-- 1 root root 0 Oct 28 10:30 /workspace/hello.txt

const sandbox = await Sandbox.create();
try {
    // Create a file
    const result1 = await sandbox.runCommand("touch", ["/workspace/hello.txt"]);
    console.log(`Create file exit code: ${result1.exit_code}`);
    
    // List files
    const result2 = await sandbox.runCommand("ls", ["/workspace"]);
    console.log(`Files: ${result2.stdout}`);
    
    // Check file exists
    const result3 = await sandbox.runCommand("ls", ["-la", "/workspace/hello.txt"]);
    console.log(`File details: ${result3.stdout}`);
} finally {
    await sandbox.kill();
}

Next Steps

Context Management

Use isolated execution contexts

Templates

Explore available environment templates

File Operations

Manage files and directories

Code Execution

Execute Python and JavaScript code

Getting Started

Core Features

Advanced Usage

Resources

Command Execution

Basic Command Execution

Simple Commands

System Information Commands

Advanced Command Options

Working Directory

Command Timeouts

Environment Variables

Simple File Commands

Next Steps

Context Management

Templates

File Operations

Code Execution

Getting Started

Core Features

Advanced Usage

Resources

​Basic Command Execution

​Simple Commands

​System Information Commands

​Advanced Command Options

​Working Directory

​Command Timeouts

​Environment Variables

​Simple File Commands

​Next Steps

Context Management

Templates

File Operations

Code Execution

Basic Command Execution

Simple Commands

System Information Commands

Advanced Command Options

Working Directory

Command Timeouts

Environment Variables

Simple File Commands

Next Steps