Run any language / command

import asyncio

from boxlite import SimpleBox

async def main() -> None:
    # The box is created lazily: the microVM actually starts on entering async with
    async with SimpleBox(image="alpine:latest") as box:
        # cmd is the program name; *args are its arguments
        result = await box.exec("echo", "Hello from BoxLite!")

        print("stdout:", result.stdout.strip())
        print("stderr:", result.stderr.strip())
        print("exit_code:", result.exit_code)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except RuntimeError as e:
        # No virtualization / image pull failure raises a standard RuntimeError (see Troubleshooting)
        print(f"BoxLite failed to run: {e}")

import asyncio

from boxlite import SimpleBox

async def main() -> None:
    # Run any language: if the image has python you can exec python; node/go/bash work the same way
    async with SimpleBox(image="python:alpine") as box:
        agent_code = "import sys; print(sys.version.split()[0])"
        result = await box.exec("python", "-c", agent_code)

        if result.exit_code == 0:
            print("Python version in box:", result.stdout.strip())
        else:
            # Note: a non-zero exit code does *not* raise; you must check exit_code
            print("Command failed:", result.stderr.strip())

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except RuntimeError as e:
        print(f"BoxLite failed to run: {e}")

import { SimpleBox } from "@boxlite-ai/boxlite";

async function main(): Promise<void> {
  const box = new SimpleBox({ image: "alpine:latest" });
  try {
    // exec(cmd, ...args)
    const result = await box.exec("echo", "Hello from BoxLite!");
    console.log("stdout:", result.stdout.trim());
    console.log("exitCode:", result.exitCode); // note the camelCase exitCode
  } catch (err) {
    console.error("BoxLite failed to run:", err);
  } finally {
    await box.stop(); // release resources (auto_remove defaults to true)
  }
}

main();

import asyncio

from boxlite import SimpleBox

async def main() -> None:
    async with SimpleBox(image="python:alpine") as box:
        # env uses a dict; user has the form "<name|uid>[:<group|gid>]", like docker exec --user
        result = await box.exec(
            "env",
            env={"FOO": "bar", "BAZ": "qux"},  # must be a dict
            cwd="/tmp",                          # working directory inside the container
            user="nobody",                       # run as non-root
        )
        # The env command output contains only the injected variables (FOO/BAZ), not PWD.
        # To confirm cwd took effect, run pwd separately (see below); it returns /tmp.
        for line in result.stdout.splitlines():
            if line.startswith(("FOO=", "BAZ=")):
                print(line)
        # Run pwd separately to confirm cwd
        pwd = await box.exec("pwd", cwd="/tmp", user="nobody")
        print("cwd:", pwd.stdout.strip())  # -> /tmp

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except RuntimeError as e:
        print(f"BoxLite failed to run: {e}")

import asyncio

from boxlite import SimpleBox

async def main() -> None:
    async with SimpleBox(image="alpine:latest") as box:
        # Drill down to the underlying native Box handle for true streaming reads
        native_box = box._box
        # Native Box.exec: the parameter is named timeout_secs (not timeout)
        execution = await native_box.exec(
            "sh",
            ["-c", "for i in 1 2 3; do echo line-$i; sleep 1; done"],
            timeout_secs=30.0,
        )

        stdout = execution.stdout()  # async iterator
        if stdout is not None:
            async for chunk in stdout:
                text = chunk.decode("utf-8", "replace") if isinstance(chunk, bytes) else chunk
                print("streamed:", text.rstrip())

        result = await execution.wait()  # get the exit code
        print("exit_code:", result.exit_code)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except RuntimeError as e:
        print(f"BoxLite failed to run: {e}")

import asyncio

from boxlite import SimpleBox

async def main() -> None:
    async with SimpleBox(image="alpine:latest") as box:
        # Set a 2-second timeout on a long-running command
        result = await box.exec("sleep", "10", timeout=2.0)
        # After ~2 seconds the process is terminated by SIGTERM; exit_code is -15 (negative = killed by signal).
        print("exit_code:", result.exit_code)        # -15 (terminated by the timeout SIGTERM)
        # On the timeout path, error_message is None.
        # To detect a timeout, check that exit_code is negative / non-zero.
        print("error_message:", result.error_message)  # None

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except RuntimeError as e:
        print(f"BoxLite failed to run: {e}")

import asyncio
from boxlite import SimpleBox, SecurityOptions, NetworkSpec
from boxlite.boxlite import AdvancedBoxOptions  # not exported at the top level

async def main():
    try:
        async with SimpleBox(
            image="python:slim",
            # Tightest OS-level sandbox: jailer + seccomp + rlimits
            advanced=AdvancedBoxOptions(security=SecurityOptions.maximum()),
            # Only these hosts resolve; everything else is DNS-sinkholed
            network=NetworkSpec(mode="enabled", allow_net=["pypi.org", "files.pythonhosted.org"]),
        ) as box:
            result = await box.exec("python", "-c", "print('hello from a locked-down box')")
            print(result.stdout, result.exit_code)
    except RuntimeError as exc:
        print(f"sandbox error: {exc}")

asyncio.run(main())

# Wrong: env passed as a list
await box.exec("env", env=[("FOO", "bar")])   # a list has no .items()

# Correct: env passed as a dict
await box.exec("env", env={"FOO": "bar"})      # ok

result = await box.exec("false")          # exit code 1, but does not raise
if result.exit_code != 0:
    print("command failed:", result.stderr)