XIAOXU CHANG for ByteDance Open Source

Posted on Mar 31

Inside AIO Sandbox (Part 1): Files & Shell — The Foundations of Agent Execution

#ai #agents

Modern AI agents are no longer just generating text—they are expected to write files, modify code, and execute commands.
But doing this directly on your local machine or production systems is risky and hard to control.
This is where AIO Sandbox comes in.
It provides an isolated, programmable environment where agents can safely:

create and manipulate files
run shell commands
execute code
produce artifacts

In this first post, we’ll focus on the two most fundamental capabilities:

🧩 Filesystem (state)
⚙️ Shell (execution)

By the end, you’ll see how these combine into a complete runtime for agents.

🌐 Multi-language SDK Support

While this tutorial uses Python, AIO Sandbox is not limited to Python developers.
The agent-sandbox SDK also supports:

TypeScript / JavaScript
Go (Golang)

👉 This makes it easy to integrate AIO Sandbox into a wide range of agent frameworks, backend services, and developer stacks.

🛠️ Prerequisites

Python 3.12+
A running AIO Sandbox instance at http://localhost:8080
Python SDK installed

pip install agent-sandbox

🧠 Mental Model

Think of AIO Sandbox as a remote, disposable Linux machine that your agent controls via APIs.

Filesystem → where data and artifacts live
Shell → how actions are executed

Simple Flow:
Agent → API → Sandbox → Filesystem + Shell

📁 Part 1 — Working with Files

Let’s start by treating the sandbox like a filesystem.

1.Hello Sandbox Files

Goal: introduce write_file, read_file, and list_path.

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

home_dir = client.sandbox.get_context().home_dir

notes_file = f"{home_dir}/hello.txt"

# Write a text file
write_result = client.file.write_file(
    file=notes_file,
    content="Hello from AIO Sandbox!\nThis file lives inside the sandbox.",
)

print("Wrote bytes:", getattr(write_result.data, "bytes_written", None))

# Read it back
read_result = client.file.read_file(file=notes_file)
print("File content:")
print(read_result.data.content)

# List files in the sandbox home directory
list_result = client.file.list_path(
    path=home_dir,
    include_size=True,
    sort_by="name",
)

items_to_list = getattr(list_result.data, 'files', getattr(list_result.data, 'entries', []))

for item in items_to_list:
    print(f"- {item.path} ({getattr(item, 'size', 'unknown')} bytes)")

2.Edit a Config File

Goal: show replace_in_file and search_in_file.
💡 Agents often follow a loop:

modify → verify → proceed

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

home_dir = client.sandbox.get_context().home_dir
config_file = f"{home_dir}/app.env"

# Create a simple config file
client.file.write_file(
    file=config_file,
    content="MODE=dev\nPORT=8000\nDEBUG=true\n",
)

# Replace one value
client.file.replace_in_file(
    file=config_file,
    old_str="MODE=dev",
    new_str="MODE=prod",
)

# Search to verify
search_result = client.file.search_in_file(
    file=config_file,
    regex=r"MODE=.*",
)

print("Search result:")
print(search_result)

# Read final content
final_file = client.file.read_file(file=config_file)
print("\nUpdated config:")
print(final_file.data.content)

3.Write and Export an Artifact

Goal: show download_file.

sandbox outputs can be streamed out cleanly
useful for logs, reports, generated code, screenshots, notebooks, datasets

home_dir = client.sandbox.get_context().home_dir
report_file = f"{home_dir}/report.txt"

# Create an artifact inside the sandbox
client.file.write_file(
    file=report_file,
    content="Run complete\nStatus: success\nArtifacts generated: 1\n",
)

# Download it from the sandbox to the local machine
with open("downloaded_report.txt", "wb") as f:
    for chunk in client.file.download_file(path=report_file):
        f.write(chunk)

print("Downloaded sandbox artifact to ./downloaded_report.txt")

4.Discover files

result = client.file.find_files(
    path=home_dir,
    glob="*.txt",
)

print(result)

⚙️ Part 2 — Executing Commands (Shell)

Now let’s make the sandbox do work.

⚠️ Important Notes

Shell commands must be passed as keyword arguments:

exec_command(command="...")

Output is available at:

result.data.output

Exit status:

result.data.exit_code

1. Basic shell command execution (Hello World)

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

result = client.shell.exec_command(
    command="echo 'Hello from sandbox shell'"
)

print("Output:", result.data.output)
print("Exit code:", result.data.exit_code)

2. Inspect the sandbox environment

result = client.shell.exec_command(command="pwd")
print("PWD:", result.data.output)

result = client.shell.exec_command(command="ls -la")
print(result.data.output)

👉 The sandbox behaves like a real Linux environment.

3. Execute a Python script

home_dir = client.sandbox.get_context().home_dir
script_path = f"{home_dir}/hello.py"

client.file.write_file(
    file=script_path,
    content="""
print("Running inside sandbox")
print("Computation:", 10 * 5)
""",
)

result = client.shell.exec_command(
    command=f"python3 {script_path}"
)

print(result.data.output)

🔥 This is an important pattern:

Agent writes code → executes it → observes output

4. Install and use a package

# Install package
client.shell.exec_command(command="pip install requests")

# Verify installation
result = client.shell.exec_command(
    command='python3 -c "import requests; print(requests.__version__)"'
)

print("Requests version:", result.data.output)

💡 Shows:

sandbox is mutable
supports dynamic dependencies

5. Chain commands

result = client.shell.exec_command(
    command="mkdir -p demo && echo 'hello' > demo/file.txt && cat demo/file.txt"
)

print(result.data.output)

6. Check exit codes

result = client.shell.exec_command(command="ls non_existent_file")

print("Output:", result.data.output)
print("Exit code:", result.data.exit_code)

Agents should check exit codes, not just output.

🧩 Bringing It Together

At this point, we’ve seen:

Filesystem (state)

Core primitives to showcase:

create
read
modify
search
list
discover

Shell (execution)