Browser kernels

List, install, and remove browser kernels from the local API, including the unattended flow for a headless machine that prepares itself.

What a kernel is

Every profile pins one browser engine version, and the matching kernel is what actually runs the session. Kernels are not bundled with the app, which is what keeps the installer small, so a freshly installed machine has none of them yet. Launching a profile whose kernel is missing returns 409 with code: "kernel_missing", and the body carries the bundle_key to install.

The kernel files are private. Each download uses a short lived signed link issued to your account, so the machine has to be signed in before it can install one. That is the only prerequisite, and it is the same whether you use the app or drive the API yourself.

The download URLs inside the app's bundled manifest point at a placeholder host that is never contacted. They are not where your machine downloads from, so a failed install is never a DNS problem with that host.

List engines

GET /api/engines returns every engine this build understands, reconciled against what is on disk and what is hosted for your operating system.

Field	Meaning
id	Engine version, for example `engine-v152`. Accepted by the install route.
bundle_key	Bundle id, for example `chrome_152`. Also accepted by the install route, and the form the 409 hands you.
label	Display name, for example `Chromium 152`.
installed	Whether the kernel is on this machine right now.
downloadable	Whether a build exists for this operating system. This is the field that decides whether an install can succeed here.
size_bytes	Installed size on disk, or the download size when it is not installed.
available	Legacy alias for `installed`. It repeats that value and says nothing about whether the kernel can be downloaded.

Not every version is built for every operating system. Check downloadable rather than assuming a version in the list can be installed on the machine you are on.

Install a kernel

POST /api/engines/{id}/install starts a background download. Either identifier works, chrome_152 or engine-v152. It returns a progress object straight away; poll GET /api/engines/installs/{token} until phase reads done. The phases run pending, downloading, verifying, unpacking, installing, done, with error and cancelled as the other endings.

# start the install
curl -X POST http://127.0.0.1:8765/api/engines/chrome_152/install \
  -H "Authorization: Bearer $OCULR_TOKEN"
 
# {"token": "6f1c...", "bundle_key": "chrome_152", "phase": "pending", ... }
 
# then poll until phase is done
curl http://127.0.0.1:8765/api/engines/installs/6f1c... \
  -H "Authorization: Bearer $OCULR_TOKEN"

A machine that prepares itself

A headless box can do the whole thing over the API, with no one at the keyboard. Sign in once, install the kernel your profiles pin, then launch. The sign in is saved per user account and per data directory, so run these as the same user and with the same OCULR_DATA_DIR that the agent itself runs under, or the agent will read a different file and the install will be refused.

# 1. sign in (saves the session next to the agent's data dir)
curl -X POST http://127.0.0.1:8765/api/auth/cloud/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'
 
# 2. install the kernel your profiles pin
curl -X POST http://127.0.0.1:8765/api/engines/chrome_152/install \
  -H "Authorization: Bearer $OCULR_TOKEN"
 
# 3. poll, then launch as normal

If the account has the emailed sign in code switched on, the login answers with a challenge_id instead of a session. Either turn the code off in Settings for an unattended machine, or post the code to /api/auth/cloud/code/verify with that challenge_id.

When an install will not start

A refused install returns 409 with a structured body: a code to branch on, a message to show, and transient, which tells you whether retrying can help. Only service_unavailable is worth a retry.

code	transient	What to do
session_expired	false	This machine's sign in was rejected. Sign in again on this machine, then retry.
not_hosted	false	No build of that kernel exists for this operating system. Pick one whose `downloadable` is true.
rate_limited	false	Too many download links requested from this network. Wait a few minutes.
service_unavailable	true	The kernel service is waking up or unreachable. Wait a few seconds and try again, and check the machine can reach the service.
rejected	false	The request was refused for another reason. The message carries the status.

Download links are capped at 20 per 5 minutes per IP address. A tight retry loop keeps that cap closed, and the failure it produces looks the same as the one you were retrying, so retry slowly and only on transient: true.

Remove a kernel

DELETE /api/engines/{id} removes the kernel from disk and accepts the same two identifiers. It returns 409 if an install for that kernel is still in flight, so cancel it first.

Try Oculr Quickstart