Run an interactive terminal

InteractiveBox attaches your terminal directly to a shell running inside a VM — like SSH into a sandbox. Use it for interactive tools, REPLs, debugging sessions, or any workflow where you need a live terminal.

What you’ll build

A script that:

Launches an InteractiveBox with a shell
Runs interactive commands in a TTY session
Connects to a Python REPL inside the VM

Prerequisites

Python
Node.js

pip install boxlite

Requires Python 3.10+.

npm install @boxlite-ai/boxlite

Requires Node.js 18+.

Step 1: Start a shell session

Launch an InteractiveBox and drop into a shell. The session stays open until you type exit or the shell terminates.

Python
Node.js

shell.py

import asyncio
from boxlite import InteractiveBox


async def main():
    async with InteractiveBox(image="alpine:latest") as box:
        # You're now in an interactive shell inside the VM
        # Type commands, see output in real-time
        # Type "exit" to close the session
        await box.wait()

    print("Shell session ended")


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

python shell.py
# You'll see an Alpine Linux shell prompt
# Try: ls, whoami, cat /etc/os-release
# Type "exit" to quit

shell.js

import { InteractiveBox } from '@boxlite-ai/boxlite';

async function main() {
  const box = new InteractiveBox({ image: 'alpine:latest' });
  try {
    await box.start();
    // You're now in an interactive shell inside the VM
    // Type commands, see output in real-time
    // Type "exit" to close the session
    await box.wait();
  } finally {
    await box.stop();
  }

  console.log('Shell session ended');
}

main();

node shell.js
# You'll see an Alpine Linux shell prompt
# Try: ls, whoami, cat /etc/os-release
# Type "exit" to quit

What’s happening:

InteractiveBox creates a VM with Alpine Linux and attaches your terminal to /bin/sh
Your keystrokes go directly into the VM’s shell, and output streams back in real-time
wait() blocks until the shell process exits (when you type exit or press Ctrl+D)

Step 2: Choose your shell

You can run any shell or REPL available in the image. Specify it with the shell parameter.

Python
Node.js

bash_session.py

import asyncio
from boxlite import InteractiveBox


async def main():
    # Use bash (available in Ubuntu, not Alpine)
    async with InteractiveBox(
        image="ubuntu:22.04",
        shell="/bin/bash"
    ) as box:
        await box.wait()


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

python_repl.py

import asyncio
from boxlite import InteractiveBox


async def main():
    # Drop straight into a Python REPL
    async with InteractiveBox(
        image="python:slim",
        shell="/usr/bin/python3"
    ) as box:
        await box.wait()


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

bash_session.js

import { InteractiveBox } from '@boxlite-ai/boxlite';

async function main() {
  // Use bash (available in Ubuntu, not Alpine)
  const box = new InteractiveBox({
    image: 'ubuntu:22.04',
    shell: '/bin/bash',
  });
  try {
    await box.start();
    await box.wait();
  } finally {
    await box.stop();
  }
}

main();

python_repl.js

import { InteractiveBox } from '@boxlite-ai/boxlite';

async function main() {
  // Drop straight into a Python REPL
  const box = new InteractiveBox({
    image: 'python:slim',
    shell: '/usr/bin/python3',
  });
  try {
    await box.start();
    await box.wait();
  } finally {
    await box.stop();
  }
}

main();

Make sure the shell you specify actually exists in the image. Alpine uses /bin/sh (busybox), not /bin/bash. Ubuntu has both.

Step 3: Choose the right TTY mode

The tty parameter controls how InteractiveBox handles terminal I/O. The right choice depends on how you’re using the box.

Value	Python	Node.js	Behavior	Use when…
Auto-detect	`tty=None` (default)	`tty: undefined` (default)	Checks `sys.stdin.isatty()` / `process.stdin.isTTY`	You’re not sure — this works in most cases
Force TTY	`tty=True`	`tty: true`	Always enables PTY with I/O forwarding	You’re running from a terminal and want interactive control
No I/O	`tty=False`	`tty: false`	Disables I/O forwarding entirely	You’re controlling the box programmatically with `exec()`

Python
Node.js

tty_modes.py

import asyncio
from boxlite import InteractiveBox


async def main():
    # Force TTY mode — always interactive
    async with InteractiveBox(
        image="alpine:latest",
        tty=True
    ) as box:
        await box.wait()


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

programmatic.py

import asyncio
from boxlite import InteractiveBox


async def main():
    # No I/O forwarding — use exec() to send commands
    async with InteractiveBox(
        image="alpine:latest",
        tty=False
    ) as box:
        # InteractiveBox extends SimpleBox, so exec() works
        result = await box.exec("cat", "/etc/os-release")
        print(result.stdout)


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

tty_modes.js

import { InteractiveBox } from '@boxlite-ai/boxlite';

async function main() {
  // Force TTY mode — always interactive
  const box = new InteractiveBox({
    image: 'alpine:latest',
    tty: true,
  });
  try {
    await box.start();
    await box.wait();
  } finally {
    await box.stop();
  }
}

main();

programmatic.js

import { InteractiveBox } from '@boxlite-ai/boxlite';

async function main() {
  // No I/O forwarding — use exec() to send commands
  const box = new InteractiveBox({
    image: 'alpine:latest',
    tty: false,
  });
  try {
    await box.start();
    // InteractiveBox extends SimpleBox, so exec() works
    const result = await box.exec('cat', '/etc/os-release');
    console.log(result.stdout);
  } finally {
    await box.stop();
  }
}

main();

InteractiveBox extends SimpleBox, so you always have access to exec() for running one-off commands. The tty parameter only controls whether the shell session itself gets I/O forwarding — exec() works regardless.

What’s next?

Run any language or tool

Use SimpleBox with custom images to run Node.js, Go, Rust, or any CLI tool.

Handle errors and debug

Catch exceptions, handle timeouts, and debug failures.

InteractiveBox API reference

Full API docs for InteractiveBox constructor options and methods.

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

What you’ll build

Prerequisites

Step 1: Start a shell session

Step 2: Choose your shell

Step 3: Choose the right TTY mode

What’s next?

Run any language or tool

Handle errors and debug

InteractiveBox API reference

​What you’ll build

​Prerequisites

​Step 1: Start a shell session

​Step 2: Choose your shell

​Step 3: Choose the right TTY mode

​What’s next?

Run any language or tool

Handle errors and debug

InteractiveBox API reference

What you’ll build

Prerequisites

Step 1: Start a shell session

Step 2: Choose your shell

Step 3: Choose the right TTY mode

What’s next?