Install okyra

Download

Each tarball holds the okyra binary, LICENSE.md, a README.md, the agent skill SKILL.md and THIRD-PARTY-NOTICES. Unpack it and put the binary on your PATH:

tar xzf okyra-0.1.0-aarch64-apple-darwin.tar.gz
sudo mv okyra-0.1.0-aarch64-apple-darwin/okyra /usr/local/bin/
okyra --version            # okyra 0.1.0

The Linux tarballs are named okyra-0.1.0-x86_64-unknown-linux-musl.tar.gz and okyra-0.1.0-aarch64-unknown-linux-musl.tar.gz. They are static (musl), so they run on any Linux of that architecture with no glibc requirement.

The macOS build is not yet signed or notarized. If macOS refuses to open it after a browser download, remove the download flag with xattr -d com.apple.quarantine /usr/local/bin/okyra.

Homebrew

Coming soon. The tap opens once the macOS build is signed and notarized. Until then, brew install sthlabs/tap/okyra does not work; use a tarball.

Which browser okyra uses

okyra starts its own browser with a throwaway profile, never yours. OKYRA_CHROME wins when set. Otherwise it takes the first of these that exists:

export OKYRA_CHROME="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
okyra version              # starts the browser, prints its name and protocol version

On Debian or Ubuntu, apt-get install chromium is enough. The browser runs headless at 1280 by 900. Set OKYRA_HEADFUL=1 to see the window.

Browser settings are read once, when the daemon starts the browser. After changing OKYRA_CHROME, OKYRA_HEADFUL or OKYRA_NO_SANDBOX, run okyra stop so the next call starts fresh.

Linux containers

Inside Docker, Chromium usually cannot start its sandbox: the container blocks the namespaces it needs, and Chromium refuses to run as root with it on. okyra then fails with a message that names the fix. If the container is your isolation boundary, turn the browser sandbox off:

export OKYRA_NO_SANDBOX=1
okyra version

Keep the sandbox on outside containers, especially when your agent opens pages you do not trust. On Linux okyra also passes --disable-dev-shm-usage, since Docker gives /dev/shm only 64 MB.

A cold browser start on a fresh CI runner can take over 20 seconds. okyra waits up to 60 seconds for it.

The daemon and its socket

The first command starts okyra daemon in the background. It keeps the browser and named pages open between calls and exits after 30 idle minutes. okyra stop ends it at once. okyra status and okyra ping answer without starting the browser.

The socket is mode 0600, so only your user can talk to the daemon. Its log sits next to it with a .log extension, for example $TMPDIR/okyra.log. A socket path must stay under about 100 characters, the Unix limit.

okyra status
{
  "browser_started": false,
  "connect": null,
  "pid": 30205,
  "uptime_ms": 13
}

Attach to your own browser

okyra can drive the browser you already run, signed in as you, instead of starting one. Turn on remote debugging at chrome://inspect/#remote-debugging (brave://inspect in Brave), then:

export OKYRA_CONNECT=brave   # or chrome, edge, chromium, a user data folder, or a ws:// URL
okyra goto https://example.com

The browser may ask you to allow the connection; okyra waits up to 2 minutes for that click. okyra opens its own tabs behind yours and never touches yours. okyra stop leaves the browser and those tabs open. An attached daemon stays up for a day when idle, since each new attach asks you to allow it again.