Kernel Browser Processes API
Execute and manage processes on the browser instance.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kernel API Keys Browser Processes API
description: Developer tools and cloud infrastructure for AI agents to use web browsers
version: 0.1.0
servers:
- url: https://api.onkernel.com
description: API Server
security:
- bearerAuth: []
tags:
- name: Browser Processes
description: Execute and manage processes on the browser instance.
paths:
/browsers/{id}/process/exec:
post:
summary: Execute a command synchronously
operationId: processExec
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessExecRequest'
responses:
'200':
description: Execution result
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessExecResult'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.exec('id', { command: 'command' });\n\nconsole.log(response.duration_ms);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.exec(\n id=\"id\",\n command=\"command\",\n)\nprint(response.duration_ms)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Exec(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserProcessExecParams{\n\t\t\tCommand: \"command\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.DurationMs)\n}\n"
/browsers/{id}/process/spawn:
post:
summary: Execute a command asynchronously
operationId: processSpawn
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessSpawnRequest'
responses:
'200':
description: Spawned
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessSpawnResult'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.spawn('id', { command: 'command' });\n\nconsole.log(response.pid);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.spawn(\n id=\"id\",\n command=\"command\",\n)\nprint(response.pid)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Spawn(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserProcessSpawnParams{\n\t\t\tCommand: \"command\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Pid)\n}\n"
/browsers/{id}/process/{process_id}/status:
get:
summary: Get process status
operationId: processStatus
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: process_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Status
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessStatus'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.status('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n id: 'id',\n});\n\nconsole.log(response.cpu_pct);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.status(\n process_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id=\"id\",\n)\nprint(response.cpu_pct)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Status(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\tkernel.BrowserProcessStatusParams{\n\t\t\tID: \"id\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.CPUPct)\n}\n"
/browsers/{id}/process/{process_id}/stdout/stream:
get:
summary: Stream process stdout via SSE
operationId: processStdoutStream
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: process_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: SSE stream of process output and lifecycle events
headers:
X-SSE-Content-Type:
description: Media type of SSE data events (application/json)
schema:
type: string
const: application/json
content:
text/event-stream:
schema:
$ref: '#/components/schemas/ProcessStreamEvent'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.stdoutStream(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n { id: 'id' },\n);\n\nconsole.log(response.data_b64);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nfor process in client.browsers.process.stdout_stream(\n process_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id=\"id\",\n):\n print(process)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tstream := client.Browsers.Process.StdoutStreamStreaming(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\tkernel.BrowserProcessStdoutStreamParams{\n\t\t\tID: \"id\",\n\t\t},\n\t)\n\tfor stream.Next() {\n\t\tfmt.Printf(\"%+v\\n\", stream.Current())\n\t}\n\terr := stream.Err()\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/browsers/{id}/process/{process_id}/stdin:
post:
summary: Write to process stdin
operationId: processStdin
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: process_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessStdinRequest'
responses:
'200':
description: Bytes written
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessStdinResult'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.stdin('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n id: 'id',\n data_b64: 'data_b64',\n});\n\nconsole.log(response.written_bytes);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.stdin(\n process_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id=\"id\",\n data_b64=\"data_b64\",\n)\nprint(response.written_bytes)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Stdin(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\tkernel.BrowserProcessStdinParams{\n\t\t\tID: \"id\",\n\t\t\tDataB64: \"data_b64\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.WrittenBytes)\n}\n"
/browsers/{id}/process/{process_id}/kill:
post:
summary: Send signal to process
operationId: processKill
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: process_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessKillRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OkResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.kill('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n id: 'id',\n signal: 'TERM',\n});\n\nconsole.log(response.ok);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.kill(\n process_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id=\"id\",\n signal=\"TERM\",\n)\nprint(response.ok)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Kill(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\tkernel.BrowserProcessKillParams{\n\t\t\tID: \"id\",\n\t\t\tSignal: kernel.BrowserProcessKillParamsSignalTerm,\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Ok)\n}\n"
/browsers/{id}/process/{process_id}/resize:
post:
summary: Resize a PTY-backed process terminal
operationId: processResize
tags:
- Browser Processes
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: process_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessResizeRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OkResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.process.resize('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n id: 'id',\n cols: 1,\n rows: 1,\n});\n\nconsole.log(response.ok);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.process.resize(\n process_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id=\"id\",\n cols=1,\n rows=1,\n)\nprint(response.ok)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Process.Resize(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\tkernel.BrowserProcessResizeParams{\n\t\t\tID: \"id\",\n\t\t\tCols: 1,\n\t\t\tRows: 1,\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Ok)\n}\n"
components:
schemas:
ProcessStatus:
type: object
description: Current status of a process.
properties:
state:
type: string
enum:
- running
- exited
description: Process state.
exit_code:
type: integer
nullable: true
description: Exit code if the process has exited.
cpu_pct:
type: number
description: Estimated CPU usage percentage.
mem_bytes:
type: integer
description: Estimated resident memory usage in bytes.
additionalProperties: false
ProcessKillRequest:
type: object
description: Signal to send to the process.
required:
- signal
properties:
signal:
type: string
enum:
- TERM
- KILL
- INT
- HUP
default: TERM
description: Signal to send.
additionalProperties: false
ErrorDetail:
type: object
properties:
code:
type: string
description: Lower-level error code providing more specific detail
example: invalid_input
message:
type: string
description: Further detail about the error
example: Provided version string is not semver compliant
ProcessSpawnRequest:
allOf:
- $ref: '#/components/schemas/ProcessExecRequest'
- type: object
properties:
allocate_tty:
type: boolean
description: Allocate a pseudo-terminal (PTY) for interactive shells.
default: false
rows:
type: integer
description: Initial terminal rows. Only used when allocate_tty is true.
minimum: 1
maximum: 65535
cols:
type: integer
description: Initial terminal columns. Only used when allocate_tty is true.
minimum: 1
maximum: 65535
ProcessResizeRequest:
type: object
description: Resize a PTY-backed process terminal.
required:
- rows
- cols
properties:
rows:
type: integer
minimum: 1
maximum: 65535
description: New terminal rows.
cols:
type: integer
minimum: 1
maximum: 65535
description: New terminal columns.
additionalProperties: false
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Application-specific error code (machine-readable)
example: bad_request
message:
type: string
description: Human-readable error description for debugging
example: 'Missing required field: app_name'
details:
type: array
description: Additional error details (for multiple errors)
items:
$ref: '#/components/schemas/ErrorDetail'
inner_error:
$ref: '#/components/schemas/ErrorDetail'
ProcessStreamEvent:
type: object
description: SSE payload representing process output or lifecycle events.
properties:
stream:
type: string
description: Source stream of the data chunk.
enum:
- stdout
- stderr
data_b64:
type: string
description: Base64-encoded data from the process stream.
event:
type: string
description: Lifecycle event type.
enum:
- exit
exit_code:
type: integer
description: Exit code when the event is "exit".
additionalProperties: false
OkResponse:
type: object
description: Generic OK response.
required:
- ok
properties:
ok:
type: boolean
description: Indicates success.
default: true
additionalProperties: false
ProcessExecResult:
type: object
description: Result of a synchronous command execution.
properties:
exit_code:
type: integer
description: Process exit code.
stdout_b64:
type: string
description: Base64-encoded stdout buffer.
stderr_b64:
type: string
description: Base64-encoded stderr buffer.
duration_ms:
type: integer
description: Execution duration in milliseconds.
additionalProperties: false
ProcessStdinResult:
type: object
description: Result of writing to stdin.
properties:
written_bytes:
type: integer
description: Number of bytes written.
additionalProperties: false
ProcessStdinRequest:
type: object
description: Data to write to the process standard input.
required:
- data_b64
properties:
data_b64:
type: string
description: Base64-encoded data to write.
additionalProperties: false
ProcessExecRequest:
type: object
description: Request to execute a command synchronously.
required:
- command
properties:
command:
type: string
description: Executable or shell command to run.
args:
type: array
description: Command arguments.
items:
type: string
default: []
cwd:
type: string
description: Working directory (absolute path) to run the command in.
nullable: true
pattern: ^/.*
env:
type: object
description: Environment variables to set for the process.
additionalProperties:
type: string
default: {}
as_user:
type: string
description: Run the process as this user.
nullable: true
as_root:
type: boolean
description: Run the process with root privileges.
default: false
timeout_sec:
type: integer
description: Maximum execution time in seconds.
nullable: true
additionalProperties: false
ProcessSpawnResult:
type: object
description: Information about a spawned process.
properties:
process_id:
type: string
format: uuid
description: Server-assigned identifier for the process.
pid:
type: integer
description: OS process ID.
started_at:
type: string
format: date-time
description: Timestamp when the process started.
additionalProperties: false
responses:
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad Request – invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer