Use interactive terminals - Namespace Documentation

Use terminal.open() for programs that require a pseudo-terminal or interactive input. Read terminal output, write input, resize the terminal, and wait for it to exit.

Opening a terminal starts a stopped Devbox automatically. Unlike Namespace Sessions, an SDK terminal is tied to its connection and does not persist for later reattachment.

`terminal.open()`

Open an interactive shell in the Devbox and control it through a TerminalSession.

Example

Open a terminal, print its output, run a command, and wait for it to exit:

const devbox = await client.devboxes.get("sdk-example");
const terminal = await devbox.terminal.open({
  columns: 120,
  rows: 40,
});
terminal.onData((data) => process.stdout.write(data));
terminal.write("pwd\n");
terminal.write("exit\n");
const { exitCode, signal } = await terminal.wait();

API reference

terminal.open(options?: TerminalOpenOptions): Promise<TerminalSession>

Arguments and options

TerminalOpenOptions

Options used to open the terminal.

Hide properties

number

default:"80"

The initial terminal width in columns.

number

default:"24"

The initial terminal height in rows.

string

default:"xterm-256color"

The terminal type reported to the remote shell.

Record<string, string>

Environment variables requested for the terminal session.

AbortSignal

Cancels terminal setup. If aborted after the terminal opens, the SDK closes the terminal.

number

The timeout budget for activation, connection, and terminal setup. It does not limit the lifetime of an open terminal.

Return value

terminal.open() resolves with a TerminalSession.

interface TerminalSession {
  write(data: string | Uint8Array): void;
  resize(columns: number, rows: number): void;
  close(): void;
  onData(listener: (data: Uint8Array) => void): () => void;
  onExit(listener: (exitCode: number | null, signal: string | null) => void): () => void;
  onError(listener: (error: Error) => void): () => void;
  wait(): Promise<{ exitCode: number | null; signal: string | null }>;
}

The methods on TerminalSession are documented below.

More examples

Forward local input

Forward local terminal input to a remote shell and keep it open until the user types exit.

const devbox = await client.devboxes.get("my-devbox");
const terminal = await devbox.terminal.open();

const forwardInput = (data: Buffer) => terminal.write(data);
const unsubscribe = terminal.onData((data) => process.stdout.write(data));

try {
  process.stdin.setRawMode(true);
  process.stdin.resume();
  process.stdin.on("data", forwardInput);

  // Wait until the remote shell ends, such as after the user types "exit".
  const result = await terminal.wait();

  process.exitCode = result.exitCode ?? 1;
} finally {
  process.stdin.off("data", forwardInput);
  process.stdin.pause();
  process.stdin.setRawMode(false);
  unsubscribe();
  terminal.close();
}

`terminal.write()`

Send text or bytes to the terminal’s standard input. Strings are written as provided, so include \n when submitting a command.

Example

terminal.write("npm test\n");

API reference

write(data: string | Uint8Array): void

Arguments and options

string | Uint8Array

required

Text or bytes to send to the terminal.

write() throws an Error if the terminal is already closed.

`terminal.resize()`

Change the dimensions of the remote pseudo-terminal.

Example

terminal.resize(160, 50);

API reference

resize(columns: number, rows: number): void

Arguments and options

number

required

The new terminal width in columns.

number

required

The new terminal height in rows.

resize() throws an Error if the terminal is already closed.

`terminal.close()`

Close the terminal locally. Calling close() more than once has no effect.

Example

terminal.close();

API reference

close(): void

Arguments and options

This method has no arguments or options. Closing the terminal causes pending wait() calls to resolve when the underlying channel closes. A locally closed terminal reports a null exit code and signal.

`terminal.onData()`

Subscribe to terminal output. Standard output and standard error are delivered through the same listener.

Example

terminal.onData((data) => process.stdout.write(data));

API reference

onData(listener: (data: Uint8Array) => void): () => void

Arguments and options

(data: Uint8Array) => void

required

Called with each output chunk.

Return value

Returns a function that removes the listener.

More examples

Stop listening for output

const unsubscribe = terminal.onData((data) => process.stdout.write(data));
// Use the terminal while the listener receives output.

// Unsubscribe when done.
unsubscribe();

`terminal.onExit()`

Subscribe to the terminal’s exit event.

Example

const unsubscribe = terminal.onExit((code, signal) => {
  console.log({
    code,
    signal,
  });
});

API reference

onExit(listener: (exitCode: number | null, signal: string | null) => void): () => void

Arguments and options

(exitCode: number | null, signal: string | null) => void

required

Called when the terminal closes. Either value may be null when the remote side does not report it.

Return value

Returns a function that removes the listener.

`terminal.onError()`

Subscribe to terminal transport errors.

Example

const unsubscribe = terminal.onError((error) => console.error(error));

API reference

onError(listener: (error: Error) => void): () => void

Arguments and options

(error: Error) => void

required

Called when the terminal transport reports an error.

Return value

Returns a function that removes the listener.

`terminal.wait()`

Wait for the terminal to close. Calling wait() after exit resolves immediately with the recorded result.

Example

const { exitCode, signal } = await terminal.wait();

API reference

wait(): Promise<{ exitCode: number | null; signal: string | null }>

Arguments and options

This method has no arguments or options.

Return value

number | null

required

The remote shell’s exit code, or null when no exit code is available.

string | null

required

The signal that ended the remote shell, or null when no signal is available.

Run commands

Run structured commands and shell scripts without an interactive terminal.

Handle errors and timeouts

Cancel operations and handle SDK failures.

​terminal.open()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Forward local input

​terminal.write()

​Example

​API reference

​Arguments and options

​terminal.resize()

​Example

​API reference

​Arguments and options

​terminal.close()

​Example

​API reference

​Arguments and options

​terminal.onData()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Stop listening for output

​terminal.onExit()

​Example

​API reference

​Arguments and options

​Return value

​terminal.onError()

​Example

​API reference

​Arguments and options

​Return value

​terminal.wait()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Run commands

Handle errors and timeouts

`terminal.open()`

Example

API reference

Arguments and options

Return value

More examples

Forward local input

`terminal.write()`

Example

API reference

Arguments and options

`terminal.resize()`

Example

API reference

Arguments and options

`terminal.close()`

Example

API reference

Arguments and options

`terminal.onData()`

Example

API reference

Arguments and options

Return value

More examples

Stop listening for output

`terminal.onExit()`

Example

API reference

Arguments and options

Return value

`terminal.onError()`

Example

API reference

Arguments and options

Return value

`terminal.wait()`

Example

API reference

Arguments and options

Return value

Related documentation