# Surf

> The open protocol for the agentic web.

Surf lets any website expose typed commands for AI agents — like robots.txt, but for what agents can *do*.

Instead of screenshots, DOM parsing, or browser automation, agents discover a manifest at `/.well-known/surf.json` and execute commands directly via HTTP, WebSocket, or in-browser.

## This Site is Surf-Enabled

This website dogfoods the Surf protocol. Try:

```bash
# Discover commands
curl https://surf.codes/.well-known/surf.json

# Execute a search
curl -X POST https://surf.codes/surf/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "docs.search", "params": {"query": "authentication"}}'

# Get all packages
curl -X POST https://surf.codes/surf/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "packages.list"}'

# Pipeline: get project info + packages + changelog in one call
curl -X POST https://surf.codes/surf/pipeline \
  -H "Content-Type: application/json" \
  -d '{"steps": [{"command": "project.info"}, {"command": "packages.list"}, {"command": "changelog.latest"}]}'
```

## Quick Start

```
npm install @surfjs/core
```

## Links

- Website: https://surf.codes
- Documentation: https://surf.codes/docs
- GitHub: https://github.com/hauselabs/surf
- npm: https://www.npmjs.com/org/surfjs
- Protocol Spec: https://github.com/hauselabs/surf/blob/main/SPEC.md

## Packages (7)

- @surfjs/core — Server-side: command registry, manifest, middleware, auth
- @surfjs/client — Agent-side: discover, execute, pipeline, sessions
- @surfjs/cli — Terminal: inspect, test, ping Surf endpoints
- @surfjs/devui — Browser dev inspector for commands
- @surfjs/next — Next.js App Router adapter with manifest serving
- @surfjs/react — React hooks for Surf Live real-time state sync
- @surfjs/zod — Zod schema integration for parameter validation

## Key Features

- Discovery via /.well-known/surf.json (auto-generated manifest with checksums)
- Typed parameters with validation and examples
- Pipeline execution (chain commands with $prev references)
- SSE streaming for long-running commands
- WebSocket transport for full-duplex communication
- Surf Live — real-time state sync between agents and browser UIs
- Session management with server-side state
- Auth (Bearer, API key, scoped, optional, hidden)
- Rate limiting per-token, per-session, per-command
- Framework adapters: Express, Fastify, Hono, Next.js