Quick Start

Get up and running with Tiny Claw in minutes. Install, configure, and start chatting with your autonomous AI companion.

Quick Start

Get Tiny Claw up and running in just a few minutes. This guide will walk you through installation, setup, and your first interaction with your AI companion.

Tiny Claw uses Ollama Cloud as the default provider with a generous free tier. You’ll need to create a free account to get your API key.

Installation

1. Install Bun

   Tiny Claw is built on Bun for maximum performance. If you don’t have Bun installed:

   curl -fsSL https://bun.sh/install | bash
   

   Verify installation:

   bun --version
   
2. Clone the Repository

   git clone https://github.com/warengonzaga/tinyclaw.git
   cd tinyclaw
   
3. Install Dependencies

   bun install
   

   This installs all required packages for the monorepo, including core packages, plugins, and the web UI.

Setup Wizard

Tiny Claw offers two setup options: CLI wizard (terminal-based) or Web setup (browser-based).

CLI Setup

Run the interactive setup wizard in your terminal:

bun run cli setup

The wizard will guide you through:

1. Security Acknowledgment - Accept GPL-3.0 license and security practices
2. API Key Configuration - Enter your Ollama Cloud API key (free at ollama.com)
3. Soul Seed Selection - Choose or generate a personality seed for your companion
4. Two-Factor Authentication - Set up TOTP for web dashboard access
5. Recovery Credentials - Save your recovery token and backup codes

The setup wizard validates your API key in real-time and provides a QR code for easy TOTP setup with your authenticator app.

Web Setup

Start the web-based setup wizard:

bun run cli setup --web

Then open http://localhost:3000/setup in your browser to complete the onboarding flow.

The web setup server runs in setup-only mode until configuration is complete. The main agent won’t start until you finish the wizard.

Getting Your Ollama Cloud API Key

1. Create an Account

   Go to ollama.com and sign up for a free account.

2. Navigate to API Keys

   Once logged in, go to your account settings → API keys.

3. Generate a Key

   Create a new API key and copy it. You’ll paste this during the setup wizard.

Start Tiny Claw

Once setup is complete, start your AI companion:

 bun start

The agent will:

• Initialize the database and memory systems
• Load your personality configuration (soul seed)
• Start the web UI server
• Begin listening for messages

Open http://localhost:3000 to access the Discord-like web interface.

On first start, Tiny Claw will walk you through any remaining configuration. No manual config files needed - it’s self-configuring!

First Interaction

Once the web UI is open:

1. Log in with your TOTP code from your authenticator app
2. Start chatting in the main channel
3. Watch the agent learn - it remembers context across conversations
4. Check the sidebar to see active sub-agents during delegation tasks

Example Commands

Try these to explore Tiny Claw’s capabilities:

Hello! What can you help me with?

What's your personality like?

Help me organize my project files

Explain how your memory system works

CLI Commands Reference

Tiny Claw provides several CLI commands for managing your instance:

Command	Description
bun run cli setup	Run interactive setup wizard (use --web for browser)
bun start	Start the Tiny Claw agent
bun run cli config	Manage models, providers, and settings
bun run cli seed	Show your Tiny Claw’s soul seed
bun run cli backup	Export or import a .tinyclaw backup archive
bun run cli purge	Wipe all data for fresh install (use --force to include secrets)
bun run cli --version	Show version number
bun run cli --help	Show help message

Development Commands

For development and debugging:

bun dev          # Development mode with hot reload
bun build        # Build all packages
bun test         # Run test suite
bun dev:ui       # Run web UI in development mode

Use the --verbose flag with bun start to enable debug-level logs during development.

What’s Next?

Installation Guide

Detailed installation instructions, prerequisites, and troubleshooting

Plugin Development

Learn how to create custom channels, providers, and tools

Configuration

Advanced configuration options and customization

Memory System

Understand how Tiny Claw learns and remembers

Troubleshooting

Setup wizard fails to validate API key

• Verify your API key is correct and hasn’t expired
• Check your internet connection
• Ensure Ollama Cloud is reachable from your network
• The key is saved even if validation fails - you can re-run bun run cli setup to reconfigure

Web UI won't load at localhost:3000

• Check if port 3000 is already in use: lsof -i :3000
• Set a custom port: PORT=8080 bun start
• Look for error messages in the terminal output
• Try clearing browser cache and reloading

TOTP code verification fails

• Make sure your device’s time is synchronized (TOTP is time-sensitive)
• Double-check you entered the secret correctly in your authenticator app
• Try scanning the QR code again
• Wait for the code to refresh and try a new 6-digit code

Lost recovery credentials

If you lose your recovery token or backup codes:

• You can use bun run cli purge --force to wipe all data and start fresh
• This will delete your entire configuration, memory, and secrets
• You’ll need to run setup again and choose a new soul seed