host.python
host.python runs Python on behalf of the app, streaming output back as it lands. Use it for compute the browser cannot do directly: data wrangling, plotting, anything that wants the Python ecosystem.
This is a risk-tier-gated capability. The app must declare it (the python permission tag in the manifest), and the user grants it. Calls reject with permission when the gate is not satisfied.
API
interface PythonNamespace {
eval(code: string, opts?: { onStream?: (delta: unknown) => void; timeout?: number }): Promise<unknown>;
interrupt(): Promise<void>;
}| Method | What it does |
|---|---|
eval(code, opts?) | Run a Python snippet; resolves with the result. onStream receives output deltas; timeout is in milliseconds. |
interrupt() | Send KeyboardInterrupt to the running cell. |
Run with streaming
await host.ready();
const result = await host.python.eval(
`
import statistics
data = [4, 8, 15, 16, 23, 42]
print("mean", statistics.mean(data))
statistics.pstdev(data)
`,
{
timeout: 30_000,
onStream: (delta) => appendOutput(delta), // stdout / stderr / display deltas as they arrive
},
);
console.log('final value:', result);Subscribe via onStream before long-running work so you see progress (stdout, stderr, and display output) as it streams, rather than only at the end.
Interrupt
await host.python.interrupt(); // KeyboardInterrupt to the in-flight cellNotes
- Gated by the app's risk tier; the user must grant the
pythoncapability. Without the grant,evalrejects withpermission. - In detached mode (
host.detached === true) there is no host bridge, soevalrejects withunknown_op. - For an interactive REPL surface with cell history, the native
pythonapp exposes a richer command set; see the agent command interface.host.pythonis the programmatic SDK entry point.
Related
- host.shell: run shell commands with streaming output
- Security model: how risk-tier capabilities are gated
- Error codes:
permission,timeout,unknown_op