Environment and startup

import asyncio

import boxlite

async def main():
    try:
        # at construction time, env is list[tuple[str, str]] (note: different from the dict used by exec(env=...))
        # note that working_dir must be a directory that already exists in the image, otherwise exec raises RuntimeError.
        # alpine ships with /tmp; to use a custom directory like /work, create it first via exec mkdir.
        async with boxlite.SimpleBox(
            image="alpine:latest",
            env=[("APP_ENV", "production"), ("LANG", "C.UTF-8")],
            user="1000:1000",     # run as uid=1000, gid=1000 (non-root)
            working_dir="/tmp",   # commands run in this directory by default (must already exist in the image)
        ) as box:
            print(f"box started: {box.id}")

            # a non-zero exit code does not raise; check exit_code yourself
            result = await box.exec("sh", "-c", "echo $APP_ENV @ $(pwd) as $(id -u)")
            if result.exit_code != 0:
                print(f"command failed ({result.exit_code}): {result.stderr.strip()}")
            else:
                print(result.stdout.strip())  # production @ /tmp as 1000
    except Exception as e:
        # image pull failure / no virtualization raises a standard exception (e.g. RuntimeError)
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

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

async function main() {
  try {
    // in Node, construction-time env is Record<string, string> (different from Python's construction-time list)
    // workingDir must be a directory that already exists in the image, otherwise exec throws. alpine ships with /tmp.
    await using box = new SimpleBox({
      image: "alpine:latest",
      env: { APP_ENV: "production", LANG: "C.UTF-8" },
      user: "1000:1000",
      workingDir: "/tmp",
    });

    const result = await box.exec("sh", ["-c", "echo $APP_ENV @ $(pwd) as $(id -u)"]);
    if (result.exitCode !== 0) {
      console.error(`command failed (${result.exitCode}): ${result.stderr.trim()}`);
    } else {
      console.log(result.stdout.trim()); // production @ /tmp as 1000
    }
  } catch (e) {
    console.error(`error: ${(e as Error).message}`);
  }
}

main();

import asyncio

import boxlite

async def main():
    try:
        async with boxlite.SimpleBox(
            image="python:alpine",
            entrypoint=["python3"],
            # init must be long-running, otherwise the container goes Stopped and exec is no longer possible
            cmd=["-c", "import time; print('init running'); time.sleep(120)"],
            cpus=1,
            memory_mib=512,
        ) as box:
            print(f"box started: {box.id}")
            await asyncio.sleep(2)  # wait for init to come up
            # while init is long-running, other commands can be exec'd, exit=0
            result = await box.exec("python3", "-c", "print('hello from exec')")
            print(f"exec: {result.stdout.strip()} (exit={result.exit_code})")  # exit=0
    except Exception as e:
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

import boxlite

async def main():
    try:
        # in alpine, nobody is uid=65534, gid=65534
        async with boxlite.SimpleBox(image="alpine:latest", user="nobody:nobody") as box:
            result = await box.exec("id")
            print(result.stdout.strip())  # uid=65534(nobody) gid=65534(nobody) ...
    except Exception as e:
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

import boxlite

async def main():
    try:
        async with boxlite.SimpleBox(image="alpine:latest") as box:
            # per-execution override (exec's env is a dict, timeout is in seconds, float)
            result = await box.exec(
                "sh", "-c", "echo $GREETING",
                env={"GREETING": "hi"},   # exec takes a dict
                user="nobody",
                cwd="/tmp",
                timeout=10.0,
            )
            print(result.stdout.strip())  # hi

# The two env parameters take different shapes — this catches people out:
#   Box constructor : env=[("KEY", "value")]   list of tuples
#   exec(...)       : env={"KEY": "value"}     dict
# Passing a dict to the constructor raises:
#   TypeError: argument 'env': 'dict' object cannot be cast as 'Sequence'
    except Exception as e:
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

import boxlite

async def main():
    try:
        # correct: construction-time env is list[tuple[str, str]]
        async with boxlite.SimpleBox(
            image="alpine:latest",
            env=[("KEY", "value")],
        ) as box:
            result = await box.exec("sh", "-c", "echo $KEY")
            print(result.stdout.strip())  # value
    except Exception as e:
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

RuntimeError: internal error: spawn_failed: Container init process exited — cannot exec. ... incompatible container status: `Stopped`

RuntimeError: internal error: spawn_failed: ... error in executing process : failed to unix syscall

import asyncio

import boxlite

async def main():
    try:
        async with boxlite.SimpleBox(image="alpine:latest") as box:
            # create the directory first, then run inside it
            mk = await box.exec("mkdir", "-p", "/work")
            if mk.exit_code != 0:
                print(f"mkdir failed: {mk.stderr.strip()}")
                return
            result = await box.exec("pwd", cwd="/work")
            print(result.stdout.strip())  # /work
    except Exception as e:
        print(f"error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())