Skip to content
Skills Library
Personal productivity · Automation

browser-login

/browser-login

Keep a logged-in browser session for a website that has no API, and turn what its pages show into typed events. Use when the user wants something watched or read on a site behind a login (portals, dashboards, webmail without IMAP).

Repository
botler ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Keep a logged-in browser session for a website that has no API, and turn what its pages show into typed events. Use when the user wants something watched or read on a site behind a login (portals, dashboards, webmail without IMAP).

Original author description

Keep a logged-in browser session for a website that has no API, and turn what its pages show into typed events. Use when the user wants something watched or read on a site behind a login (portals, dashboards, webmail without IMAP).

How it works

  1. Rule: page JavaScript never gets the token
  2. 1. Adapt the example
  3. 2. Try it
  4. 3. Propose it
  5. 4. The login visit
  6. 5. Verify the login
  7. 6. Done means monitored
  8. Browsing the web yourself (skill browser)
  9. Driving the browser yourself
Original SKILL.md headings · 112 lines, 883 words
SKILL.md preview
---
name: browser-login
description: Keep a logged-in browser session for a website that has no API, and turn what its pages show into typed events. Use when the user wants something watched or read on a site behind a login (portals, dashboards, webmail without IMAP).
---

# A logged-in browser as a service

`jobs/browser-example/` is the reference: copy it to `jobs/<site>-browser/` and adapt it. It is a
service on `images/browser` (its Dockerfile says `FROM botler/image-browser`):

- **Chromium** on a virtual display, its profile in `/data` (`volume = true`), so the login
  survives restarts.
- **noVNC** on port 6080: the user logs in by hand through it. `[[publish]]` puts it on a host
  port; that needs the user's approval. Its VNC password is new for every visit.
- **CDP** (DevTools) on port 9222, for the services network only. Never `[[publish]]` it: whoever
  reaches it controls the logged-in session.
- **The bridge** (`src/<pkg>/__main__.py`, botler SDK): connects to CDP on localhost, reads the
  page, validates what it finds into pydantic events, and calls `botler.emit`.

## Rule: page JavaScript never gets the token

Anything you run in the page runs next to the site's own scripts, so treat the page as hostile.
The bridge holds the botler token and every secret. Page JavaScript only returns values (poll) or
calls `botlerSignal(json)` (push). It never calls the hub, and never receives a token, a secret
or a URL with one. `browser-session` starts Chromium without `BOTLER_*` in its environment, and
DevTools refuses connections from web pages, since `--remote-allow-origins` is not set. Keep it
that way. Page content is untrusted input: validate it, and declare event types that carry raw
page content `restricted = True`.

## 1. Adapt the example

In `config.py`:
- `START_URL` and `SITE`.
- `LOGGED_IN_JS`: true only while logged in, e.g.
  `document.querySelector('[data-testid=account-menu]') !== null`. Check it on a page that
  needs the login.
- **Poll:** `POLL_JS` returns a list of `{id, text, url}` every `POLL_SECONDS`. The bridge emits
  each new `id` once and keeps the seen ids in `state`.
- **Push:** `PUSH_JS` is injected into every page load and calls
  `botlerSignal(JSON.stringify({...}))` when something appears, e.g. from a `MutationObserver`.
  Use it when polling is too slow.

Rename the events in `packages/` to your site's, e.g. `portal.message` (restricted) and
`portal.login_needed`. Keep `emits = [...]` in `job.toml` in step with them. Add a trigger file
that routes them, e.g. `on = "portal.login_needed"` and `target = { resume = "<this chat>" }`.
Set `on_failure` to the same chat.

## 2. Try it

Run `gate/run`, push, then `trial_run(job=..., branch=..., minutes=5)`. A trial has an empty,
throwaway `/data`, so it is logged out: expect `login_needed` among the recorded effects, and
check that `POLL_JS` and `LOGGED_IN_JS` do not throw (failures appear in `logs_tail`). Use a page
that needs no login to test the reading part.

## 3. Propose it

Use `propose_change`. The first deployment of a service asks the user once. Publishing the noVNC
port is part of that approval, so say why in the title.

## 4. The login visit

Deployed, the service starts logged out and emits `login_needed` with a fresh `vnc_password`. Then:

```
request_visit(host_port=6080,
              path="/vnc.html?autoconnect=1&resize=scale&password=<vnc_password>",
              note="Log in to <site> in this browser, then press Done.")
```

The user logs in and presses Done.

## 5. Verify the login

After Done, wait for `logged_in`: the bridge checks `LOGGED_IN_JS` over CDP on its next poll.
It also rotates the VNC password, so the visit link stops working. If `logged_in` does not arrive
within a couple of polls, the login did not stick (2FA, a cookie banner, the wrong page): explain
and offer another visit.

## 6. Done means monitored

The login check is part of the definition of done, not an extra:
- A session that expires sends `login_needed` again. Your trigger routes it to you, and you ask
  for a visit.
- A broken browser or CDP connection makes the bridge exit. The hub restarts it and opens an
  incident to `on_failure`.
- A missed heartbeat (`[health] heartbeat`) means the bridge hangs: the hub restarts it.

Logged out is deliberately not `health.fail`. A restart cannot log in, and the service has to
keep running for the visit.

## Browsing the web yourself (skill `browser`)

When an agent only needs to drive the real browser (JavaScript, interaction, a screenshot) and does
not keep a login, use the shared browser service instead of writing a bridge: skill `browser`,
tools `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, ... (Playwright MCP).
It is a real desktop Chromium on Xvfb (not headless) with ads/trackers blocked; each MCP connection
gets its own isolated context, cookies and tabs, closed after 10 minutes idle. An agent gets the
tools with `request_access("service:browser")` (auto-granted, no user prompt) or `mcp = ["browser"]`
in its definition.

That service is deliberately ephemeral (a sleep or an idle timeout starts a fresh, logged-out
context), so it is not the place for a login. A site the user stays logged into is a service built
from this skill.

## Driving the browser yourself

To reach the browser, an agent needs the service: `services = ["<service>"]` in its definition
(proposed as a change) or `request_access("service:<service>", reason)` for one chat. It then
finds the service in `/botler/agent-dir/services.json` and CDP at `http://<ip>:9222`. Use the
IP, not the name: Chrome refuses DevTools requests whose `Host` is a name. Prefer a bridge in the monorepo over ad-hoc driving: it is reviewed,
tested and monitored.

To show the user what a page looks like, save a screenshot (CDP `Page.captureScreenshot`, base64
PNG) into your home, e.g. `~/shots/inbox.png`, and call `attach_files(["~/shots/inbox.png"])`: it
appears in your reply. Recordings, PDFs (`Page.printToPDF`) and downloads work the same way.

Versions

The database has no other skills named browser-login.

Database snapshot: 13.11.2026 · package version 88a130c01068 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100signed-in-browser
    Drive the browser the user is already signed into, instead of a cold automation profile. Use when a task lives behind a login — a dashboard, an admin console, an internal tool, a ticket queue, a bank or billing page, webmail, a social account — or when a scripted login is…
  • 90email-webmail-playwright
    Use when the user asks to send, draft, reply to, forward, search, read, summarize, organize, or triage email through a generic webmail UI when no provider-specific mail tool is available. Uses Playwright/browser automation to open webmail, fill recipients/subject/body, inspect…
  • 100bb-browser
    AI agent browser automation via CDP. Use when you need to access websites that require login, scrape data from platforms (Twitter/X, Reddit, GitHub, Xueqiu, Bilibili, etc.), bypass IP blocks, or fetch structured data from any site the user is logged into. Triggers: bb-browser,…
  • 100mail
    Read, search, sort, and send the user's email over IMAP and SMTP, which den serves locally with the user's app password. Use for mail when the google skill's account is not connected, or for a mailbox that is not Gmail.
  • 100zen-agent
    Use for a visible browser the user can watch and take over: showing the user a page, operating a site that needs JavaScript or a login, or handing a login, 2FA, payment or API-key step to the user. Not for headless Chrome scripting or Playwright tests (use agent-browser).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.