Agent Run:Upgrade AgentRun Sandbox to FC Cloud Sandbox

Creating a Sandbox

AgentRun SDK (Before Upgrade): AgentRun follows a two-stage "first build template, then launch sandbox" approach, using sandbox_idle_timeout_seconds to control idle reclamation when launching sandboxes.

from agentrun.sandbox import Sandbox, TemplateInput, TemplateType

# Step 1: Create a template (reusable, for batch-launching sandboxes with the same configuration)
template_name = "my-code-template"
template = Sandbox.create_template(
    input=TemplateInput(
        template_name=template_name,
        template_type=TemplateType.CODE_INTERPRETER,
        # Optional: cpu=2.0, memory=4096, disk_size=10240,
    )
)

# Step 2: Create a sandbox from the template (recommended to use the with context manager)
with Sandbox.create(
    template_type=TemplateType.CODE_INTERPRETER,
    template_name=template_name,
    sandbox_idle_timeout_seconds=600,
) as sandbox:
    print(f"Sandbox ID: {sandbox.sandbox_id}")
# Sandbox is automatically deleted when exiting the with block

# Or manage lifecycle manually
sandbox = Sandbox.create(
    template_type=TemplateType.CODE_INTERPRETER,
    template_name=template_name,
)
try:
    print(f"Sandbox ID: {sandbox.sandbox_id}")
finally:
    sandbox.delete()
# When the template is no longer needed: Sandbox.delete_template(template_name)

E2B SDK (After Upgrade): The simplest approach is to directly use the default template (e.g., base) to launch a sandbox; if custom environments are needed, FC E2B supports building templates from existing images (Template().from_image(...)).

from e2b import Sandbox

# Method 1 (Recommended): Directly use the default template to launch a sandbox without building a template
# Note: Creation must use Sandbox.create(...); the Sandbox(...) constructor is only for connecting to existing sandboxes
with Sandbox.create(
    template="base",  # FC E2B default template name (template can be omitted)
    timeout=300  # Timeout in seconds
) as sandbox:
    print(f"Sandbox ID: {sandbox.sandbox_id}")

# Or manage lifecycle manually
sandbox = Sandbox.create(template="base", timeout=300)
try:
    print(f"Sandbox ID: {sandbox.sandbox_id}")
finally:
    sandbox.kill()

If you need to pre-install dependencies/customize the environment, build a template from an existing image (FC E2B does not support layer-by-layer pip_install builds; please bake dependencies into the image):

from e2b import Sandbox, Template, default_build_logger

# Build a template from an existing image
build = Template.build(
    Template().from_image(
        "registry.cn-hangzhou.aliyuncs.com/your-namespace/your-image:tag",
        username="<registry-user>",
        password="<registry-pass>",
    ),
    name="my-python-template",
    cpu_count=2,
    memory_mb=2048,
    on_build_logs=default_build_logger(),
)

# Launch a sandbox using the built template
with Sandbox.create(template=build.template_id, timeout=300) as sandbox:
    print(f"Sandbox ID: {sandbox.sandbox_id}")

Executing Code

AgentRun SDK (Before Upgrade): Code execution goes through sandbox.context. Direct execute is stateless single execution; use context.create() to get ctx for continuous execute, maintaining variables/imports across rounds.

from agentrun.sandbox import Sandbox, TemplateType
from agentrun.sandbox.model import CodeLanguage

sandbox = Sandbox.create(
    template_type=TemplateType.CODE_INTERPRETER,
    template_name="my-code-template",
)

# Method 1: Stateless single execution
result = sandbox.context.execute(code="import math\nprint(f'Pi = {math.pi:.4f}')")
print(result)

# Method 2: Stateful multi-round execution (variables, imports maintained across rounds)
with sandbox.context.create(language=CodeLanguage.PYTHON) as ctx:
    ctx.execute(code="import numpy as np")
    ctx.execute(code="arr = np.array([1, 2, 3])")
    result = ctx.execute(code="print(arr.sum())")
    print(result)

sandbox.delete()

E2B SDK (After Upgrade):

from e2b_code_interpreter import Sandbox

with Sandbox.create() as sandbox:
    execution = sandbox.run_code("import math\nprint(f'Pi = {math.pi:.4f}')")
    # Note: execution.logs.stdout is List[str] (line by line), use "".join(...) for the whole output
    print("".join(execution.logs.stdout))
    print(execution.results)  # Rich results of the last expression (charts/DataFrame, etc.)

Executing Shell Commands

AgentRun SDK (Before Upgrade): Uses sandbox.process.cmd, where cwd is a required parameter.

from agentrun.sandbox import Sandbox, TemplateType

sandbox = Sandbox.create(
    template_type=TemplateType.CODE_INTERPRETER,
    template_name="my-code-template",
)

result = sandbox.process.cmd(
    command="ls -la /home",
    cwd="/home",     # Required
    timeout=30,
)
print(result["stdout"])
print(f"Exit code: {result['exitCode']}")

sandbox.delete()

E2B SDK (After Upgrade):

from e2b import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.commands.run(
        "ls -la /home",
        cwd="/home",   # Optional
        timeout=30,    # In seconds (the Python SDK uses timeout, not timeout_ms)
    )
    print(result.stdout)
    print(f"Exit code: {result.exit_code}")

    # Long-running background process (e.g., starting a service)
    proc = sandbox.commands.run("python3 -m http.server 8080", cwd="/tmp", background=True)
    print(f"pid: {proc.pid}")

File Operations

AgentRun SDK (Before Upgrade): Distinguishes two sets of APIs—sandbox.file for reading/writing file content within the sandbox; sandbox.file_system handles local ↔ sandbox upload/download and directory management.

from agentrun.sandbox import Sandbox, TemplateType

sandbox = Sandbox.create(
    template_type=TemplateType.CODE_INTERPRETER,
    template_name="my-code-template",
)

# Local → Sandbox: Upload file
sandbox.file_system.upload(
    local_file_path="./data.csv",
    target_file_path="/home/user/data.csv",
)

# Sandbox → Local: Download file
sandbox.file_system.download(
    path="/home/user/result.json",
    save_path="./result.json",
)

# Read/write file content within sandbox
sandbox.file.write(path="/tmp/note.txt", content="hello", create_dir=True)
content = sandbox.file.read(path="/tmp/note.txt")

# Directory operations
sandbox.file_system.mkdir(path="/tmp/mydir", parents=True)
sandbox.file_system.list(path="/tmp")
sandbox.file_system.move(source="/tmp/a.txt", destination="/tmp/b.txt")
sandbox.file_system.remove(path="/tmp/mydir")

sandbox.delete()

E2B SDK (After Upgrade): E2B uses a unified sandbox.files; local ↔ sandbox transfer is achieved by reading/writing bytes locally first.

from e2b import Sandbox

with Sandbox.create() as sandbox:
    # Local → Sandbox (equivalent to AgentRun file_system.upload)
    with open("./data.csv", "rb") as f:
        sandbox.files.write("/home/user/data.csv", f.read())
    
    # Sandbox → Local (equivalent to AgentRun file_system.download)
    # Pass format="bytes" to download binary content
    content = sandbox.files.read("/home/user/result.bin", format="bytes")
    with open("./result.bin", "wb") as f:
        f.write(content)
    
    # Read/write within sandbox (equivalent to AgentRun file.write / file.read)
    sandbox.files.write("/tmp/note.txt", "hello")
    text = sandbox.files.read("/tmp/note.txt")
    
    # Directory operations
    sandbox.files.make_dir("/tmp/mydir")
    sandbox.files.list("/tmp")
    sandbox.files.rename("/tmp/a.txt", "/tmp/b.txt")
    sandbox.files.remove("/tmp/mydir")

Port Exposure & HTTP Services

The AgentRun Code Interpreter sandbox SDK has no port exposure / public access methods. E2B uses get_host(port) to directly obtain the external mapping address of a port—this is a new capability added by the upgrade.

from e2b import Sandbox

with Sandbox.create() as sandbox:
    # Start HTTP service in the background
    sandbox.commands.run("cd /app && python -m http.server 8080", background=True)
    
    # Get externally accessible host
    host = sandbox.get_host(8080)
    print(f"Service address: https://{host}")

Pause & Resume

E2B uses sandbox.pause() to pause the sandbox and Sandbox.connect(sandbox_id) to resume; file/process states within the sandbox are preserved during pause. You can use lifecycle during creation to control "automatic pause after idle timeout + automatic resume on reconnection."

from e2b import Sandbox

# Declare during creation: automatically pause after idle timeout, automatically resume on reconnection
sandbox = Sandbox.create(
    template="base",
    timeout=300,
    lifecycle={"on_timeout": "pause", "auto_resume": True},
)

sandbox.files.write("/tmp/state.txt", "persist-me")
sandbox_id = sandbox.sandbox_id

# Explicitly pause
sandbox.pause()

# Later (can be in another process/machine), resume using sandbox_id; state is preserved
resumed = Sandbox.connect(sandbox_id)
assert resumed.files.read("/tmp/state.txt").strip() == "persist-me"
resumed.kill()

Specifying VPC (Accessing Internal Network Resources)

In FC E2B, VPC and other FC extension configurations are passed through the metadata parameter of Sandbox.create, using fc.sandbox.* convention keys (values as JSON strings).

import json
from e2b import Sandbox

vpc_config = {
    "vpcId": "vpc-xxxxxxxx",
    "securityGroupId": "sg-xxxxxxxx",
    "vSwitchIds": ["vsw-xxxxxxxx"],
}
metadata = {"fc.sandbox.network.vpc": json.dumps(vpc_config)}

with Sandbox.create(template="base", timeout=300, metadata=metadata) as sandbox:
    r = sandbox.commands.run(
        "python3 -c \"import socket; socket.create_connection(('nas-host', 2049), 5); print('ok')\""
    )
    print(r.stdout)

Mounting OSS

Pass OSS mount points through metadata and specify the trusted role (RAM Role ARN) using fc.sandbox.auth.role. After mounting, OSS directories appear as ordinary file system paths within the sandbox.

import json
from e2b import Sandbox

oss_config = {
    "mountPoints": [
        {
            "bucketName": "my-bucket",
            "mountDir": "/mnt/oss",
            "bucketPath": "/some/prefix",
            "endpoint": "oss-cn-hangzhou-internal.aliyuncs.com",
            "readOnly": False,
        }
    ]
}
metadata = {
    "fc.sandbox.storage.oss": json.dumps(oss_config),
    "fc.sandbox.auth.role": "acs:ram::<MainAccountID>:role/<RoleName>",
}

with Sandbox.create(template="base", timeout=300, metadata=metadata) as sandbox:
    files = sandbox.files.list("/mnt/oss")
    print(f"Number of OSS files: {len(files)}")
    sandbox.files.write("/mnt/oss/hello.txt", "written to oss\n")

Creating Sandboxes & Executing Code

AgentRun SDK (Before Upgrade): Also follows a "template → sandbox" two-stage approach and requires explicit waitUntilReadyOrFailed(); code execution goes through sandbox.context.create() + ctx.execute().

import { CodeInterpreterSandbox, Template, TemplateType, CodeLanguage } from '@agentrun/sdk';

// Step 1: Build template and wait until ready
const templateName = 'my-code-template';
const template = await Template.create({
    input: {
        templateName,
        templateType: TemplateType.CODE_INTERPRETER,
        sandboxIdleTimeoutInSeconds: 600,
    },
});
await template.waitUntilReadyOrFailed();

// Step 2: Launch sandbox from template and wait until running/healthy
const sandbox = await CodeInterpreterSandbox.createFromTemplate(templateName);
await sandbox.waitUntilRunning();
await sandbox.waitUntilReadyOrFailed();

// Execute code (through context)
const ctx = await sandbox.context.create({ language: CodeLanguage.PYTHON });
const result = await ctx.execute({
    code: "arr = [1,2,3,4,5]\nprint('Sum:', sum(arr))",
});
console.log(result);

await ctx.delete();
await sandbox.delete();
await template.delete();

E2B SDK (After Upgrade): E2B's JS SDK does not have run_code (Jupyter Kernel is Python-only), so it is recommended to write scripts first and then execute with commands.run.

import { Sandbox } from 'e2b';
import 'dotenv/config';

const sandbox = await Sandbox.create({
    template: 'default',
    timeoutMs: 300_000,  // Note: the E2B JS SDK uses milliseconds
});

try {
    await sandbox.files.write('/tmp/calc.js', `
        const arr = [1, 2, 3, 4, 5];
        console.log('Sum:', arr.reduce((a, b) => a + b, 0));
    `);
    const result = await sandbox.commands.run('node /tmp/calc.js');
    console.log(result.stdout);  // Sum: 15
} finally {
    await sandbox.kill();
}

File Operations

AgentRun SDK (Before Upgrade):

import { CodeInterpreterSandbox } from '@agentrun/sdk';

const sandbox = await CodeInterpreterSandbox.createFromTemplate('my-code-template');
await sandbox.waitUntilReadyOrFailed();

// Local → Sandbox
await sandbox.fileSystem.upload({
    localFilePath: './local.txt',
    targetFilePath: '/home/user/remote.txt',
});

// Sandbox → Local
await sandbox.fileSystem.download({
    path: '/home/user/result.txt',
    savePath: './result.txt',
});

// Read/write within sandbox
await sandbox.file.write({ path: '/tmp/note.txt', content: 'hello' });
const content = await sandbox.file.read({ path: '/tmp/note.txt' });

await sandbox.delete();

E2B SDK (After Upgrade):

import { Sandbox } from 'e2b';
import fs from 'fs';
import 'dotenv/config';

const sandbox = await Sandbox.create();

try {
    // Local → Sandbox
    const content = fs.readFileSync('./local.txt');
    await sandbox.files.write('/home/user/remote.txt', content);
    
    // Sandbox → Local
    const result = await sandbox.files.read('/home/user/result.txt');
    fs.writeFileSync('./result.txt', result);
} finally {
    await sandbox.kill();
}