Skip to main content
Local Agent Browser CLI is now part of Agent Browser CLI. The gologin-local-agent-browser-cli npm package is deprecated: install gologin-agent-browser-cli and use --runtime local. Scripts that call gologin-local-agent-browser keep working, see Migrate from Local Agent Browser CLI.
Agent Browser CLI has two runtimes with the same commands. The cloud runtime runs sessions in Gologin Cloud Browser. The local runtime runs them in Orbita, the Gologin browser, on your own machine. This page covers the local runtime. Snapshots, refs and other commands work as described on the Agent Browser CLI page.

When to use local vs cloud


Requirements

  • Node.js 20 or later. The local runtime starts Orbita through the Gologin Node.js SDK, which needs Node.js 20.
  • A Gologin API token in GOLOGIN_TOKEN. See Get a token.
  • A profile ID for every session. Unlike the cloud runtime, the local runtime doesn’t create temporary profiles.
  • Orbita. If it isn’t installed yet, the Gologin SDK downloads it to ~/.gologin/browser on first launch. If Orbita is somewhere else, set GOLOGIN_EXECUTABLE_PATH.

Install

The package installs two commands:
  • gologin-agent-browser runs browser sessions in the cloud unless you choose local.
  • gologin-local-agent-browser is a compatibility alias that runs commands in the local runtime.

Choose the local runtime

Pass --runtime local to a command, or set the runtime once for the whole shell:
--local and a leading local work too: gologin-agent-browser local open https://example.com --profile your_profile_id.
Session commands such as snapshot, click and close go to the cloud runtime unless you choose local. After you open a local session, pass --runtime local to every command that follows, or set GOLOGIN_AGENT_BROWSER_RUNTIME=local.
Gologin API commands such as api, browser and proxy always call the API directly, whatever the runtime.

Environment variables

The local runtime keeps its config, profile list and job history in ~/.gologin-local-agent-browser/, the same folder the old CLI used.

Quick start

--visible (or --headed) and --headless (or --background) choose the window mode for one open. open-visible and open-background are shortcuts for them.

Browser commands

Session commands are the same as in the cloud runtime: snapshot, click, type, fill, find, wait, press, scroll, tabs, cookies, storage-export, eval, screenshot, pdf, upload and more. See the command reference. back, forward and reload work only in the cloud runtime for now. find locates an element on the live page and acts on it in one step. Use it when refs go stale on dynamic pages:

Profile commands

These commands run in the local runtime even without --runtime local: profile-create and profile-update take a use-case template and a proxy. --proxy-country us adds a Gologin proxy, --proxy-host with --proxy-port sets your own.

Runbooks and batch jobs

A runbook is a JSON file with a list of CLI steps:
Run it on one profile, or on many profiles in parallel:
targets.json lists the profiles:
Check the results with jobs and job <jobId>. --status takes running, ok, partial or failed:

Migrate from Local Agent Browser CLI

  • Scripts that call gologin-local-agent-browser keep working. The command now comes from gologin-agent-browser-cli.
  • Profiles, config and job history in ~/.gologin-local-agent-browser/ stay where they are.
  • For AI agents, install the Agent Browser skill. It covers both runtimes, and the separate Local Agent Browser skill is deprecated.

npm package

gologin-agent-browser-cli

Source code

GologinLabs/agent-browser