Libraries

Official SDKs

Tzafon provides official SDKs for Python and TypeScript with identical functionality and APIs.

Python SDK

uv add tzafon

TypeScript SDK

bun add @tzafon/computer

Installation

Python
TypeScript

uv add tzafon

bun add @tzafon/computer

Environment Variable (Recommended)

export TZAFON_API_KEY=sk_your_api_key_here

from tzafon import Computer

client = Computer()  # Auto-reads from environment

Explicit API Key

from tzafon import Computer

client = Computer(api_key="sk_your_api_key_here")

Basic Usage

Both SDKs follow the same pattern with language-specific conventions.

from tzafon import Computer

client = Computer()
with client.create(kind="browser") as computer:
    computer.navigate("https://example.com")
    computer.click(100, 200)

How Actions Work

Actions execute immediately when called. Each method call sends a request to the computer instance.

from tzafon import Computer

client = Computer()
computer = client.create(kind="browser")
computer.navigate("https://example.com")  # Executes now
computer.click(100, 200)                  # Executes now

API Levels

The SDK provides two levels of API access:

High-Level Wrapper (Recommended for Simple Workflows)

The wrapper provides convenient, language-idiomatic methods for common operations:

# High-level wrapper - clean and simple
computer.navigate("https://example.com")
computer.click(100, 200)
computer.screenshot()

Limitations: The wrapper methods work with single tabs only and don’t expose advanced parameters like tab_id or include_context. Use the wrapper when:

You’re working with a single tab
You want clean, readable code
You don’t need page context or advanced features

Using execute() for Advanced Features

Use execute() when:

You need multi-tab management (tab_id parameter)
You want page context (include_context parameter)
You need low-level actions like key_down, mouse_down

# execute() wrapper method for advanced features
computer.execute({
    "type": "click",
    "x": 100,
    "y": 200,
    "tab_id": "tab_abc123",
    "include_context": True
})

# Or use the direct API with explicit IDs
client.computers.click(
    computer.id,
    x=100,
    y=200,
    tab_id="tab_abc123"
)

For multi-tab workflows and page context, see Multi-Tab Management and Page Context.

Async and Cleanup

Python AsyncComputer

Python

from tzafon import AsyncComputer

async with AsyncComputer() as client:
    computer = await client.computers.create(kind="browser")
    await client.computers.navigate(computer.id, url="https://example.com")
    await client.computers.terminate(computer.id)

TypeScript await using (TS 5.2+)

TypeScript

import Computer from '@tzafon/computer';

const client = new Computer();
await using computer = await client.create({ kind: 'browser' });
await computer.navigate('https://example.com');
// Automatically calls terminate() when scope exits

Client Configuration

from tzafon import Computer

client = Computer(
    api_key="sk_...",
    base_url="https://api.tzafon.ai",
    timeout=120.0,
    max_retries=2,
)

Error Handling

import tzafon
from tzafon import Computer

try:
    client = Computer()
    with client.create(kind="browser") as computer:
        computer.navigate("https://example.com")
except tzafon.RateLimitError:
    print("Rate limit exceeded")
except tzafon.AuthenticationError:
    print("Invalid API key")
except tzafon.APIError as e:
    print(f"API error: {e}")

Feature Parity

Core actions work identically across both SDKs:

Action	Python	TypeScript
Navigate	`navigate(url)`	`navigate(url)`
Click	`click(x, y)`	`click(x, y)`
Type	`type(text)`	`type(text)`
Screenshot	`screenshot()`	`screenshot()`
Double Click	`double_click(x, y)`	`doubleClick(x, y)`
Right Click	`right_click(x, y)`	`rightClick(x, y)`
Drag	`drag(x1, y1, x2, y2)`	`drag(x1, y1, x2, y2)`
Hotkey	`hotkey(*keys)`	`hotkey(keys)`
Scroll	`scroll(dx, dy)`	`scroll(dx, dy)`
HTML	`html()`	`getHTML()`
Debug	`debug(command)`	`debug(command)`
Set Viewport	`set_viewport(w, h)`	`setViewport(w, h)`
Wait	`wait(seconds)`	`wait(seconds)`

Advanced Features

Both SDKs provide wrapper methods for advanced operations:

Feature	Python	TypeScript
Execute Action	`execute({...})`	`execute({...})`
Batch Actions	`batch([...])`	`batch([...])`
Key Down	`execute({"type": "key_down", ...})`	`execute({ type: 'key_down', ...})`
Key Up	`execute({"type": "key_up", ...})`	`execute({ type: 'key_up', ...})`
Mouse Down	`execute({"type": "mouse_down", ...})`	`execute({ type: 'mouse_down', ...})`
Mouse Up	`execute({"type": "mouse_up", ...})`	`execute({ type: 'mouse_up', ...})`
Keep Alive	`keep_alive()`	`keepAlive()`
Retrieve Status	`retrieve()`	`retrieve()`
Stream Events	`stream_events()`	`streamEvents()`
Stream Screencast	`stream_screencast()`	`streamScreencast()`
Tab Management	`execute({"type": "list_tabs"})`	`client.computers.tabs.list(id)`

Tab management in TypeScript uses dedicated client.computers.tabs.* methods. Python uses execute() with tab action types (list_tabs, new_tab, switch_tab, close_tab).

Getting Started

Core Concepts

Examples

Official SDKs

Python SDK

TypeScript SDK

Installation

Environment Variable (Recommended)

Explicit API Key

Basic Usage

How Actions Work

API Levels

High-Level Wrapper (Recommended for Simple Workflows)

Using execute() for Advanced Features

Async and Cleanup

Python AsyncComputer

TypeScript await using (TS 5.2+)

Client Configuration

Error Handling

Feature Parity

Advanced Features

Version Requirements

Python

TypeScript

Next Steps

Computer Instances

Actions

Getting Started

Core Concepts

Examples

​Official SDKs

Python SDK

TypeScript SDK

​Installation

​Environment Variable (Recommended)

​Explicit API Key

​Basic Usage

​How Actions Work

​API Levels

​High-Level Wrapper (Recommended for Simple Workflows)

​Using execute() for Advanced Features

​Async and Cleanup

​Python AsyncComputer

​TypeScript await using (TS 5.2+)

​Client Configuration

​Error Handling

​Feature Parity

​Advanced Features

​Version Requirements

Python

TypeScript

​Next Steps

Computer Instances

Actions

Official SDKs

Installation

Environment Variable (Recommended)

Explicit API Key

Basic Usage

How Actions Work

API Levels

High-Level Wrapper (Recommended for Simple Workflows)

Using execute() for Advanced Features

Async and Cleanup

Python AsyncComputer

TypeScript await using (TS 5.2+)

Client Configuration

Error Handling

Feature Parity

Advanced Features

Version Requirements

Next Steps