https://github.com/zk1tty/login-run

Simplest API server to execute and persist the user login session on remote browser
https://github.com/zk1tty/login-run

browser-automation browserless

Last synced: 22 days ago
JSON representation

Simplest API server to execute and persist the user login session on remote browser

• Host: GitHub
• URL: https://github.com/zk1tty/login-run
• Owner: zk1tty
• License: mit
• Created: 2026-05-04T19:03:09.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2026-05-29T06:06:38.000Z (27 days ago)
• Last Synced: 2026-05-29T08:09:41.222Z (27 days ago)
• Topics: browser-automation, browserless
• Language: TypeScript
• Homepage: https://stay-authed.onrender.com
• Size: 28 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Login Run 🏃🏻‍♀️

Login Run is a minimal API for turning one-time human login into reusable, authenticated browser sessions for agents.

Many workflows still depend on portals without APIs, where the agent needs to read or update data inside an end user's account. The user has to log in, pass CAPTCHA and OTP(one time passcode), and then the agent needs to keep working later **without asking the user to repeat the same login flow**.    

Login Run provides the remote browser session layer for that.

Try it from [Demo site](https://stay-authed.onrender.com/demo)

> [!TIP]

> **Result:** HealthEquity login became **3x faster** than using browser agent on runtime — from **85 seconds** to **24 seconds**.

> So you can integrate this workflow synchronously to your frontend or chatbot via tool call, and launch the product!



  



## What It Provides

Login Run has two parts:

1. **LoginRun API** — a minimal API for logging into anti-bot-heavy web portals, handling CAPTCHA/OTP checkpoints, and maintaining authenticated browser session state for repeat agent workflows.

2. **LoginRun Codegen** — a ReAct-style onboarding loop that generates site profiles and regression fixtures for deterministic browser automation, then validates them locally before they are promoted into API-backed workflows.

The API keeps authentication/session management separate from agent logic. Codegen helps teams add new websites without manually scripting every login flow.

## Current API

The server exposes a small async login API.

```text

GET  /health

POST /v1/logins

GET  /v1/logins/:runId

GET  /v1/logins/:runId/events

POST /v1/logins/:runId/otp

```

Start phase 1:

```bash

curl -s -X POST http://127.0.0.1:8787/v1/logins \

  -H "content-type: application/json" \

  -d '{

    "customerId": "demo-user",

    "targetUrl": "https://example.com/login",

    "username": "user@example.com",

    "password": "password",

    "otpDeliverySelection": "email"

  }'

```

Poll status:

```bash

curl -s http://127.0.0.1:8787/v1/logins/

```

Submit OTP:

```bash

curl -s -X POST http://127.0.0.1:8787/v1/logins//otp \

  -H "content-type: application/json" \

  -d '{"code":"123456"}'

```

Frontend clients can also subscribe to:

```text

GET /v1/logins/:runId/events

```

Polling is the source of truth; SSE is for frontend completion callbacks.

## LoginRun Codegen

Try the standalone Codegen demo without cloning this repo:

```bash

npx @loginrun/codegen demo

```

It generates a redacted HealthEquity-style onboarding profile, fixture artifacts, regression test, and report under `./loginrun/healthequity`. The demo does not submit credentials, request OTP, call LoginRun APIs, or require Browserless configuration.

## Proof of CAPTCHA resolver

Login Run has been tested against Cloudflare Turnstile behavior using the public test page:

```text

https://browser-compat.turnstile.workers.dev/

```

The run below is generated from real captured screenshots:

![Cloudflare Turnstile auto-mode frames](docs/research/turnstile/assets/cloudflare-turnstile-auto-mode-frames.gif)

It has also completed a real HealthEquity-style login workflow against:

```text

https://my.healthequity.com/ClientLogin.aspx

```

The animation below was generated from all screenshots in one captured run:

![HealthEquity login workflow](docs/research/login/assets/healthequity-login-run-animated.png)

## Setup

```bash

cp .env.example .env

npm install

npm run start:bl-server

```

Useful environment:

- `BROWSERLESS_TOKEN`

- `BL_PROXY=local|cloud|cloud_stealth|cloud_stealth_residential|cloud_stealth_residential_sticky`

- `PUPPETEER_API_HOST=0.0.0.0`

- `PUPPETEER_API_PORT=8787`

Browserless target profiles live in `config/browserless-targets.json`.

## Scripts

```bash

npm run login:probe

npm run login:probe:concurrency

npm run otp:gmail:init

npm run otp:gmail:watcher

npm test

```