@ceki/sdk

TypeScript/Node.js SDK for browser.ceki.me — rent real browsers from real people for AI agent automation.

Install

npm install @ceki/sdk

For the CLI (global):

npm install -g @ceki/sdk

Quickstart

import { connect } from '@ceki/sdk';

const client = await connect(process.env.CEKI_API_KEY!);
const options = await client.search({ geo: 'US', language: 'en' });
const browser = await client.rent(options[0].schedule_id);

await browser.navigate('https://example.com');
const snap = await browser.snapshot();
// snap.screenshot — base64 PNG, snap.chat — new messages

await browser.close();
await client.close();

Environment Variables

| Variable | Description | |---|---| | CEKI_API_KEY | Your API key (required) |

API

connect(apiKey, options?) -> Client

Establish a WebSocket connection to the relay. Returns a Client instance.

ConnectOptions

| Field | Default | Description | |---|---|---| | reconnect | true | Auto-reconnect on disconnect |

client.search(filters?, limit?) -> BrowserOption[]

Search for available browsers. Filters: geo, language, etc.

client.rent(scheduleId, opts?) -> Browser

Rent a browser by schedule ID. Waits up to 60s for a match. Options:

• human — 'natural' (default), 'careful', or null (no humanization)
• maskingMode — enable masking
• fingerprint — true, false, or fingerprint object

client.resume(sessionId, opts?) -> Browser

Resume an existing session within its 120s grace window.

client.close()

Close all sessions and the connection.

Browser Methods

await browser.navigate(url)                      // Navigate to URL
await browser.click(x, y)                         // Click at coordinates
await browser.type(text)                          // Type text — one Ceki.typeText command; extension does per-char keydown/keyUp + humanizer delays
await browser.scroll({ deltaY: -300 })            // Scroll
await browser.screenshot({ format: 'png' })       // Screenshot as Buffer
await browser.screenshot({ format: 'base64' })    // Screenshot as {data: string}
await browser.snapshot()                           // Screenshot + chat history
await browser.switchTab()                          // Switch browser tab
await browser.configure({ maskingMode: true })     // Configure session
await browser.upload(selector, pathOrBuffer)       // Upload file to input
await browser.send({ method, params })             // Raw CDP command
await browser.close()                              // End session (alias: release)
await browser.waitUntilEnded()                     // Block until session ends

Chat

await browser.chat.send('Please solve the captcha')
await browser.chat.sendImage('/tmp/screenshot.png')
const messages = await browser.chat.history({ since: ts, limit: 50 })
browser.chat.onMessage(msg => console.log(msg.text))

Profile (cookies + storage)

// Export profile
const profile = await browser.profile.export({
  domains: ['.reddit.com', 'reddit.com'],
});
fs.writeFileSync('profile.json', JSON.stringify(profile));

// Import profile in next session
const saved = JSON.parse(fs.readFileSync('profile.json', 'utf-8'));
await browser.profile.import(saved);

Human Mode

Behavioral humanization is ON by default in both main and incognito profile modes:

• Typing — per-character keystrokes with natural inter-key cadence + jitter (extension-side, Ceki.typeText).
• Mouse — clicks are preceded by a bezier mousemove trajectory (8–35 intermediate mouseMoved events), so the page sees a real pointer trail instead of a teleport.

Fingerprint Tier-2 (UA / timezone / WebGL overrides) stays OFF in main mode to preserve the provider's identity — separate from behavioral humanization.

// Default: behavioral humanizer ON (natural profile)
const browser = await client.rent(scheduleId);

// Explicit profile
const browser = await client.rent(scheduleId, { human: 'careful' });

// Disable session-wide humanization
const browser = await client.rent(scheduleId, { human: null });

Per-call disable

Pass { human: false } to flatten just one call, without leaking jitter to siblings:

await browser.type('[email protected]', { human: false });   // flat keystrokes
await browser.click(120, 240, { human: false });            // straight pointer jump
await browser.scroll({ deltaY: -300, human: false });

The CLI equivalent is --no-human / --raw on type, click, scroll, navigate. Both flags mean "this call only".

Environment overrides

• CEKI_HUMAN_PROFILE — Override default profile name (careful)
• CEKI_HUMAN_PROFILE_PATH — Path to custom JSON profile file
• CEKI_HUMAN_DISABLE=1 — Global kill-switch: disable humanization for every call regardless of per-call human: arguments or CLI flags

Error Classes

| Exception | Cause | |---|---| | AuthError | Invalid API key or token revoked | | RateLimitExceeded | Too many requests. Has .retryAfter (seconds) | | InsufficientFunds | Account balance too low | | SessionEnded | Provider ended the session. Has .reason | | SessionNotFound | Session ID not found | | SessionExpired | Session grace window expired | | NotOwner | Not the session owner | | CdpUnrecoverable | CDP connection lost permanently | | ConnectionLost | Relay connection lost after max reconnects | | TimeoutError | Operation timed out | | TransportError | WebSocket or HTTP transport error | | ChatSendFailed | Chat message failed to send |

CLI

The SDK installs a ceki CLI binary on your PATH.

Install

npm install -g @ceki/sdk

Environment variables

| Variable | Required | Purpose | |---|---|---| | CEKI_API_KEY | yes | Agent token (ag_...) |

Quick start

export CEKI_API_KEY=ag_...

SCHEDULE=$(ceki search --limit 1 | jq -r '.[0].schedule_id')
SID=$(ceki rent --schedule $SCHEDULE | jq -r .session_id)
ceki navigate $SID https://example.com
ceki snapshot $SID -o snap.png
ceki stop $SID

The CLI persists session state locally — after rent it saves the session ID so subsequent commands resume it by SID without re-renting.

Commands

Discovery and lifecycle

| Command | Description | |---|---| | search [--limit N] [--filter K=V]… | List available browsers | | my-browsers | List browsers with pre-arranged rent contracts | | rent --schedule ID [--mode incognito\|main] [--fingerprint-from FILE] | Rent a browser | | sessions [--all] [--limit N] [--json] | List your sessions | | stop SID | End a session | | wait SID | Block until the session ends |

Browser control

| Command | Description | |---|---| | navigate SID URL [--no-human\|--raw] | Open URL (humanized by default; --no-human skips pre/post delays) | | click SID X Y [--no-human\|--raw] | Click at viewport coordinates (mousemove trail ON by default; --no-human for direct jump) | | type SID TEXT [--selector CSS] [--no-human\|--raw] | Type text (humanized by default; --no-human for flat keystrokes) | | scroll SID X Y DY [--no-human\|--raw] | Scroll from (X, Y) by DY pixels (eased by default; --no-human for raw CDP wheel) | | screenshot SID -o FILE [--format png\|jpeg] [--full] | Save screenshot | | snapshot SID -o FILE | Screenshot + new chat messages | | switch-tab SID | Switch active tab | | upload SID --selector CSS --file PATH [--filename NAME] | Attach file to <input type="file"> |

Chat with host

| Command | Description | |---|---| | chat SID send TEXT | Send message to host | | chat SID next [--timeout SEC] | Wait for next host message | | chat SID history [--since TS] [--limit N] | Fetch chat history | | chat SID send-image --image PATH [--text MSG] | Send image to host |

Advanced

| Command | Description | |---|---| | profile SID export -o FILE [--domains CSV] [--no-session-storage] | Export cookies / localStorage | | profile SID import -i FILE | Import previously exported profile | | request-captcha SID [--acceptance SEC] [--completion SEC] [--manual] | Ask host to solve CAPTCHA | | configure SID [--masking-mode VAL] [--fingerprint VAL] | Toggle masking / fingerprint | | cdp SID --method METHOD [--params JSON] | Raw CDP command |

Output and errors

Successful commands write a single JSON line to stdout. Errors go to stderr as {"error": "...", "code": "..."}. Pipe stdout through jq to chain commands.

Exit codes

| Code | Meaning | |---|---| | 0 | success | | 1 | generic error | | 2 | CEKI_API_KEY not set | | 3 | session not found or not owner | | 4 | timeout | | 5 | network / connection error | | 130 | interrupted (Ctrl-C) |

Full reference (with EN+RU): https://browser.ceki.me/docs#cli

Development

npm install
npm run typecheck
npm test
npm run build

License

MIT