Documentation Menu
SDK@arcede/air-sdk

AIR 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

Terminal
npm install @arcede/air-sdk

Requires 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 Windsurf
  • npx @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

playwright-example.ts
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

puppeteer-example.ts
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

browser-use-example.ts
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().

Full configuration example
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,
  },
});
OptionTypeDefaultDescription
apiKeystringAPI key starting with "air_". Get one from the dashboard.
baseURLstring"https://api.agentinternetruntime.com"Cloud API base URL. Override for self-hosted or staging.
telemetryEnabledbooleantrueSend anonymized usage data to improve selector accuracy. No values or PII are collected.
cacheEnabledbooleantrueCache capabilities and macros locally to reduce API calls.
cacheTTLMsnumber1,800,000Local cache time-to-live in milliseconds (default 30 min).
telemetryBatchSizenumber50Max telemetry events buffered before auto-flush.
telemetryFlushIntervalMsnumber30,000Telemetry flush interval in milliseconds.
debugbooleanfalseLog debug info to console.
onErrorfunctionundefinedCallback for non-fatal SDK errors (network, cache, etc.).
includeExecutionbooleanfalseInclude rich execution intelligence fields (tier, extraction rules, entry points) in capability responses.
mpp.enabledbooleanfalseEnable Machine Payments Protocol for HTTP 402 auto-payment.
mpp.paymentMethodstringPayment method: "stripe_spt" or "crypto_wallet".
mpp.credentialstringStripe Shared Payment Token or crypto wallet address.
mpp.maxPerRequestnumberUSD cap per single payment.
mpp.maxPerSessionnumberUSD cap per browsing session.
mpp.autoApprovebooleanfalseAuto-pay within limits without callback.
mpp.onPaymentRequiredfunctionundefinedCustom 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.

PrioritySourceDescription
1AIR_API_KEYEnvironment variable (explicit override)
2~/.config/air/credentials.jsonGlobal config (primary store, created by init)
3.envProject-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
Terminal
# Recommended: auto-detect and configure your agent
npx @arcede/air-sdk install-skill

# Supports Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClaw

Alternative: Claude Code CLI

Terminal
# Or add manually via Claude Code CLI:
claude mcp add air-sdk -e AIR_API_KEY=your_key_here -- air-sdk --mcp

Performance Tip

The MCP server starts in ~60s with npx due to package resolution. For instant startup (~2s), install globally:

Terminal
# 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).

Responses API
{
  "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
mcp.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

ToolDescription
extract_urlExtract structured data from any URL. Best on JSON-LD, RSS/Atom feeds, JSON APIs, and SPAs. Meta-only results cost 0 credits.
browse_capabilitiesDiscover what actions can be automated on a website domain. Returns capabilities with confidence scores, execution tiers, selectors, and universal patterns from similar sites.
execute_capabilityGet a structured execution plan for a specific capability. Returns CSS selectors, fallbacks, pattern-matched guidance, and entry URLs.
report_outcomeReport 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.

CommandDescription
npx @arcede/air-sdk install-skillAuto-detect Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw and register the MCP server.
npx @arcede/air-sdk initInteractive setup: save API key to ~/.config/air/credentials.json.
npx @arcede/air-sdk whoamiShow current API key (masked), source, agent status, and verify key.
npx @arcede/air-sdk logoutRemove API key from global config and all agent configurations.
npx @arcede/air-sdk --mcpStart the MCP server for Claude Code, Cursor, Windsurf, or OpenClaw.
npx @arcede/air-sdk --versionPrint the installed SDK version.
npx @arcede/air-sdk --helpShow 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.