Process Execution

Every Kernel browser runs inside its own VM with a full Linux environment alongside Chromium. Process execution lets you run arbitrary commands in that VM — install a tool, inspect files, run a script, or drive a co-located agent — without leaving the session.

Run a command synchronously

process.exec runs a command and blocks until it exits or times out. stdout_b64 and stderr_b64 are base64-encoded, and exit_code tells you whether it succeeded.

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const browser = await kernel.browsers.create({});

const result = await kernel.browsers.process.exec(browser.session_id, {
  command: 'ls',
  args: ['-la', '/tmp'],
});

console.log(Buffer.from(result.stdout_b64 ?? '', 'base64').toString());
console.log('exit code', result.exit_code);

import base64

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create()

result = kernel.browsers.process.exec(
    browser.session_id,
    command="ls",
    args=["-la", "/tmp"],
)

print(base64.b64decode(result.stdout_b64 or "").decode())
print("exit code", result.exit_code)

Use cwd to set a working directory, env to pass environment variables, as_user/as_root to control privileges, and timeout_sec to cap execution time.

Run a command in the background

process.spawn starts a command without waiting for it to finish, returning a process_id you use to manage it afterward. This is the right call for long-running processes — a server, a watcher script, an interactive shell.

If your long-running process is a server, pick a port yourself and don’t assume it’s free — the VM’s own infrastructure (live view, CDP, the playwright daemon) already listens on several, including 8080, 9222–9225, 8888, 10001, and 10002.

const spawned = await kernel.browsers.process.spawn(browser.session_id, {
  command: 'sh',
  args: ['-c', 'while true; do echo "tick $(date +%s)"; sleep 5; done'],
});

console.log('process_id', spawned.process_id);

spawned = kernel.browsers.process.spawn(
    browser.session_id,
    command="sh",
    args=["-c", 'while true; do echo "tick $(date +%s)"; sleep 5; done'],
)

print("process_id", spawned.process_id)

Pass allocate_tty: true to attach a pseudo-terminal for interactive shells, with cols/rows to set its initial size.

Manage a running process

Check status

Poll for whether a spawned process is still running, and its resource usage:

const status = await kernel.browsers.process.status(spawned.process_id, {
  id_or_name: browser.session_id,
});

console.log(status.state, status.exit_code);

status = kernel.browsers.process.status(
    spawned.process_id,
    id_or_name=browser.session_id,
)

print(status.state, status.exit_code)

Stream stdout and stderr

Read output from a spawned process as it happens over server-sent events:

const stream = await kernel.browsers.process.stdoutStream(spawned.process_id, {
  id_or_name: browser.session_id,
});

for await (const chunk of stream) {
  if (chunk.event === 'exit') {
    console.log('exited with', chunk.exit_code);
    break;
  }
  console.log(chunk.stream, Buffer.from(chunk.data_b64 ?? '', 'base64').toString());
}

import base64

with kernel.browsers.process.stdout_stream(
    spawned.process_id, id_or_name=browser.session_id
) as stream:
    for chunk in stream:
        if chunk.event == "exit":
            print("exited with", chunk.exit_code)
            break
        print(chunk.stream, base64.b64decode(chunk.data_b64 or "").decode())

Write to stdin

Send base64-encoded input to a running process, e.g. to answer an interactive prompt:

await kernel.browsers.process.stdin(spawned.process_id, {
  id_or_name: browser.session_id,
  data_b64: Buffer.from('y\n').toString('base64'),
});

import base64

kernel.browsers.process.stdin(
    spawned.process_id,
    id_or_name=browser.session_id,
    data_b64=base64.b64encode(b"y\n").decode(),
)

Resize a PTY

Resizing only works on a process spawned with allocate_tty: true — calling it on a plain process returns a 400. Match the terminal to a live view or client window:

const shell = await kernel.browsers.process.spawn(browser.session_id, {
  command: 'sh',
  allocate_tty: true,
  cols: 80,
  rows: 24,
});

await kernel.browsers.process.resize(shell.process_id, {
  id_or_name: browser.session_id,
  cols: 120,
  rows: 40,
});

shell = kernel.browsers.process.spawn(
    browser.session_id,
    command="sh",
    allocate_tty=True,
    cols=80,
    rows=24,
)

kernel.browsers.process.resize(
    shell.process_id,
    id_or_name=browser.session_id,
    cols=120,
    rows=40,
)

Kill a process

await kernel.browsers.process.kill(spawned.process_id, {
  id_or_name: browser.session_id,
  signal: 'TERM',
});

kernel.browsers.process.kill(
    spawned.process_id,
    id_or_name=browser.session_id,
    signal="TERM",
)

signal accepts TERM, KILL, INT, or HUP.

Root and per-user execution

Pass as_root: true or as_user: "<name>" on exec or spawn to control which user the command runs as. This is safe because a Kernel browser is a unikernel VM with no shared host kernel — root inside your session has no path to other customers or platform infrastructure.

Via CLI

The CLI exposes the same operations:

# Synchronous
kernel browsers process exec <session-id> --command ls --args -la

# Background, then inspect
kernel browsers process spawn <session-id> --command python3 --args -m --args http.server
kernel browsers process status <session-id> <process-id>
kernel browsers process kill <session-id> <process-id>

Example: co-locating an agent with its browser

Driving a browser from outside the VM means every tool call is a round trip through Kernel’s API. Process execution lets you flip that around: upload an agent binary into the VM with File I/O, then run it alongside Chromium so it talks to the VM’s local Playwright endpoint over loopback instead. See the fx co-located agent cookbook for a full working example.

File I/O

Upload and download files from a browser VM

SSH Access

Open an interactive SSH session for debugging

CLI reference

All kernel browsers process subcommands and flags

Overview

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

Process Execution

Run a command synchronously

Run a command in the background

Manage a running process

Check status

Stream stdout and stderr

Write to stdin

Resize a PTY

Kill a process

Root and per-user execution

Via CLI

Example: co-locating an agent with its browser

File I/O

SSH Access

CLI reference

​Run a command synchronously

​Run a command in the background

​Manage a running process

​Check status

​Stream stdout and stderr

​Write to stdin

​Resize a PTY

​Kill a process

​Root and per-user execution

​Via CLI

​Example: co-locating an agent with its browser

​Related

File I/O

SSH Access

CLI reference

Run a command synchronously

Run a command in the background

Manage a running process

Check status

Stream stdout and stderr

Write to stdin

Resize a PTY

Kill a process

Root and per-user execution

Via CLI

Example: co-locating an agent with its browser

Related