host.shell

host.shell runs a shell command on behalf of the app and streams its output back. Use it for build steps, file operations, or driving CLI tools from an app surface.

This is a risk-tier-gated capability. The app must declare it (the shell permission tag in the manifest), and the user grants it. Calls reject with permission when the gate is not satisfied.

API

interface ShellNamespace {
  run(command: string, opts?: { onStream?: (delta: unknown) => void; timeout?: number; stdin?: string }): Promise<unknown>;
  interrupt(): Promise<void>;
}

Method	What it does
`run(command, opts?)`	Run a command; resolves when it exits. `onStream` receives output deltas; `timeout` is in milliseconds; `stdin` feeds input.
`interrupt()`	Send `SIGINT` (^C) to the running command.

Run with streaming

await host.ready();

const result = await host.shell.run('ls -la && du -sh .', {
  timeout: 20_000,
  onStream: (delta) => appendOutput(delta), // live stdout/stderr deltas
});

Subscribe via onStream before invoking so you see live output as the command runs. For a command that reads stdin, pass it up front:

await host.shell.run('cat | sort', { stdin: 'banana\napple\ncherry\n' });

Interrupt

await host.shell.interrupt(); // SIGINT to the in-flight command

Notes

Gated by the app's risk tier; the user must grant the shell capability. Without the grant, run rejects with permission.

In detached mode (host.detached === true) there is no host bridge, so run rejects with unknown_op.

The native shell apps (daemon, ssh) expose a richer PTY command surface (scrollback, grep, raw stdin) to agents; see the agent command interface. host.shell is the programmatic SDK entry point.

host.python: run Python with streaming output

Security model: how risk-tier capabilities are gated

Error codes: permission, timeout, unknown_op

host.shell

API

Run with streaming

Interrupt

Notes

Related

On this page