Skip to content
uklokPublic

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

UKLOK Browser

One headful Google Chrome session that a human and an agent can share.

  • Human control: noVNC
  • Agent control: Chrome DevTools Protocol (CDP)
  • Durable identity: persistent Linux Chrome profile
  • Default deployment: Docker-network only
  • Local development: loopback-only host access
  • Current image platform: linux/amd64

Choose your path

I want to… Go here
Run it locally Quick start
Control it with an agent Browser Use — Phase A
Build deterministic browser automations Browser automations
Understand the moving parts Architecture
Keep logins across restarts Profiles & identity
Debug a black screen / unhealthy browser Operations
Understand the security boundaries Security
Publish or pin an image version Releases
Work on this repo as an agent AGENTS.md

Full documentation index: docs/README.md.

Fastest local start

cp .env.example .env

docker compose \
  -f compose.yaml \
  -f local.yaml \
  up --build -d

Then:

On Apple Silicon, Docker Desktop runs the current linux/amd64 image through emulation. The local overlay attempts sandboxed Chrome first and only falls back to --no-sandbox for the known namespace failure. Production does not enable that fallback.

Persistent browser identity

The easiest persistence path is the named Docker volume in compose.yaml.

For a host-visible profile owned by the Linux container:

mkdir -p "$HOME/.uklok-browser/chrome-profile"

docker compose \
  -f compose.yaml \
  -f local.yaml \
  -f bind-profile.yaml \
  up --build -d

Authenticate once inside this Linux Chrome session. Do not mount a macOS/Windows Chrome user-data directory into the container; authentication secrets are not cross-platform portable. See Profiles & identity.

Runtime contract

A healthy session means all of these are true:

  1. Xvfb is alive.
  2. Chrome is headful and running.
  3. CDP answers on :9222.
  4. noVNC serves the same display on :6080.
  5. The Chrome profile is writable and survives restart.

tests/smoke.sh encodes that contract.

Agent control with Browser Use

Once Chrome is healthy, add the pinned Browser Use capability layer:

./bin/browser-use-setup
./bin/browser-use-doctor

The adapter attaches Browser Use to this same Chrome over CDP; it does not create another browser runtime. See Browser Use — Phase A.

For repeated work, move learned behavior out of the agent happy path and into contract-first browser automations. Agents return only when a checkpoint fails or behavior changes.

Governance

Organization working rules are anchored by the UKLOK agent entrypoint:

https://github.com/uklok/ai-exchange/blob/main/AGENTS.md

Repository-specific agent guidance lives in AGENTS.md.

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages