# @lov3kaizen/agentsea-surf

> Surf - Computer-use agent for AgentSea. Control desktop environments through screen capture, mouse, and keyboard actions using Claude's vision capabilities.

Latest version **1.2.1** (published 2026-07-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @lov3kaizen/agentsea-surf
pnpm add @lov3kaizen/agentsea-surf
yarn add @lov3kaizen/agentsea-surf
bun add @lov3kaizen/agentsea-surf
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2026-07-02 |
| First published | 2026-01-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 4 |
| Unpacked size | 1.3 MB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| Author | lovekaizen |
| Maintainers | lov3kaizen |
| Keywords | agentsea, surf, ai, agents, computer-use, desktop-automation, screen-capture, mouse-control, keyboard-control, vision, claude, anthropic, puppeteer, automation, rpa, typescript, nodejs, nestjs |

## Links

- npm: https://www.npmjs.com/package/@lov3kaizen/agentsea-surf
- Repository: https://github.com/lovekaizen/agentsea
- Homepage: https://agentsea.dev
- Issues: https://github.com/lovekaizen/agentsea/issues
- npm.io page: https://npm.io/package/@lov3kaizen/agentsea-surf

## Dependencies (4)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [sharp](https://npm.io/package/sharp.md) ^0.33.0
- [@lov3kaizen/agentsea-core](https://npm.io/package/@lov3kaizen/agentsea-core.md) 1.2.1
- [@lov3kaizen/agentsea-types](https://npm.io/package/@lov3kaizen/agentsea-types.md) 1.2.1

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.2.1 (latest) — 2026-07-02
- 1.2.0 — 2026-06-30
- 1.1.1 — 2026-06-30
- 1.1.0 — 2026-06-25
- 1.0.1 — 2026-06-16
- 1.0.0 — 2026-06-16
- 0.8.0 — 2026-06-16
- 0.6.0 — 2026-02-09
- 0.5.2 — 2026-01-04
- 0.5.1 — 2026-01-04

## README

# @lov3kaizen/agentsea-surf

Surf - Computer-use agent for AgentSea. Control desktop environments through screen capture, mouse, and keyboard actions using Claude's vision capabilities.

## Features

- **8 Computer-Use Tools**: screenshot, click, type, scroll, drag, key press, cursor move, wait
- **Multiple Backends**: Native (macOS, Linux, Windows), Puppeteer browser, Docker container
- **Claude Vision Integration**: Automatic screen analysis and action determination
- **NestJS Integration**: Full REST API and WebSocket support
- **Security Sandboxing**: Rate limiting, command blocking, domain/path restrictions

## Installation

```bash
npm install @lov3kaizen/agentsea-surf
# or
pnpm add @lov3kaizen/agentsea-surf
```

### Optional Dependencies

```bash
# For browser automation
npm install puppeteer

# For image processing
npm install sharp
```

## Quick Start

### Basic Usage

```typescript
import { SurfAgent, createNativeBackend } from '@lov3kaizen/agentsea-surf';

async function main() {
  // Create a native backend for your platform
  const backend = createNativeBackend();
  await backend.connect();

  // Create the agent
  const agent = new SurfAgent('session-1', backend, {
    maxSteps: 20,
    vision: {
      model: 'claude-sonnet-4-6',
      maxTokens: 4096,
      includeScreenshotInResponse: true,
    },
  });

  // Execute a task
  const result = await agent.execute('Open Chrome and navigate to google.com');

  console.log('Result:', result.response);
  console.log('Steps taken:', result.state.actionHistory.length);

  await backend.disconnect();
}

main().catch(console.error);
```

### With Streaming

```typescript
const agent = new SurfAgent('session-1', backend, config);

for await (const event of agent.executeStream('Search for weather')) {
  switch (event.type) {
    case 'screenshot':
      console.log('Screenshot taken');
      break;
    case 'action':
      console.log(`Executing: ${event.action.description}`);
      break;
    case 'complete':
      console.log('Task completed:', event.response);
      break;
  }
}
```

### NestJS Integration

```typescript
import { Module } from '@nestjs/common';
import { SurfModule } from '@lov3kaizen/agentsea-surf/nestjs';

@Module({
  imports: [
    SurfModule.forRoot({
      backend: { type: 'native' },
      config: {
        maxSteps: 50,
        sandbox: { enabled: true },
      },
      enableRestApi: true,
      enableWebSocket: true,
    }),
  ],
})
export class AppModule {}
```

## Backends

### Native Backend

Automatically selects the appropriate backend for your platform:

```typescript
import { createNativeBackend } from '@lov3kaizen/agentsea-surf';

const backend = createNativeBackend({ displayIndex: 0 });
```

### Browser Backend (Puppeteer)

```typescript
import { PuppeteerBackend } from '@lov3kaizen/agentsea-surf';

const backend = new PuppeteerBackend({
  headless: false,
  viewport: { width: 1920, height: 1080 },
  initialUrl: 'https://example.com',
});
```

### Docker Backend

```typescript
import { DockerBackend } from '@lov3kaizen/agentsea-surf';

const backend = new DockerBackend({
  image: 'agentsea/desktop:ubuntu-22.04',
  resolution: { width: 1920, height: 1080, scaleFactor: 1 },
  removeOnDisconnect: true,
});
```

## Tools

All tools can be used independently:

```typescript
import {
  createSurfTools,
  createNativeBackend,
} from '@lov3kaizen/agentsea-surf';

const backend = createNativeBackend();
await backend.connect();

const tools = createSurfTools(backend);

// Use individual tools
await tools.screenshot.execute({});
await tools.click.execute({ x: 100, y: 200 });
await tools.typeText.execute({ text: 'Hello World' });
```

## Security

The sandbox configuration allows you to restrict agent capabilities:

```typescript
const agent = new SurfAgent('session', backend, {
  sandbox: {
    enabled: true,
    maxActionsPerMinute: 60,
    blockedDomains: ['malicious-site.com'],
    blockedCommands: ['rm -rf', 'sudo'],
    blockedPaths: ['/etc', '/root'],
  },
});
```

## API Reference

### SurfAgent

Main agent class for executing computer automation tasks.

**Constructor:**

```typescript
new SurfAgent(
  sessionId: string,
  backend: DesktopBackend,
  config?: Partial<SurfConfig>
)
```

**Methods:**

- `execute(task: string, context?: AgentContext)` - Execute a task
- `executeStream(task: string, context?: AgentContext)` - Execute with streaming
- `stop()` - Stop the current execution
- `getState()` - Get current agent state

### REST API Endpoints

When using NestJS integration:

- `POST /surf/execute` - Execute a task
- `POST /surf/action` - Execute single action
- `POST /surf/screenshot` - Take a screenshot
- `GET /surf/screen` - Get screen state
- `GET /surf/sessions` - List active sessions
- `GET /surf/status` - Get backend status

### WebSocket Events

- `execute` - Start task execution (emits `stream`, `complete`, `error`)
- `action` - Execute single action (emits `actionResult`)
- `screenshot` - Take screenshot (emits `screenshotResult`)
- `stop` - Stop current execution
- `status` - Get backend status

## License

MIT

---
_Source: https://npm.io/package/@lov3kaizen/agentsea-surf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._