Quickstart Guide

Tonk follows a simple two-mode workflow:

  1. Workers stream data in - Background services connect to external APIs or your file system and stream data into your local Tonk store
  2. Apps visualise data - Frontend applications provide interfaces to explore and interact with that data

This architecture separates data ingestion from visualisation, making your applications more maintainable and your data more reusable across different interfaces.

Installing Tonk

First, you'll need to install Tonk on your machine:

npm install -g @tonk/cli && tonk hello

This will install the Tonk CLI globally and run the hello command, which sets up the Tonk daemon for synchronising your data.

The Tonk Workflow

Mode 1: Create Workers (Data Ingestion)

Workers are background services that connect to the outside world and stream data into your Tonk store. Start by creating a worker:

tonk create  # choose 'worker' when prompted
cd my-worker

Workers handle tasks like:

  • Syncing data from Google Maps, Gmail, or other APIs
  • Processing scheduled tasks
  • Real-time data streaming
  • API integrations

Example worker structure:

// src/index.ts - Your worker's main logic
app.post('/tonk', async (req, res) => {
  // Connect to external API
  const data = await fetchFromExternalAPI();
  
  // Store in Tonk via keepsync
  await writeDoc('my-collection/data', data);
  
  res.json({ success: true });
});

Mode 2: Create Apps (Data Visualisation)

Once you have data flowing in via workers, create frontend apps to visualise and interact with that data:

tonk create  # choose 'react' when prompted
cd my-app

Apps are React applications that:

  • Connect to your Tonk stores
  • Provide interfaces for your data
  • Enable real-time collaboration
  • Work offline-first

The CLI will scaffold a project with:

  • React, TypeScript, and Tailwind CSS
  • Keepsync for accessing your data stores
  • Development tools

Development Workflow

Start Your Worker

First, get your worker running to begin data ingestion:

cd my-worker
pnpm dev

Register and start the worker:

tonk worker register
tonk worker start my-worker

Start Your App

Then start your frontend app and navigate to http://localhost:3000 in the browser:

cd my-app
pnpm dev

This will:

  1. Start a development server with hot reloading (so changes in the code are instantly reflected)
  2. Connect to your Tonk stores (where workers are streaming data)

Understanding the Data Flow

The magic happens through Tonk Stores - shared data containers that connect workers and apps:

External APIs → Workers → Tonk Stores → Apps → Users
                  ↑                ↓
                  └ Real-time sync ┘

In Workers: Writing Data

Workers stream data into stores using keepsync:

import { writeDoc } from '@tonk/keepsync';

// Worker streams in location data
await writeDoc('locations/favorites', {
  places: googleMapsData,
  lastSync: Date.now()
});

In Apps: Sculpting Data

Apps connect to these stores allowing you to perform sophisticated actions over your data.

import { create } from "zustand";
import { sync } from "@tonk/keepsync";

// App reads and displays the same data
const useLocationStore = create(
  sync(
    (set) => ({
      locations: [],
      // ... your app logic
    }),
    { docId: "locations/favorites" }
  )
);

Key Benefits

  • Separation of concerns: Workers handle data, apps handle logic and rendering
  • Real-time sync: Changes appear instantly across all connected apps
  • Offline-first: Everything works without internet, syncs when reconnected
  • No database complexity: No migrations, caching, or auth headaches
  • Collaborative: Multiple users see updates in real-time

Deployment Options

Tonk provides several ways to deploy your workers and apps:

Local Deployment

Build and serve locally:

# Build your app
pnpm run build

# Push the bundle to Tonk
tonk push

# Start hosting the bundle
tonk start <bundleName>

One-Touch Hosting (Experimental)

For quick deployment to the cloud:

tonk deploy

⚠️ Note: This is experimental and requires an access code. Contact Tonk support for access.

Docker & Production

For production deployments, Tonk includes Docker support and cloud deployment options.

Next Steps

Real-World Examples

Check out these complete examples in the repository:

  • Google Maps Locations Worker - Syncs your saved places from Google Maps
  • My World App - Visualizes location data on an interactive map
  • File Browser App - Browse and manage files with real-time sync

Vibe Coding with Tonk

What is Vibe Coding?

Vibe coding is a novel approach to software development where a person uses natural language to describe tasks to an LLM which generates the code. The person is primarily responsible for guiding the LLM and imparting a vision. Vibe coding is about building momentum, following creative instincts, and evolving a project through rapid iteration and feedback loops.

Essential Tools

Graphical Software

  • Cursor - fork of Visual Studio Code, with deep AI integration
  • Windsurf - another VS Code fork, more streamlined and beginner-friendly

Terminal

  • Claude Code - highly capable and intuitive CLI-based agentic coding tool

Models

  • Claude 3.7 Sonnet or Claude 4 Sonnet recommended for most tasks
  • Claude 4 Opus or OpenAI o3 for complicated reasoning tasks and planning

Core Principles

1. Begin with a plan

Using your favourite vibe coding IDE or chat interface, work out a detailed plan of what you want to achieve with your project. It's best to include features, views, technical details, constraints, and visual preferences. If you're unsure about any specifics, have the LLM go with its best judgement. You can always refine your project later.

Once you're happy with your plan, save it to a markdown file in your project, so the LLM can reference it later. Then, open your agentic editor to your Tonk project and prompt the LLM with the first part of your plan.

2. Retain control

Vibe coding at its best can fully abstract the code from you. It should never abstract intent. LLMs can only implement what you can articulate, so make sure you can reason about what you're asking of it. Vibe coding fails hard and fast when you lose understanding of what the LLM is doing at a high level.

Break tasks into small steps you know how to test. When something goes wrong, specifically articulate what you wanted, what you observed, and what you want to change. If there are errors in the browser, code, or terminal, make sure to pass them on to the LLM.

3. Git as fail-safe

Each time you complete a milestone, commit the changes to git. This allows you to quickly see what changes the LLM has made since the last commit, compare various stages of your project, and try multiple iterations of a feature without risking stable parts of your code.

4. Ask AI for help

If you're not sure what you want or how to get there, be as clear as you can to the LLM and ask for some options without writing any code. Weigh the options then ask it to go through with one. If you want to try multiple, commit your changes to git first. Then, you can change the code as much as you like and revert when necessary.

You can also ask the LLM to explain any part of the code to you. If you feel yourself losing grip of the project's intent, don't be afraid to dig into the code and poke around.

Where Tonk Comes In

Tonk is designed specifically to enable vibe coding workflows. Here's how Tonk supports the vibe coding approach:

Streamlined Tech Stack

Tonk's architecture, tooling, and developer experience are tailored for easy use by LLMs. The entire backend is abstracted, letting the AI focus on what it does best: React frontends. We use Vite, Tailwind, and Zustand, which are favoured by agentic tooling and provide the optimal balance between convenience and extensibility.

Tonk provides sync middleware for Zustand stores so that all state saved to a store is automatically persisted and synced between connected devices around the world.

A backend server is automatically generated so you can query external services from your React app.

Exploratory Development

  • Rapid prototyping - spin up new ideas in minutes, not hours
  • Easy experimentation - try different approaches without fear of breaking things
  • Continuous data - access any all of your data across your apps, synced live
  • Seamless scaling - move from prototype to production without architectural rewrites

What's Achievable with Tonk

Perfect For

  • Real-time applications - chat apps, collaborative tools, live dashboards
  • Exploratory projects - when you're not sure what you're building yet
  • Idiosyncratic expression - for a unique and creative web
  • Learning and experimentation - try new ideas quickly
  • Small to medium applications - full-stack apps with 1-1000 users
  • Hackathons and time-boxed projects - maximum velocity development

Coming Soon

  • Enterprise applications - greater security guarantees and reliability
  • User space - tying users to data
  • Identity, authentication, permissions - gate access and share with peace of mind

Don't Use For

  • Mission-critical systems
  • Performance-critical applications
  • Massive scale

Resources

For the practical: https://github.com/techiediaries/awesome-vibe-coding?tab=readme-ov-file.

For the poetic: https://www.thewayofcode.com/

Keepsync

Keepsync is our local-first sync engine that provides real-time collaboration and local-first data management for Tonk applications. It uses Automerge CRDTs under the hood to enable automatic conflict resolution when multiple users edit the same data, and when working offline.

Documents and Stores

Keepsync supports two main ways to work with data:

  1. Synced Stores: Zustand stores enhanced with real-time synchronisation using the sync middleware
  2. Direct Document Access: File-system-like access to individual documents using path-based addressing

Documents are uniquely identified by a docId and automatically reconcile state between all clients connected to the same server.

Basic Usage

1. Set Up the Sync Engine

Initialise the sync engine in your application entry point (this is automatically included when you create a Tonk app):

// index.tsx
import { configureSyncEngine } from "@tonk/keepsync";
import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";

const wsProtocol = window.location.protocol === "https:" ? "wss:" : "ws:";
const httpProtocol = window.location.protocol === "https:" ? "https://" : "http://";
const wsUrl = `${wsProtocol}//${window.location.host}/sync`;
const wsAdapter = new BrowserWebSocketClientAdapter(wsUrl);
const storage = new IndexedDBStorageAdapter();

configureSyncEngine({
  url: `${httpProtocol}//${window.location.host}`,
  network: [wsAdapter as any],
  storage,
});

2. Create a Synced Store with the Middleware

Use the sync middleware to create stores that automatically synchronise with other clients:

// stores/counterStore.ts
import { create } from "zustand";
import { sync } from "@tonk/keepsync";

interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

export const useCounterStore = create<CounterState>(
  sync(
    // The store implementation
    (set) => ({
      count: 0,

      // Increment the counter
      increment: () => {
        set((state) => ({ count: state.count + 1 }));
      },

      // Decrement the counter
      decrement: () => {
        set((state) => ({ count: Math.max(0, state.count - 1) }));
      },

      // Reset the counter
      reset: () => {
        set({ count: 0 });
      },
    }),
    // Sync configuration
    {
      docId: "counter",
      // Optional: configure initialisation timeout (default: 30000ms)
      initTimeout: 30000,
      // Optional: handle initialisation errors
      onInitError: (error) =>
        console.error("Sync initialisation error:", error),
    }
  )
);

3. Use the Store in React Components

// components/Counter.tsx
import React from "react";
import { useCounterStore } from "../stores/counterStore";

export function Counter() {
  // Use the store hook directly - sync is handled by the middleware
  const { count, increment, decrement, reset } = useCounterStore();

  return (
    <div>
      <h2>Collaborative Counter: {count}</h2>
      <div>
        <button onClick={decrement}>-</button>
        <button onClick={increment}>+</button>
        <button onClick={reset}>Reset</button>
      </div>
      <p>
        <small>
          Open this app in multiple windows to see real-time collaboration in
          action.
        </small>
      </p>
    </div>
  );
}

Direct Document Access

For scenarios where you need more fine-grained control over document access, when working outside of React, or when a Zustand store is too heavyweight, you can work directly with documents using filesystem-like paths.

Reading and Writing Documents

import { readDoc, writeDoc } from "@tonk/keepsync";

// Read a document
const userData = await readDoc<{ name: string; email: string }>('users/john');
console.log(userData); // { name: "John Doe", email: "john@example.com" } or undefined

// Write a document
await writeDoc('users/john', {
  name: "John Doe",
  email: "john@example.com",
  lastLogin: new Date().toISOString()
});

// Update an existing document
const currentData = await readDoc('users/john');
if (currentData) {
  await writeDoc('users/john', {
    ...currentData,
    lastLogin: new Date().toISOString()
  });
}

Listening to Document Changes

You can listen for changes to specific documents without using the full sync middleware:

import { listenToDoc } from "@tonk/keepsync";

// Attach a listener to a document
const removeListener = await listenToDoc('users/john', (doc) => {
  console.log('User document changed:', doc);
  // Update UI or trigger other side effects
});

// Later, when you want to stop listening
removeListener();

File System Operations

Keepsync provides filesystem-like operations for organising your documents:

import { ls, mkDir, rm } from "@tonk/keepsync";

// List contents of a directory
const contents = await ls('users');
console.log(contents); // Returns DocNode with children array

// Create a directory structure
await mkDir('projects/tonk-app/data');

// Remove a document or directory (recursively)
const success = await rm('users/inactive-user');
console.log(success); // true if removed successfully

Advanced Features

Document Types and Structure

Keepsync organises documents in a hierarchical structure similar to a filesystem:

import type { DocNode, DirNode, RefNode } from "@tonk/keepsync";

// DocNode: Represents a document or directory
interface DocNode {
  type: 'doc' | 'dir';
  pointer?: DocumentId;
  name: string;
  timestamps: {
    create: number;
    modified: number;
  };
  children?: RefNode[];
}

// DirNode: Represents a directory
interface DirNode {
  type: 'dir';
  name: string;
  timestamps: {
    create: number;
    modified: number;
  };
  children?: RefNode[];
}

// RefNode: Reference to a document or directory
interface RefNode {
  pointer: DocumentId;
  type: 'doc' | 'dir';
  timestamps: {
    create: number;
    modified: number;
  };
  name: string;
}

Error Handling

import { readDoc, writeDoc } from "@tonk/keepsync";

try {
  const data = await readDoc('some/path');
  if (!data) {
    console.log('Document not found');
  }
} catch (error) {
  console.error('Sync engine not initialised:', error);
}

// Handle sync initialisation errors in stores
const useMyStore = create(
  sync(
    (set) => ({ /* store definition */ }),
    {
      docId: "my-store",
      onInitError: (error) => {
        // Handle initialisation failures
        console.error('Failed to initialise sync:', error);
        // Could show user notification, retry logic, etc.
      }
    }
  )
);

Best Practices

  1. Use meaningful document paths: Organise your data logically using clear, hierarchical paths like users/profiles/john or projects/my-app/settings.

  2. Handle initialisation gracefully: Always provide onInitError callbacks for sync middleware to handle network or initialisation issues.

  3. Choose the right tool: Use synced stores for application state that needs real-time collaboration, and direct document access for more structured data or when you need filesystem-like operations.

  4. Clean up listeners: Always call the cleanup function returned by listenToDoc when components unmount or when listeners are no longer needed.

  5. Path conventions: Use forward slashes (/) for path separators and avoid starting paths with / (they will be normalised automatically).

API Reference

Sync Middleware

  • sync<T>(config: StateCreator<T>, options: SyncOptions): StateCreator<T> - Creates a synced Zustand store

Document Operations

  • readDoc<T>(path: string): Promise<T | undefined> - Read a document
  • writeDoc<T>(path: string, content: T): Promise<void> - Write/update a document
  • listenToDoc<T>(path: string, listener: (doc: T) => void): Promise<() => void> - Listen for document changes

Filesystem Operations

  • ls(path: string): Promise<DocNode | undefined> - List directory contents
  • mkDir(path: string): Promise<DirNode | undefined> - Create directory structure
  • rm(path: string): Promise<boolean> - Remove document or directory

Configuration

  • configureSyncEngine(options: SyncEngineOptions): SyncEngine - Initialise the sync engine
  • getSyncEngine(): SyncEngine | null - Get the current sync engine instance

Tonk Workers

Tonk Workers are background services that extend your Tonk applications with additional functionality. They run as separate processes and integrate seamlessly with the Tonk ecosystem through a standardized API.

Overview

Workers provide specialized functionality like:

  • Data synchronisation with external services
  • Scheduled background tasks
  • API integrations
  • Real-time data processing

Architecture

Workers are standalone Node.js applications that:

  • Run on their own ports
  • Communicate via HTTP/WebSocket
  • Integrate with Tonk's sync system (keepsync)
  • Are managed by the Tonk CLI

Creating a Worker

1. Initialize a Worker

tonk create # choose 'worker' when prompted
cd new-worker

2. Worker Structure

// src/index.ts
import express from 'express';
import cors from 'cors';
import { configureSyncEngine } from './sync.js';

const app = express();
const PORT = process.env.PORT || 5555;

app.use(cors());
app.use(express.json());

// Health check endpoint (required)
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// Main worker endpoint
app.post('/tonk', async (req, res) => {
  try {
    // Your worker logic here
    const result = await processRequest(req.body);
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(PORT, () => {
  console.log(`Worker running on port ${PORT}`);
});

3. Worker Configuration

Create a worker.config.js file:

module.exports = {
  runtime: {
    port: 5555,
    healthCheck: {
      endpoint: "/health",
      method: "GET",
      interval: 30000,
      timeout: 5000,
    },
  },
  process: {
    file: "index.js",
    cwd: "./dist",
    instances: 1,
    autorestart: true,
    env: {
      NODE_ENV: "production",
    },
  },
  schemas: {
    documents: {
      default: {},
    },
  },
};

Managing Workers

Register a Worker

tonk worker register

List Workers

tonk worker ls

Start/Stop Workers

tonk worker start my-worker
tonk worker stop my-worker

Check Worker Status

tonk worker ping my-worker
tonk worker inspect my-worker

View Logs

tonk worker logs my-worker

keepsync Integration

Workers can read and write to Tonk's sync system:

import { configureSyncEngine, readDoc, writeDoc } from './sync.js';

// Configure sync engine
const engine = configureSyncEngine({
  url: SYNC_URL,
  network: [wsAdapter as any as NetworkAdapterInterface],
  storage: new NodeFSStorageAdapter(),
});

// Read data
const data = await readDoc('my-collection/document-id');

// Write data
await writeDoc('my-collection/document-id', {
  timestamp: Date.now(),
  data: processedData,
});

Example: Google Maps Locations Worker

The codebase includes a complete example worker that:

  • Connects to Google Maps API
  • Exports saved locations daily
  • Stores data in keepsync
  • Provides CLI commands for setup

Key features:

  • OAuth 2.0 authentication
  • Scheduled exports (cron-like)

Standard Endpoints

Workers should implement these standard endpoints:

  • GET /health - Health check (required)
  • POST /tonk - Main processing endpoint
  • GET /status - Worker status information
  • Custom endpoints for specific functionality

Best Practices

Error Handling

// Global error handlers
process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  process.exit(1);
});

process.on('unhandledRejection', (reason) => {
  console.error('Unhandled Rejection:', reason);
  process.exit(1);
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('Shutting down gracefully...');
  process.exit(0);
});

Environment Configuration

// Use environment variables for configuration
const config = {
  port: process.env.PORT || 5555,
  syncUrl: process.env.SYNC_URL || 'ws://localhost:7777',
  apiKey: process.env.API_KEY,
};

Logging

// Structured logging
console.log(JSON.stringify({
  timestamp: new Date().toISOString(),
  level: 'info',
  message: 'Worker started',
  port: PORT,
}));

Deployment

Workers are deployed separately from Tonk applications but work great together.

  1. Development: Workers run locally via tonk worker start
  2. Docker: Include workers in your docker-compose.yml

Troubleshooting

Worker Not Starting

# Check worker status
tonk worker inspect my-worker

# View logs
tonk worker logs my-worker

# Check port conflicts
lsof -i :5555

Health Check Failures

Ensure your worker responds to GET /health with:

{"status": "ok"}

Sync Issues

  • Verify SYNC_URL environment variable
  • Check network connectivity to Tonk server
  • Ensure proper keepsync configuration

Next Steps

Deploying Tonk Apps

This guide covers various deployment strategies for Tonk applications, from local containerization to cloud deployment on platforms like AWS EC2.

Overview

Tonk applications can be deployed in several ways:

  1. Local Development: Using tonk -d daemon for development
  2. Docker Containerization: Packaging apps and the Tonk server in containers
  3. One-Touch Hosting: Using tonk deploy for managed hosting (experimental)

Docker Deployment

Tonk provides built-in Docker support for both the Tonk server and individual applications.

Tonk Server

The Tonk server is available as a pre-built Docker image at tonklabs/tonk-server:latest. Pull and run the image with:

docker run -d \
  --name tonk-server \
  -p 7777:7777 \
  -v tonk-data:/data/tonk \
  tonklabs/tonk-server:latest

Tonk Apps

When you create a Tonk app using tonk create, a docker-compose.yml file is automatically included in your project. This file is pre-configured to work with your app.

  1. Build your Tonk app:

    cd my-tonk-app
pnpm run build

  2. Start the containers using the included configuration:

    docker-compose up -d

  3. Access your app:

    • Tonk server: http://localhost:7777
    • Your app: http://localhost:8000

Customizing Your Docker Setup

You can customize the included docker-compose.yml file for your specific needs:

services:
  tonk-server:
    image: tonklabs/tonk-server:latest
    container_name: tonk-server
    volumes:
      - tonk-data:/data/tonk/stores
      - tonk-bundles:/data/tonk/bundles
      - ./dist:/tmp/app-bundle
    ports:
      - "7777:7777"
      - "8000:8000"
    environment:
      - PORT=7777
      - NODE_ENV=production
      - VERBOSE=false           # Disable verbose logging for production
      - SYNC_INTERVAL=30000     # Set sync interval to 30 seconds
    restart: unless-stopped
    # The command section handles app deployment automatically

Environment Configuration

The Tonk server Docker image supports several environment variables:

VariableDefaultDescription
PORT7777Port for the Tonk server
BUNDLES_PATH/data/tonk/bundlesDirectory for storing app bundles
STORES_PATH/data/tonk/storesDirectory for storing data
CONFIG_PATH/data/tonk/configDirectory for configuration files
VERBOSEtrueEnable verbose logging
SYNC_INTERVAL0Sync interval in milliseconds
NODE_ENVproductionNode.js environment

Troubleshooting

Common Issues

  1. Port conflicts: Ensure ports 7777 and 8000 are available
  2. Permission issues: Check file permissions for data directories
  3. Network connectivity: Verify security group settings
  4. Resource limits: Monitor CPU and memory usage

Debugging Commands

# Check container logs
docker logs tonk-server

# Check container status
docker ps

# Check Tonk server health
curl http://localhost:7777/ping

# Check running bundles
tonk ps

One-Touch Hosting (Experimental)

⚠️ EXPERIMENTAL FEATURE ⚠️

The tonk deploy command provides experimental one-touch hosting for Tonk applications. This feature is highly experimental and will change drastically. Expect data loss. You must obtain an access code to use this feature (see below).

Usage

In your Tonk app directory run:

tonk deploy

Options:

  • -n, --name <name>: Name for the deployed app (defaults to package.json name)
  • -r, --region <region>: Region to deploy to (default: ord)
  • -m, --memory <memory>: Memory allocation (e.g., 256mb, 1gb) (default: 1gb)
  • -c, --cpus <cpus>: Number of CPUs (default: 1)
  • --skip-build: Skip the build step
  • --remote: Use remote Docker build

Important Warnings

  • Data Loss: Your deployed applications and data may be lost at any time
  • Breaking Changes: The deployment architecture will change soon
  • No SLA: This is an experimental service with no uptime guarantees
  • Access Required: You must have a valid deploy code from Tonk

How It Works

  1. Builds your Tonk application locally
  2. Creates a compressed bundle of your project
  3. Uploads the bundle to Tonk's hosting service
  4. Returns a public URL for your deployed application

Getting Access

Contact Jack at Tonk (Telegram) to request a deploy code.

Next Steps

Reference

This reference guide provides detailed information about Tonk commands, features, and troubleshooting tips.

Command reference

The Tonk CLI includes the following commands:

tonk hello

Initializes the Tonk daemon, which provides synchronization services for your apps.

Usage: tonk hello [options]

Say hello to start and launch the tonk daemon

Options:
  -h, --help  display help for command

tonk create

Creates a new Tonk application with an interactive setup process.

Usage: tonk create [options]

Create a new tonk application or component

Options:
  -i, --init  initialize in the folder
  -h, --help  display help for command

tonk push

Packages and uploads your application bundle to the Tonk server.

Usage: tonk push [options]

Package and upload a bundle to the Tonk server

Options:
  -u, --url <url>    URL of the Tonk server (default: "http://localhost:7777")
  -n, --name <name>  Name for the bundle (defaults to directory name)
  -d, --dir <dir>    Directory to bundle (defaults to ./dist)
  -s, --start        Start the bundle after upload
  -h, --help         display help for command

tonk ls

Lists available application bundles on the Tonk server.

Usage: tonk ls [options]

List available bundles on the Tonk server

Options:
  -u, --url <url>  URL of the Tonk server (default: "http://localhost:7777")
  -h, --help       display help for command

tonk ps

Shows currently running bundle servers.

Usage: tonk ps [options]

List running bundle servers

Options:
  -u, --url <url>  URL of the Tonk server (default: "http://localhost:7777")
  -h, --help       display help for command

tonk start <bundle-name>

Starts a bundle server for a specific bundle.

Usage: tonk start [options] <bundleName>

Start a bundle server

Arguments:
  bundleName         Name of the bundle to start

Options:
  -u, --url <url>    URL of the Tonk server (default: "http://localhost:7777")
  -p, --port <port>  Port for the bundle server (optional)
  -h, --help         display help for command

tonk kill <server-id>

Stops a running bundle server.

Usage: tonk kill [options] <serverId>

Stop a running bundle server

Arguments:
  serverId         ID of the server to stop

Options:
  -u, --url <url>  URL of the Tonk server (default: "http://localhost:7777")
  -h, --help       display help for command

tonk proxy <bundle-name>

Creates a reverse proxy to access a Tonk bundle using SSH tunnelling with Pinggy service.

Usage: tonk proxy [options] <bundleName>

Create a reverse proxy to access a Tonk bundle

Arguments:
  bundleName         Name of the bundle to proxy

Options:
  -u, --url <url>    URL of the Tonk server (default: "http://localhost:7777")
  -h, --help         display help for command

This command checks if the specified bundle is running, then creates an SSH tunnel using Pinggy to make the bundle accessible via a public URL with QR code for easy mobile access.

tonk worker

Manages worker processes and configurations. The worker command provides comprehensive lifecycle management for Tonk workers.

Usage: tonk worker [command] [options]

Manage Tonk workers

Commands:
  inspect <nameOrId>     Inspect a specific worker
  ls                     List all registered workers
  rm <nameOrId>          Remove a registered worker
  ping <nameOrId>        Ping a worker to check its status
  start <nameOrId>       Start a worker
  stop <nameOrId>        Stop a worker
  logs <nameOrId>        View logs for a worker
  register [dir]         Register a worker with Tonk
  install <package>      Install and start a worker from npm
  init                   Initialize a new worker configuration file

Options:
  -h, --help             display help for command

Worker Subcommands

tonk worker inspect <nameOrId> Inspect a specific worker and optionally perform actions on it.

Options:
  -s, --start            Start the worker
  -S, --stop             Stop the worker
  -c, --config <path>    Path to worker configuration file
  -p, --ping             Ping the worker to check its status
  -h, --help             display help for command

tonk worker logs <nameOrId> View logs for a worker using PM2 integration.

Options:
  -f, --follow           Follow log output
  -l, --lines <n>        Number of lines to show (default: "100")
  -e, --error            Show only error logs
  -o, --out              Show only standard output logs
  -h, --help             display help for command

tonk worker register [dir] Register a worker with Tonk from a directory containing worker configuration.

Arguments:
  dir                    Path to worker directory (defaults to current directory)

Options:
  -n, --name <n>         Name of the worker
  -e, --endpoint <endpoint>  Endpoint URL of the worker
  -p, --port <port>      Port number for the worker
  -d, --description <description>  Description of the worker
  -h, --help             display help for command

tonk worker install <package> Install and start a worker directly from an npm package.

Arguments:
  package                NPM package name

Options:
  -p, --port <port>      Specify a port for the worker (default: auto-detect)
  -n, --name <n>         Custom name for the worker (default: npm package name)
  -h, --help             display help for command

tonk worker init Initialize a new worker configuration file in the current or specified directory.

Options:
  -d, --dir <directory>  Directory to create the configuration file in (default: ".")
  -n, --name <n>         Name of the worker
  -p, --port <port>      Port number for the worker (default: "5555")
  -h, --help             display help for command

FAQ

Pre-requisites to install

  1. You'll need Node.js and npm installed to run the Tonk installation command.

How do I get it working on Windows?

Tonk should work on Windows without any extra configuration.

  1. Install Tonk via npm:
npm install -g @tonk/cli
  1. Start Tonk:
tonk hello