Python SDK (linege-sdk)

Python SDK for the Linege anti-fingerprint browser platform.

Provides:

• LinegeApi -- Cloud API client (auth, environments, proxies)
• SidecarClient -- Local WebSocket client for browser control (DOM actions, mirror input, navigation)
• launch_chrome -- Chrome process launcher with gost proxy tunnel
• Utilities -- Path resolution, free port detection, GPU detection

Installation

pip install https://pub-69fcb37602174d10b2152f09439de470.r2.dev/sdk/linege_sdk-0.2.0-py3-none-any.whl

For development:

cd packages/linege-sdk-python
pip install -e ".[dev]"

Quick Start

Token Auth

from linege_sdk import LinegeApi

api = LinegeApi(api_url="https://api.sybilslayer.com", token="YOUR_TOKEN")

profile = api.get_user_profile()
print(f"{profile.user.username}: {profile.quota.remaining} envs remaining")

env = api.create_environment(country="JP", name="demo")
print(f"Created: {env.env_id}, proxy: {env.proxy}")

Username/Password Auth

from linege_sdk import LinegeApi

api = LinegeApi.from_login("https://api.sybilslayer.com", "alice", "secret123")

Sidecar (Browser Control)

from linege_sdk import SidecarClient

with SidecarClient("ws://127.0.0.1:7788/chrome") as sc:
    sc.register(env_id)
    sc.navigate("https://example.com")
    sc.dom_click("input[name='q']")
    sc.dom_input("input[name='q']", "hello from python sdk")
    sc.dom_scroll(delta_y=300)
    html = sc.dump_html()

API Reference

LinegeApi

Method	Description
LinegeApi(api_url, token, timeout=20)	Constructor (token auth)
LinegeApi.from_login(api_url, username, password)	Constructor (login auth)
login(username, password) -> LoginResponse	Login and auto-set token
get_health() -> HealthResponse	Service health check
get_countries() -> CountriesResponse	Available countries
get_version() -> VersionResponse	Client version info
get_user_profile() -> UserProfileResponse	Current user profile + quota
create_environment(country, name?, platform?, note?) -> CreateEnvResponse	Create browser environment
get_environment(env_id, auto_heal_proxy=True) -> EnvDetail	Get environment details
list_environments(page=1, limit=20) -> EnvListResponse	List environments
delete_environment(env_id) -> DeleteEnvResponse	Delete environment
refresh_proxy(env_id, reason?) -> RefreshProxyResponse	Refresh proxy
report_proxy_dead(env_id, consecutive_failures=1, reason?) -> ReportProxyDeadResponse	Report dead proxy

SidecarClient

Method	Description
SidecarClient(url, timeout=10)	Constructor
connect()	Connect to sidecar WebSocket
close()	Disconnect
register(env_id)	Register browser with env ID
set_mirror_mode(enabled)	Enable/disable mirror mode
claim_master(bounds?)	Claim master role
send_input(input_payload)	Send raw input event
send_resize(payload)	Send resize event
dom_click(selector, x?, y?)	Click element by selector
dom_input(selector, value)	Set input value
dom_focus(selector)	Focus element
dom_scroll(delta_x=0, delta_y=0, selector?)	Scroll page/element
dump_html(max_nodes=500)	Dump page HTML
dump_axtree(max_items=200)	Dump accessibility tree
navigate(url)	Navigate to URL
eval_script(script)	Evaluate JavaScript
press_sequentially(selector, text, delay_ms=50)	Type text char-by-char
auto_click/auto_input/auto_scroll/auto_navigate/auto_eval	Auto-prefixed aliases
on_message(handler)	Register message callback

Launcher

Function	Description
launch_chrome(env_detail, data_dir?, chrome_path?, sidecar_port?) -> LaunchResult	Launch Chrome with gost tunnel
stop_process_tree(pid)	Kill process tree

Utilities

Function	Description
get_free_port() -> int	Find available TCP port
resolve_chrome_path() -> str	Locate Chrome binary
resolve_data_dir() -> str	Locate data directory
resolve_gost_path() -> str	Locate gost binary

Types

Type	Key Fields
LoginResponse	token, user: UserInfo, quota: Quota
UserProfileResponse	user: UserInfo, quota: Quota, stats: UserStats
CreateEnvResponse	env_id, country, proxy, quota_remaining, profile
EnvDetail	extends CreateEnvResponse + name, status, created_at
EnvListResponse	environments: List[EnvListItem], pagination: Pagination
DeleteEnvResponse	message
RefreshProxyResponse	env_id, country, proxy
ReportProxyDeadResponse	message, new_proxy
HealthResponse	status, timestamp
CountriesResponse	countries: List[CountryInfo]
VersionResponse	versions: Dict[str, VersionInfo]
ProfileConfig	profile_id, env_id, enabled_modules, base, hooks

Environment Variables

Variable	Description	Default
API_BASE	Linege API base URL	https://api.sybilslayer.com
API_TOKEN	Bearer token	(none)
LINEGE_USERNAME	Username for login auth	(none)
LINEGE_PASSWORD	Password for login auth	(none)

Examples

# Full CRUD workflow
python examples/example_full.py --api-url https://api.sybilslayer.com --username alice --password secret

# With token
python examples/example_full.py --token YOUR_TOKEN

# Group control E2E
python examples/real_group_control_e2e.py

# Google search flow E2E
python examples/real_google_flow_e2e.py

Notes

• api_url accepts both https://host and https://host/api/v1 (auto-normalized).
• Default request timeout is 20s, configurable via timeout parameter.
• All API calls produce structured JSON logs with trace_id and timing.
• The SDK is typed (PEP 561 py.typed marker included).