Interactive shell (PTY)

# interactive.py
# How to run: execute in a real terminal  python interactive.py
import asyncio
import os
import sys

from boxlite import InteractiveBox

async def main() -> None:
    print("Starting interactive Alpine container...")
    print("Type 'exit' or press Ctrl-D to quit\n")

    # Pass the local TERM into the box for correct color/cursor behavior
    term_mode = os.environ.get("TERM", "xterm-256color")

    try:
        # InteractiveBox is an async context manager:
        # entering async with automatically creates+starts the box and launches a PTY-backed shell.
        async with InteractiveBox(
            image="alpine:latest",
            shell="/bin/sh",            # optional, defaults to /bin/sh
            env=[("TERM", term_mode)],  # env is list[tuple[str, str]]
        ) as itbox:
            # You are now inside the interactive shell.
            # I/O is forwarded bidirectionally by a background task; wait() blocks until the shell exits.
            await itbox.wait()
    except KeyboardInterrupt:
        print("\nInterrupted by Ctrl-C")
    except Exception as exc:  # startup failure / no virtualization / image pull failure, etc.
        print(f"\nError: {exc}", file=sys.stderr)
        sys.exit(1)

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

// interactive.mjs
// How to run: execute in a real terminal  node interactive.mjs
import { InteractiveBox } from "@boxlite-ai/boxlite";

async function main() {
  console.log("Starting interactive shell... (type 'exit' to quit)\n");

  const box = new InteractiveBox({
    image: "alpine:latest",
    shell: "/bin/sh", // optional, defaults to /bin/sh
    tty: true, // force I/O forwarding on; if omitted, auto-detected from whether stdin is a TTY
  });

  try {
    await box.start(); // launch the PTY-backed shell and begin forwarding
    await box.wait(); // block until the shell exits
    console.log("\nShell exited.");
  } catch (err) {
    console.error("Error:", err);
    process.exitCode = 1;
  } finally {
    await box.stop(); // restore terminal mode and destroy the box
  }
}

main();

# Correct
env=[("TERM", "xterm-256color"), ("LANG", "C.UTF-8")]
# Wrong: passing a dict raises
#   TypeError: argument 'env': 'dict' object cannot be cast as 'Sequence'
# env={"TERM": "xterm-256color"}

internal error: spawn_failed: internal error: build failed: failed to create container: exec process failed with error ...