Stealth Browser

A Camoufox cloud browser and hosted-agent platform, with an independently usable
stealth-cli browser component. Penguin Harness
is the integrated Agent Core. Applications use the project-scoped platform API;
cloud SDK clients remain pending.

Implementation status

Part	Status
stealth-cli	Working CLI, local SDK, daemon, HTTP and MCP; npm version 0.7.0, with unreleased perception improvements in source
API, workers, contracts	Working local browser creation, navigation, snapshots, events and verified cleanup; account-scoped projects, durable SQLite state; separate token-only development mode
Website	Working account/project/key/browser/Profile/Workspace/Agent console, proxy configuration, browser assets, schedules, Webhooks and HTTP/MCP tools; remaining v2 screens pending
Agent runtime	Pinned Penguin engine/provider adapter; scoped browser/Workspace/external tools, persistent sessions/runs and cancellation
Product prototype	Interactive design with local demo data

The current development scope is all non-payment v2 functionality. The
development plan tracks delivery;
the specification defines product and browser-component boundaries.

Use the browser component

npm install -g stealth-cli
stealth --help

For commands, local SDK examples, persistence and MCP setup, read the
component README.

Develop from source

The platform workspace needs Node.js 24 or newer and npm. The independent browser
component supports Node >=20. The component's install
hook downloads Camoufox; npx camoufox-js fetch retries a failed download.
Hosted runs use an operator model from .env or a project BYOK connection.
The console provides encrypted credentials and model connection tests; allowed
provider origins are operator configuration. See the API setup below.

The root allowScripts policy enables the existing CLI install hook and native
dependencies on npm versions that require explicit lifecycle-script approval.

git clone https://github.com/Youhai020616/stealth-browser.git stealth-browser
cd stealth-browser
npm ci
npm start -- --help
cp .env.example .env
npm run dev
npm run test:unit
npm run test:integration
npm run test:e2e
npm run docs:check
npm run test:package

npm test runs repository tooling, platform unit/integration/E2E tests and the
component's full suite. npm run demo:browser runs a self-contained real
Camoufox chain through the local API, including process cleanup and capacity
reuse. For a persistent development API, follow API setup.
test:package packs and installs the CLI in a temporary consumer project,
checks its CLI/SDK and launches a real Camoufox browser. It needs npm network
access and the browser binary; temporary consumer files are removed afterward.

The design prototype is a git-ignored checkout under artifacts/designs/; when its own
preview server is running it is reviewed at http://127.0.0.1:48631/
(design records). The actual account console runs at
http://127.0.0.1:48632/ through npm run dev.
Configure email delivery in .env to register and verify accounts; Google/GitHub
are optional configured providers. See setup and limits.

Repository map

apps/                   Web, API and worker application boundaries
packages/stealth-cli/    Published browser CLI and local SDK
packages/platform/      Platform domain and persistence boundary
packages/agent-runtime/ Penguin integration boundary
packages/contracts/     Cloud API and event contract boundary
packages/cloud-sdk/     JavaScript cloud SDK boundary
sdks/python/            Python cloud SDK boundary
tests/                  Repository tooling and platform unit/integration/E2E tests
infra/                  Deployment configuration boundary
scripts/                Repository checks
docs/                   Architecture, decisions, guidelines and design records
tasks/                  In-flight development plans
resources/              Ignored upstream reference checkouts
artifacts/              Ignored prototypes, design assets and verification evidence

The root package is private. The only publishable workspace is stealth-cli;
package operations target packages/stealth-cli/. Its release notes live in
CHANGELOG.md.

Read AGENTS.md before contributing and
the architecture before changing module boundaries.

License

MIT. Upstream reference checkouts retain their own licenses.

Cloud Workspaces provide project file uploads/folders, safe previews, ZIP downloads
and Penguin file input/output with persistent session binding. See the
Workspace API for limits and remaining
production storage work.

Scheduled Agent runs are available under Configuration in the tracked console:
daily/interval/Cron, timezone previews, pause/edit/manual run and execution history.
See the schedule API. Signed Webhooks provide event subscriptions,
test delivery, HMAC signatures, retry/replay and attempt history.
HTTP/MCP tool integrations provide
project connections, encrypted tokens, discovery/allowlists, Agent/schedule selection
and actual tool execution. Provider-specific OAuth connectors remain part of the ongoing v2 delivery.

Project teams support verified-account invitations, member roles/removal/leave and
ownership transfer for non-default projects. Existing API keys are permanently
revoked on removal or admin demotion. See team behavior.