Python SDK

The official Vibengine Python SDK provides a simple, Pythonic interface for creating and managing cloud sandboxes. It supports both synchronous and asynchronous usage.

Installation

pip install vibengine

poetry add vibengine

uv add vibengine

Initialization

from vibengine import Sandbox

The SDK reads your API key from the VE_API_KEY environment variable by default. You can also pass it explicitly when creating a sandbox.

Sandbox Class

The Sandbox class is the primary interface for interacting with Vibengine cloud sandboxes.

`Sandbox(template?, timeout?, envs?, metadata?)`

Creates a new sandbox instance and waits for it to be ready. The constructor can be used directly or via the context manager protocol.

Parameters:

Parameter	Type	Default	Description
`template`	`str`	`"base"`	Template to use for the sandbox.
`timeout`	`int`	`300`	Sandbox timeout in seconds.
`envs`	`dict[str, str]`	`{}`	Environment variables for the sandbox.
`metadata`	`dict[str, str]`	`{}`	Custom metadata key-value pairs.
`api_key`	`str or None`	`None`	API key override (uses env var if unset).

Returns: Sandbox

from vibengine import Sandbox

# Basic creation
sandbox = Sandbox()

# With options
sandbox = Sandbox(
    template="python-data",
    timeout=600,
    envs={"DATABASE_URL": "postgres://..."},
    metadata={"user": "jack", "purpose": "analysis"},
)

# Using context manager (auto-kills on exit)
with Sandbox(template="base") as sandbox:
    result = sandbox.commands.run("echo 'Hello!'")
    print(result.stdout)
# Sandbox is automatically killed here

`Sandbox.connect(sandbox_id)`

Reconnects to an already running sandbox by its ID. This is useful when you need to resume interaction with a sandbox across different requests or processes.

Parameters:

Parameter	Type	Description
`sandbox_id`	`str`	The unique sandbox identifier.

Returns: Sandbox

from vibengine import Sandbox

sandbox = Sandbox.connect("sbx_a1b2c3d4e5")
result = sandbox.commands.run("echo 'reconnected!'")
print(result.stdout)  # "reconnected!"

`sandbox.sandbox_id`

The unique identifier for this sandbox instance. Use this to reconnect later with Sandbox.connect().

Type: str

sandbox = Sandbox()
print(sandbox.sandbox_id)  # "sbx_a1b2c3d4e5"

Commands

`sandbox.commands.run(cmd, **kwargs)`

Executes a shell command inside the sandbox and waits for it to complete.

Parameters:

Parameter	Type	Default	Description
`cmd`	`str`	required	The shell command to execute.
`cwd`	`str`	`"/home"`	Working directory for the command.
`envs`	`dict[str, str]`	`{}`	Additional environment variables.
`timeout`	`int`	`60`	Command execution timeout in seconds.

Returns: CommandResult

class CommandResult:
    stdout: str
    stderr: str
    exit_code: int

result = sandbox.commands.run("ls -la /home")
print(result.stdout)
print(result.exit_code)  # 0

# With options
result = sandbox.commands.run(
    "python main.py",
    cwd="/home/project",
    envs={"DEBUG": "true"},
    timeout=30,
)

Filesystem

`sandbox.files.read(path)`

Reads the contents of a file inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`str`	Absolute path to the file.

Returns: str

content = sandbox.files.read("/home/project/config.json")
import json
config = json.loads(content)
print(config)

`sandbox.files.write(path, content)`

Writes content to a file inside the sandbox. Creates the file if it does not exist, or overwrites it if it does. Parent directories are created automatically.

Parameters:

Parameter	Type	Description
`path`	`str`	Absolute path to the file.
`content`	`str`	The content to write to the file.

Returns: None

sandbox.files.write("/home/project/main.py", """
import json

data = {"message": "Hello from Vibengine!"}
print(json.dumps(data))
""")

`sandbox.files.list(path)`

Lists the contents of a directory inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`str`	Absolute path to the directory.

Returns: list[FileInfo]

class FileInfo:
    name: str
    type: str  # "file" or "directory"
    size: int

entries = sandbox.files.list("/home/project")
for entry in entries:
    print(f"{entry.type}: {entry.name} ({entry.size} bytes)")

`sandbox.files.remove(path)`

Deletes a file or directory inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`str`	Absolute path to the file or directory.

Returns: None

sandbox.files.remove("/home/project/temp.txt")

Sandbox Lifecycle

`sandbox.kill()`

Immediately terminates the sandbox and releases all associated resources. After calling this method, the sandbox can no longer be used or reconnected to.

Returns: None

sandbox = Sandbox()
# ... do work ...
sandbox.kill()

When using the context manager (with statement), kill() is called automatically when the block exits, even if an exception occurs.

`sandbox.set_timeout(timeout)`

Extends or updates the timeout for the sandbox. The timeout is measured from the current moment, not from the original creation time.

Parameters:

Parameter	Type	Description
`timeout`	`int`	New timeout value in seconds.

Returns: None

sandbox = Sandbox(timeout=60)

# Extend to 10 more minutes from now
sandbox.set_timeout(600)

`sandbox.get_hostname(port=None)`

Returns the hostname for accessing the sandbox. If a port is specified, returns a hostname that routes to that specific port inside the sandbox.

Parameters:

Parameter	Type	Default	Description
`port`	`int or None`	`None`	Optional port number to expose.

Returns: str

hostname = sandbox.get_hostname()
print(hostname)  # "sbx_a1b2c3d4e5.vibengine.ai"

web_hostname = sandbox.get_hostname(3000)
print(web_hostname)  # "sbx_a1b2c3d4e5-3000.vibengine.ai"

Async Support

The Python SDK also provides an async variant for use with asyncio.

from vibengine import AsyncSandbox
import asyncio

async def main():
    sandbox = await AsyncSandbox.create(
        template="base",
        timeout=300,
    )

    result = await sandbox.commands.run("echo 'Hello async!'")
    print(result.stdout)

    await sandbox.kill()

asyncio.run(main())

The AsyncSandbox class mirrors the synchronous Sandbox API. All methods that perform I/O are awaitable:

from vibengine import AsyncSandbox
import asyncio

async def main():
    async with AsyncSandbox(template="base") as sandbox:
        # All I/O methods are awaitable
        await sandbox.files.write("/home/script.py", "print('hello')")
        result = await sandbox.commands.run("python /home/script.py")
        print(result.stdout)

        files = await sandbox.files.list("/home")
        for f in files:
            print(f.name)

asyncio.run(main())

Type Hints

The SDK is fully typed and works with mypy and pyright out of the box.

from vibengine import Sandbox
from vibengine.types import CommandResult, FileInfo

sandbox: Sandbox = Sandbox(template="base")

result: CommandResult = sandbox.commands.run("whoami")
print(result.stdout)  # str
print(result.exit_code)  # int

files: list[FileInfo] = sandbox.files.list("/home")
for f in files:
    name: str = f.name
    file_type: str = f.type
    size: int = f.size

Full Example

from vibengine import Sandbox

def main():
    # Create a sandbox using context manager
    with Sandbox(template="base", timeout=300) as sandbox:
        print(f"Sandbox created: {sandbox.sandbox_id}")

        # Write a Python script
        sandbox.files.write("/home/app.py", """
import http.server
import socketserver

PORT = 3000

class Handler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-type", "text/plain")
        self.end_headers()
        self.wfile.write(b"Hello from Vibengine!")

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print(f"Server running on port {PORT}")
    httpd.serve_forever()
""")

        # Run the server in the background
        sandbox.commands.run("python /home/app.py &")

        # Get the public URL
        url = sandbox.get_hostname(3000)
        print(f"App available at: https://{url}")

        # List files
        files = sandbox.files.list("/home")
        for f in files:
            print(f"  {f.name} ({f.type})")

    # Sandbox is automatically killed here
    print("Sandbox terminated.")

if __name__ == "__main__":
    main()

For additional examples and guides, visit the Vibengine documentation.

Python SDK

On this page