# Tanuki: Interactive Browser Automation & Authentication Engine for AI Agents

> Tanuki is an open-source, high-performance interactive browser automation and authentication engine built by Shuffle (https://shuffler.io). It bridges AI agents with complex web applications through isolated remote Chromium sandboxes, self-healing path optimization, AI-driven login navigation, SSO/OAuth popup handling, and secure API credential extraction.

## Core Capabilities
- **Interactive Browser Sandbox**: Remote ephemeral Chromium sandboxes with real-time bidirectional CDP/WebRTC/SSE screencasting and mouse/keyboard event injection.
- **Self-Healing Path Optimizer**: Multi-tier heuristic + LLM DOM element resolver with automatic failure invalidation and cross-tenant learning.
- **Smart Login Navigator**: Automated discovery of login gates, OAuth popups (Google, GitHub, Microsoft, Okta, SAML), and credential submission.
- **Stealth Evasion & Anti-Bot**: Turnstile and reCAPTCHA challenge mitigation, stealth navigator masks, and cookie consent CMP auto-dismissal.
- **Zero-Storage Session Vault**: Ephemeral in-memory encryption with TTL expiry for extracted tokens and credentials.
- **Shuffle Ecosystem Integration**: Direct regional datastore synchronization (`/api/v2/{category}/{key}`) and tenant-isolated workflow automation.

## Quick Links
- [Interactive Sandbox Demo](https://tanuki.to/demo): Web-based live playground for testing automation goals.
- [Connect SDK Guide](https://tanuki.to/sdk): `@shuffler/tanuki` NPM package & embedded client SDK.
- [AI Agent Integration Guide](https://tanuki.to/agents.md): Prompting instructions for Cursor, Devin, Claude, and autonomous agents.
- [Full LLM Specification](https://tanuki.to/llms-full.txt): Complete technical reference and REST API specifications.
- [GitHub Repository](https://github.com/shuffle/tanuki): Open-source Go & TypeScript codebase.

## API Reference
- `POST /api/v1/sessions`: Create an isolated browser automation session.
- `GET /api/v1/sessions/:id`: Inspect session status and goal execution plan.
- `GET /api/v1/sessions/:id/events`: Real-time Server-Sent Events (SSE) telemetry stream.
- `DELETE /api/v1/sessions/:id`: Terminate session and release browser container.
- `POST /api/v1/login`: Proxy user authentication to Shuffle backend.
- `POST /api/v1/register`: Register new user account.
- `POST /api/v1/logout`: Secure session revocation.
- `POST /api/v1/llm/test`: Test OpenAI-compatible and Shuffle LLM connectivity.

## NPM SDK Usage
```bash
npm install @shuffler/tanuki
```

```typescript
import { TanukiConnect } from '@shuffler/tanuki';

const tanuki = new TanukiConnect({
  serverUrl: 'https://tanuki.to',
  backendUrl: 'https://uk.shuffler.io'
});

// Launch interactive automation modal
const sessionId = await tanuki.open({
  targetUrl: 'https://github.com/settings/tokens',
  goal: 'get_api_key'
});
```