Documentation Menu
@arcede/air-sdkAIR SDK
Drop-in wrapper for Playwright, Puppeteer, and Browser Use. Your agent gets resilient selectors, site capability awareness, and a built-in MCP server — without changing your existing code.
Installation
npm install @arcede/air-sdkRequires Node.js 18+. Run npx @arcede/air-sdk init to generate an API key and save it to ~/.config/air/credentials.json (0600 permissions).
Standalone Packages
Don't need the full SDK? We publish lightweight standalone packages:
npx @arcede/air-mcp— MCP server only, for adding AIR tools to Claude Code, Cursor, or Windsurfnpx @arcede/air-cli— Terminal CLI for extracting data and querying capabilities from the command line@arcede/extract— Typed client for the Extract endpoint@arcede/capabilities— Typed client for the Capabilities endpoint
Quick Start
1Playwright
import { chromium } from "playwright";
import { withAIR } from "@arcede/air-sdk/playwright";
const browser = await chromium.launch();
const page = await browser.newPage();
// Wrap the page with AIR — all actions are now observed
const airPage = withAIR(page, {
apiKey: process.env.AIR_API_KEY!,
});
await airPage.goto("https://travel.example.com");
await airPage.fill('[name="origin"]', "SFO");
await airPage.fill('[name="destination"]', "JFK");
await airPage.click('button[type="submit"]');
await browser.close();2Puppeteer
import puppeteer from "puppeteer";
import { withAIR } from "@arcede/air-sdk/puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
const airPage = withAIR(page, {
apiKey: process.env.AIR_API_KEY!,
});
await airPage.goto("https://example.com");
await airPage.type("#search", "flights to NYC");
await airPage.click("#search-btn");
await browser.close();3Browser Use
import { AIRPlugin } from "@arcede/air-sdk/browser-use";
// Add AIR as a plugin to your Browser Use agent
const plugin = new AIRPlugin({ apiKey: process.env.AIR_API_KEY! });
const agent = Agent({ plugins: [plugin] });
await agent.run("Search for flights from SFO to JFK");Configuration
All configuration options for the AIRConfig object passed to withAIR().
import { withAIR } from "@arcede/air-sdk/playwright";
const airPage = withAIR(page, {
// Required
apiKey: "air_sdk_live_abc123...",
// Optional — all have sensible defaults
baseURL: "https://api.agentinternetruntime.com",
telemetryEnabled: true,
cacheEnabled: true,
cacheTTLMs: 1_800_000, // 30 minutes
telemetryBatchSize: 50,
telemetryFlushIntervalMs: 30_000,
debug: false,
// Error callback for non-fatal issues
onError: (err) => console.warn("AIR:", err.message),
// Machine Payments Protocol (optional)
mpp: {
enabled: true,
paymentMethod: "stripe_spt",
credential: "spt_...",
maxPerRequest: 0.50,
maxPerSession: 5.00,
autoApprove: true,
},
});| Option | Type | Default | Description |
|---|---|---|---|
| apiKey | string | — | API key starting with "air_". Get one from the dashboard. |
| baseURL | string | "https://api.agentinternetruntime.com" | Cloud API base URL. Override for self-hosted or staging. |
| telemetryEnabled | boolean | true | Send anonymized usage data to improve selector accuracy. No values or PII are collected. |
| cacheEnabled | boolean | true | Cache capabilities and macros locally to reduce API calls. |
| cacheTTLMs | number | 1,800,000 | Local cache time-to-live in milliseconds (default 30 min). |
| telemetryBatchSize | number | 50 | Max telemetry events buffered before auto-flush. |
| telemetryFlushIntervalMs | number | 30,000 | Telemetry flush interval in milliseconds. |
| debug | boolean | false | Log debug info to console. |
| onError | function | undefined | Callback for non-fatal SDK errors (network, cache, etc.). |
| includeExecution | boolean | false | Include rich execution intelligence fields (tier, extraction rules, entry points) in capability responses. |
| mpp.enabled | boolean | false | Enable Machine Payments Protocol for HTTP 402 auto-payment. |
| mpp.paymentMethod | string | — | Payment method: "stripe_spt" or "crypto_wallet". |
| mpp.credential | string | — | Stripe Shared Payment Token or crypto wallet address. |
| mpp.maxPerRequest | number | — | USD cap per single payment. |
| mpp.maxPerSession | number | — | USD cap per browsing session. |
| mpp.autoApprove | boolean | false | Auto-pay within limits without callback. |
| mpp.onPaymentRequired | function | undefined | Custom async logic for payments exceeding the auto-approve threshold. |
Credential Management
API keys are stored at ~/.config/air/credentials.json with 0600 permissions (owner read/write only). The SDK warns if permissions are too open, similar to SSH.
| Priority | Source | Description |
|---|---|---|
| 1 | AIR_API_KEY | Environment variable (explicit override) |
| 2 | ~/.config/air/credentials.json | Global config (primary store, created by init) |
| 3 | .env | Project-local file (backward compatibility) |
Use npx @arcede/air-sdk whoami to see which key is active and where it was resolved from. Use npx @arcede/air-sdk logout to remove credentials from all locations.
Agent Skill
Give your AI coding agent four web tools with one command. Auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClaw.
# Recommended: auto-detect and configure your agent
npx @arcede/air-sdk install-skill
# Supports Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClawAlternative: Claude Code CLI
# Or add manually via Claude Code CLI:
claude mcp add air-sdk -e AIR_API_KEY=your_key_here -- air-sdk --mcpPerformance Tip
The MCP server starts in ~60s with npx due to package resolution. For instant startup (~2s), install globally:
# Install globally for fast startup (~2s vs ~60s with npx)
npm install -g @arcede/air-sdk
# Then run install-skill to auto-configure all detected agents
npx @arcede/air-sdk install-skill
# install-skill writes the absolute binary path (e.g. /opt/homebrew/bin/air-sdk)
# to each agent config, avoiding npx version caching issues on upgrades.OpenAI Skill
AIR SDK is available as an OpenAI hosted shell skill for gpt-5.4 and gpt-5.4-mini. Upload once, use in any Responses API call with the shell tool.
Requires api.agentinternetruntime.com in your org network allowlist. Two domain_secrets are needed: AIR_API_KEY (env var for the skill code) and Authorization (header injection by the auth sidecar).
{
"model": "gpt-5.4-mini",
"tools": [{
"type": "shell",
"environment": {
"type": "container_auto",
"skills": [{ "type": "skill_reference", "skill_id": "<your_skill_id>" }],
"network_policy": {
"type": "allowlist",
"allowed_domains": ["agentinternetruntime.com", "api.agentinternetruntime.com"],
"domain_secrets": [
{ "domain": "api.agentinternetruntime.com", "name": "AIR_API_KEY", "value": "<key>" },
{ "domain": "api.agentinternetruntime.com", "name": "Authorization", "value": "Bearer <key>" }
]
}
}
}]
}MCP Server
The AIR SDK includes a built-in MCP (Model Context Protocol) server that exposes capabilities and execution tools to AI coding assistants.
Only need the MCP server? npx @arcede/air-mcp is a standalone lightweight package with zero SDK dependencies.
Add this JSON to your agent's MCP config file. The path varies by agent:
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Code:
~/.claude.json - Cursor:
~/.cursor/mcp.json - Windsurf:
~/.codeium/windsurf/mcp_config.json - OpenClaw:
~/.openclaw/openclaw.json
// Recommended: use global binary (npm install -g @arcede/air-sdk)
{
"mcpServers": {
"air-sdk": {
"command": "air-sdk",
"args": ["--mcp"],
"env": {
"AIR_API_KEY": "air_sdk_live_..."
}
}
}
}
// If not installed globally, use "command": "npx" with "args": ["-y", "@arcede/air-sdk", "--mcp"]Tools
| Tool | Description |
|---|---|
| extract_url | Extract structured data from any URL. Best on JSON-LD, RSS/Atom feeds, JSON APIs, and SPAs. Meta-only results cost 0 credits. |
| browse_capabilities | Discover what actions can be automated on a website domain. Returns capabilities with confidence scores, execution tiers, selectors, and universal patterns from similar sites. |
| execute_capability | Get a structured execution plan for a specific capability. Returns CSS selectors, fallbacks, pattern-matched guidance, and entry URLs. |
| report_outcome | Report execution results with optional browserObservations to improve collective intelligence. Feeds the learning system to create verified macros. |
CLI Commands
These commands are bundled with the SDK. For a standalone terminal CLI with extract and capabilities commands, see npx @arcede/air-cli.
| Command | Description |
|---|---|
| npx @arcede/air-sdk install-skill | Auto-detect Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw and register the MCP server. |
| npx @arcede/air-sdk init | Interactive setup: save API key to ~/.config/air/credentials.json. |
| npx @arcede/air-sdk whoami | Show current API key (masked), source, agent status, and verify key. |
| npx @arcede/air-sdk logout | Remove API key from global config and all agent configurations. |
| npx @arcede/air-sdk --mcp | Start the MCP server for Claude Code, Cursor, Windsurf, or OpenClaw. |
| npx @arcede/air-sdk --version | Print the installed SDK version. |
| npx @arcede/air-sdk --help | Show all available commands and usage. |
Privacy
The AIR SDK is designed to be privacy-first. Here's what is and isn't collected:
Collected (anonymized)
- CSS selectors used and success/failure rates
- Action types (click, fill, navigate)
- Domain names and page URLs
- Timing and performance data
Never collected
- Input values (passwords, search terms, form data)
- Cookies or session tokens
- Personally identifiable information (PII)
- Page content or DOM snapshots
Telemetry can be disabled entirely with telemetryEnabled: false in your config.