Framework Integration

SmolVM gives your AI agents a safe place to run code. Instead of executing LLM-generated commands directly on your machine, SmolVM spins up an isolated microVM in milliseconds, runs the code inside it, and tears it down when finished.

Install the agent framework extras before following these examples:

pip install "smolvm[examples]"

This adds PydanticAI, OpenAI Agents SDK, LangChain, and Playwright as dependencies. See installation for details.

Agentor

Agentor is Celesto’s own agent framework. It has built-in SmolVM support through SmolVMRuntime, so your agent’s shell commands run inside a sandbox automatically.

from agentor import Agentor
from agentor.runtime import SmolVMRuntime
from agentor.tools import ShellTool


def main() -> None:
    runtime = SmolVMRuntime(memory=1024, disk_size=2048)

    try:
        agent = Agentor(
            name="SmolVM Shell Agent",
            model="gpt-5",
            tools=[ShellTool(executor=runtime)],
            instructions="Use shell commands to inspect files inside the SmolVM sandbox.",
        )

        result = agent.run(
            "Install uv and use the Python interpreter to print 'Hello, World!'. Return both outputs."
        )
        print(result)
    finally:
        runtime.close()


if __name__ == "__main__":
    main()

See the full working example in main.py.

PydanticAI

from smolvm import SmolVM
from pydantic_ai import Agent

def run_in_smolvm(command: str, timeout: int = 30) -> str:
    """Run a shell command inside an ephemeral SmolVM sandbox.

    Args:
        command: Shell command to execute inside the sandbox guest.
        timeout: Maximum number of seconds to wait for the command.
    """
    with SmolVM() as vm:
        result = vm.run(command, timeout=timeout)
        return (
            f"exit_code: {result.exit_code}\n"
            f"stdout:\n{result.stdout.strip() or '<empty>'}\n"
            f"stderr:\n{result.stderr.strip() or '<empty>'}"
        )

agent = Agent(
    "openai:gpt-4.1",
    instructions=(
        "You are a coding assistant with access to a secure SmolVM sandbox. "
        "For shell or Python inspection requests, call run_in_smolvm exactly "
        "once and then summarize the result."
    ),
)
agent.tool_plain(docstring_format="google", require_parameter_descriptions=True)(
    run_in_smolvm
)

result = agent.run_sync("Run `uname -a && python3 --version` in the sandbox.")
print(result.output)

See the full working example in examples/agent_tools/pydanticai_tool.py.

Reusable sandbox across turns

If your agent needs to maintain state between tool calls, keep the VM alive across invocations:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from smolvm import SmolVM

@dataclass
class SandboxDeps:
    vm_id: str | None = None

def _connect_vm(deps: SandboxDeps) -> SmolVM:
    """Return the active sandbox, creating it on first use."""
    if deps.vm_id is None:
        vm = SmolVM()
        vm.start()
        deps.vm_id = vm.vm_id
        return vm
    return SmolVM.from_id(deps.vm_id)

def _cleanup_vm(vm_id: str | None) -> None:
    """Delete the reusable sandbox if one was created."""
    if vm_id is None:
        return
    vm = SmolVM.from_id(vm_id)
    try:
        vm.delete()
    finally:
        vm.close()

def run_in_reusable_smolvm(
    ctx: RunContext[SandboxDeps], command: str, timeout: int = 30
) -> str:
    """Run a shell command inside a reusable SmolVM sandbox.

    Args:
        command: Shell command to execute inside the sandbox guest.
        timeout: Maximum number of seconds to wait for the command.
    """
    vm = _connect_vm(ctx.deps)
    try:
        result = vm.run(command, timeout=timeout)
        return (
            f"exit_code: {result.exit_code}\n"
            f"stdout:\n{result.stdout.strip() or '<empty>'}\n"
            f"stderr:\n{result.stderr.strip() or '<empty>'}"
        )
    finally:
        vm.close()

agent = Agent(
    "openai:gpt-4.1",
    deps_type=SandboxDeps,
    instructions="You have access to a persistent SmolVM sandbox.",
)
agent.tool(docstring_format="google", require_parameter_descriptions=True)(
    run_in_reusable_smolvm
)

deps = SandboxDeps()
try:
    agent.run_sync("Write 'hello' to /tmp/note.txt", deps=deps)
    agent.run_sync("Read /tmp/note.txt and confirm the contents", deps=deps)
finally:
    _cleanup_vm(deps.vm_id)

See the full working example in examples/agent_tools/pydanticai_reusable_tool.py.

OpenAI Agents SDK

Use SmolVM as a function tool in the OpenAI Agents SDK:

import asyncio
from agents import Agent, Runner, function_tool
from smolvm import SmolVM

def run_in_smolvm(command: str, timeout: int = 30) -> str:
    """Run a shell command inside an ephemeral SmolVM sandbox.

    Args:
        command: Shell command to execute inside the sandbox guest.
        timeout: Maximum number of seconds to wait for the command.
    """
    with SmolVM() as vm:
        result = vm.run(command, timeout=timeout)
        return (
            f"exit_code: {result.exit_code}\n"
            f"stdout:\n{result.stdout.strip() or '<empty>'}\n"
            f"stderr:\n{result.stderr.strip() or '<empty>'}"
        )

agent = Agent(
    name="SmolVM Assistant",
    model="gpt-4.1",
    instructions=(
        "You are a coding assistant with access to a secure SmolVM sandbox. "
        "For shell or Python inspection requests, call run_in_smolvm exactly "
        "once and then summarize the result."
    ),
    tools=[function_tool(run_in_smolvm)],
)

async def main():
    result = await Runner.run(
        agent, "Run `uname -a && python3 --version` in the sandbox."
    )
    print(result.final_output)

asyncio.run(main())

See the full working example in examples/agent_tools/openai_agents_tool.py.

Use SmolVM as a SandboxAgent provider

If you want OpenAI’s SandboxAgent to treat SmolVM as its full working computer (not just a one-shot tool), use the ready-made provider in the Celesto SDK. It plugs into Runner and SandboxRunConfig directly, and ships alongside a hosted Celesto option you can swap in without changing your agent code. See OpenAI Agents SDK sandboxes for the full guide.

LangChain

Wrap SmolVM as a LangChain tool:

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from smolvm import SmolVM

@tool
def run_in_smolvm(command: str, timeout: int = 30) -> str:
    """Run a shell command inside an ephemeral SmolVM sandbox.

    Args:
        command: Shell command to execute inside the sandbox guest.
        timeout: Maximum number of seconds to wait for the command.
    """
    with SmolVM() as vm:
        result = vm.run(command, timeout=timeout)
        return (
            f"exit_code: {result.exit_code}\n"
            f"stdout:\n{result.stdout.strip() or '<empty>'}\n"
            f"stderr:\n{result.stderr.strip() or '<empty>'}"
        )

llm = ChatOpenAI(model="gpt-4.1")
agent = create_react_agent(llm, [run_in_smolvm])

result = agent.invoke({
    "messages": [{"role": "user", "content": "Run uname -a in the sandbox"}]
})
print(result["messages"][-1].content)

See the full working example in examples/agent_tools/langchain_tool.py.

Browser and desktop sandboxes

SmolVM can give your agent a browser or a full desktop inside a disposable sandbox. Use browser mode for websites and Playwright automation. Use desktop mode when the agent needs a visible screen that a computer-use driver can control. VNC means Virtual Network Computing, a standard way to view and control a remote screen.

browser_agent.py

from smolvm import SmolVM

with SmolVM.browser(
    headless=False,
    record_video=True,
    viewport={"width": 1440, "height": 900},
) as browser_sandbox:
    print(f"Session: {browser_sandbox.session_id}")
    print(f"CDP URL: {browser_sandbox.cdp_url}")
    print(f"Viewer URL: {browser_sandbox.viewer_url}")
    print(f"Display URL: {browser_sandbox.display_url}")

    browser = browser_sandbox.connect_playwright()
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com", wait_until="networkidle")

    browser_sandbox.screenshot("screenshot.png")
    browser.close()

See the full working example in examples/browser_sandbox.py.

Browser and desktop modes

Mode	Description
`SmolVM.browser(headless=True)`	Starts Chromium for automation and returns `cdp_url`.
`SmolVM.browser(headless=False)`	Starts Chromium with `cdp_url`, `viewer_url`, and `display_url`.
`SmolVM.desktop()`	Starts a full desktop with `viewer_url` and `display_url`.

cdp_url is the browser automation address used by Playwright and other Chrome DevTools Protocol clients. viewer_url opens in your browser so you can watch the screen. display_url is the VNC address for desktop viewers and computer-use agents.

Computer-use with OpenAI

Combine a visible browser or desktop sandbox with OpenAI’s computer-use API for autonomous browsing and desktop workflows. The model sees screenshots and sends back click, type, and scroll instructions.

computer_use_browser.py

from openai import OpenAI
from smolvm import SmolVM

client = OpenAI()

with SmolVM.browser(
    headless=False,
    viewport={"width": 1440, "height": 900},
) as browser_sandbox:
    browser = browser_sandbox.connect_playwright()
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com", wait_until="domcontentloaded")

    response = client.responses.create(
        model="gpt-5.4",
        tools=[{"type": "computer"}],
        input="Find the main heading on the page.",
    )

    for item in response.output:
        if item.type == "computer_call":
            # Execute browser actions based on the model's instructions.
            pass

    browser.close()

See the full working example in examples/agent_tools/computer_use_browser.py for a complete computer-use loop with action handling and domain allowlisting.

Generic tool pattern

If you use a framework not listed above, the core pattern is the same:

from smolvm import SmolVM

def run_in_smolvm(command: str, timeout: int = 30) -> str:
    """Run a shell command inside an ephemeral SmolVM sandbox."""
    with SmolVM() as vm:
        result = vm.run(command, timeout=timeout)
        if result.ok:
            return result.stdout
        return f"Error (exit {result.exit_code}): {result.stderr}"

Get Started

Features

Guides

Architecture

Operations

Framework Integration

Agentor

PydanticAI

Reusable sandbox across turns

OpenAI Agents SDK

Use SmolVM as a SandboxAgent provider

LangChain

Browser and desktop sandboxes

Browser and desktop modes

Computer-use with OpenAI

Generic tool pattern

​Agentor

​PydanticAI

​Reusable sandbox across turns

​OpenAI Agents SDK

​Use SmolVM as a SandboxAgent provider

​LangChain

​Browser and desktop sandboxes

​Browser and desktop modes

​Computer-use with OpenAI

​Generic tool pattern

Agentor

PydanticAI

Reusable sandbox across turns

OpenAI Agents SDK

Use SmolVM as a SandboxAgent provider

LangChain

Browser and desktop sandboxes

Browser and desktop modes

Computer-use with OpenAI

Generic tool pattern