The Ultimate TinyClaw Setup Guide

Before You Start

5-Minute Prerequisite Checklist

Gather these accounts and credentials first so you don't get blocked midway through setup.

Required

1. A fresh Ubuntu 24.04 DigitalOcean droplet and root SSH access.
2. A local machine with an SSH key pair (for example ~/.ssh/id_ed25519.pub).
3. Accounts for Tailscale, GitHub, and your messaging channel (Telegram/Discord/WhatsApp).
4. AI provider credentials (Anthropic and/or OpenAI) ready for TinyClaw setup.
5. 45 to 60 uninterrupted minutes for first-time configuration and verification.

Phase 01

Server & OS Hardening

Provision a fresh droplet, create a locked-down user, and eliminate password-based access. Everything runs as a non-root user from here on.

1.1

Initial System Prep

SSH into your fresh droplet as root. Update everything and install essentials.

bash — as root

apt update && apt upgrade -y
apt autoremove -y
apt install -y curl git tmux bash ufw fail2ban jq

1.2

Create a Non-Root User

Never run your agent as root. Create a dedicated user with sudo access.

bash — as root

adduser youruser
usermod -aG sudo youruser

1.3

SSH Key Authentication

Copy your public key from your local machine (e.g., ~/.ssh/id_ed25519.pub), then set it up on the server.

bash — as root

mkdir -p /home/youruser/.ssh
chmod 700 /home/youruser/.ssh

# Paste your full public key into this file
nano /home/youruser/.ssh/authorized_keys

chown -R youruser:youruser /home/youruser/.ssh
chmod 600 /home/youruser/.ssh/authorized_keys

1.4

Harden SSH

Disable root login and password authentication. Only key-based access is allowed from this point forward.

/etc/ssh/sshd_config

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
MaxAuthTries 4
LoginGraceTime 30

bash — restart ssh

systemctl restart ssh

⚠ Don't Lock Yourself Out

Before restarting SSH, open a second terminal and verify you can log in with your key as youruser. If key authentication fails, you still have your root session open to fix it.

1.5

Firewall & Fail2Ban

Switch to the youruser user. Set up UFW with deny-all defaults and enable Fail2Ban for brute-force protection.

bash — as youruser

su - youruser

# Firewall — temporarily allow SSH until Tailscale is ready
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw --force enable

# Fail2Ban — auto-ban repeat offenders
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

# Automatic security updates
sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure --priority=low unattended-upgrades
# Answer: Yes

Phase 02

Network & Tailscale

Replace public SSH with Tailscale's encrypted mesh network. After this phase, SSH is accessible only through your Tailscale network — no public exposure.

2.1

Install & Authenticate Tailscale

bash

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Follow the URL in your browser → approve at login.tailscale.com/admin/machines

✓ Enable MagicDNS

Head to login.tailscale.com/admin/dns and enable MagicDNS. This lets you SSH to your droplet by name (e.g., ssh youruser@your-droplet) instead of IP address.

2.2

Lock Down to Tailscale Only

Remove the public SSH rule and restrict all inbound traffic to the Tailscale interface. After this step, your server stops accepting connections from the public internet.

bash

# Remove public SSH — Tailscale only after this
sudo ufw delete allow OpenSSH

# Allow traffic only on Tailscale interface
sudo ufw allow in on tailscale0

# Optional: allow Tailscale UDP for direct peer connections
sudo ufw allow 41641/udp

sudo ufw reload

# Enable Tailscale SSH (identity-based, no keys needed)
sudo tailscale set --ssh

⚠ Keep Your Session Open

Don't close your current SSH session until you've verified you can connect via Tailscale from another terminal. If Tailscale SSH isn't working, you'll need DigitalOcean's console to recover.

Note on Public Ports

You can skip opening 41641/udp if you want a stricter lockdown. Tailscale will still work via relay nodes, with potentially lower direct-connection performance.

Phase 03

Development Tools

Install the toolchain your agent needs to build and ship: Node.js via NVM (Node Version Manager), Yarn, Expo/EAS, and the GitHub CLI.

Minimal setup is preselected. Enable advanced tools only if your project needs them.

bash — install selected tools

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc

# Install & activate Node LTS
nvm install --lts
nvm use --lts
nvm alias default lts/*

# Verify
node -v   # ~v24.x
npm -v

# Add GitHub CLI apt repository
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
  | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

# Install & authenticate
sudo apt update
sudo apt install gh -y
gh auth login

Phase 04

Claude Code & TinyClaw

Install the AI engine and the orchestration layer that turns it into an always-on agent you can message from anywhere.

4.1

Install Claude Code

bash

curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Verify & authenticate
claude --version
claude

4.2

Install TinyClaw

TinyClaw is the orchestration layer. It connects Claude Code to messaging channels (such as Telegram) and manages multi-agent teams.

bash

curl -fsSL https://raw.githubusercontent.com/jlia0/tinyclaw/main/scripts/remote-install.sh | bash

Verify the install. If the command isn't found, open a new shell or run source ~/.bashrc.

bash — verify

tinyclaw --version

Phase 05

Agent Configuration

Run the setup wizard, configure heartbeats, and define specialized agents that can work together as a team.

5.1

Run the Setup Wizard

The interactive wizard walks you through channels, API tokens, workspace path, and heartbeat interval.

bash

tinyclaw start
# Interactive prompts:
#   Channel          → Telegram (recommended)
#   Workspace         → ~/.tinyclaw-workspace
#   Provider          → Anthropic
#   Heartbeat         → 1800 (30 min)
#   Default agent     → coder

What Each Wizard Prompt Means

Channel — How you message your agent. Telegram is recommended (simple bot setup, works on mobile).

Workspace — Where the agent stores files, task lists, and logs.

Provider — Your AI backend. Needs an Anthropic API key (ANTHROPIC_API_KEY env var).

Heartbeat — How often the agent pings to confirm it's alive. 1800 = every 30 min.

Default agent — Receives messages when you don't use an @ prefix.

💡 Cost Tip — Cheap Heartbeats

Use a lightweight model for heartbeat checks instead of Claude. Heartbeats are simple status pings — use a low-cost model instead of spending Anthropic API credits on them.

5.2

Define Your Agent Team

Create specialized agents with distinct roles, then group them into a coordinated team.

bash

# Create primary coder (skip if wizard already created it)
tinyclaw agent add \
  --name coder \
  --provider anthropic \
  --model opus \
  --role "Primary development agent"

# Add a code reviewer
tinyclaw agent add \
  --name reviewer \
  --provider anthropic \
  --model sonnet \
  --role "Review code for bugs, optimize for mobile perf"

# Add a build agent
tinyclaw agent add \
  --name builder \
  --provider anthropic \
  --model opus \
  --role "Handle EAS builds and deployments"

# Form a team with a leader
tinyclaw team add \
  --name mobiledev \
  --agents coder,reviewer,builder \
  --leader coder

Phase 06

Persistence & Uptime

Your agent should survive crashes, reboots, and its own self-improvement attempts. This phase ensures it recovers automatically.

6.1

Auto-Restart Script

A wrapper that ensures TinyClaw is always running inside a tmux session.

~/tinyclaw-restart.sh

#!/bin/bash
SESSION="tinyclaw"
COMMAND="tinyclaw start"

if ! tmux has-session -t "$SESSION" 2>/dev/null; then
    tmux new-session -d -s "$SESSION" "$COMMAND"
else
    if ! tmux list-panes -t "$SESSION" | grep -q "tinyclaw"; then
        tmux send-keys -t "$SESSION" C-c
        sleep 3
        tmux send-keys -t "$SESSION" "$COMMAND" C-m
    fi
fi

tinyclaw status

bash — make it executable & test

chmod +x ~/tinyclaw-restart.sh
~/tinyclaw-restart.sh

6.2

Systemd User Service

~/.config/systemd/user/tinyclaw.service

[Unit]
Description=TinyClaw Always-On Agent
After=network-online.target

[Service]
Type=simple
ExecStart=/home/youruser/tinyclaw-restart.sh
Restart=always
RestartSec=10
Environment="NVM_DIR=/home/youruser/.nvm"
Environment="PATH=/home/youruser/.nvm/versions/node/v24*/bin:/usr/local/bin:/usr/bin:/bin"
WorkingDirectory=/home/youruser
TimeoutStartSec=120

[Install]
WantedBy=default.target

bash — enable & start

mkdir -p ~/.config/systemd/user

systemctl --user daemon-reload
systemctl --user enable tinyclaw.service
systemctl --user start tinyclaw.service
systemctl --user status tinyclaw.service

# Survive reboots even when not logged in
sudo loginctl enable-linger youruser

6.3

Resurrection Script

If your agent self-updates and breaks itself, the following script restores it from the latest git backup. Pair this with periodic git push backups of the workspace.

~/.tinyclaw-workspace/resurrect-tinyclaw.sh

#!/usr/bin/env bash
set -euo pipefail

WORKSPACE="$HOME/.tinyclaw-workspace"
SERVICE="tinyclaw.service"
BACKUP_BRANCH="main"

if [ ! -d "$WORKSPACE/.git" ]; then
  echo "Workspace is not a git repo: $WORKSPACE"
  exit 1
fi

cd "$WORKSPACE"
systemctl --user stop "$SERVICE" || true
tmux kill-session -t tinyclaw 2>/dev/null || true

git fetch origin
git reset --hard "origin/$BACKUP_BRANCH"
git clean -fd

if [ -f package.json ]; then
  npm install --silent
fi

systemctl --user start "$SERVICE"
systemctl --user status "$SERVICE" --no-pager -n 20

bash — install + test the recovery path

chmod +x ~/.tinyclaw-workspace/resurrect-tinyclaw.sh
# Run once while healthy so you know it works before an outage
~/.tinyclaw-workspace/resurrect-tinyclaw.sh

✓ Dead Man's Switch

Message your agent daily. If a full day passes with no response, SSH in and run tinyclaw logs all. The resurrection script and git history ensure you can always roll back to a known-good state.

Phase 07

The Operating System

Your agent is not a chatbot — it is a system. The rules in this phase define how it thinks, works, and recovers from failure. They go into your AGENTS.md file — see the Prompt Templates page for ready-to-use versions.

7.1

Execution Loop

Every meaningful task follows a disciplined cycle. The agent does not make one-shot guesses — every change requires a verified outcome.

The Loop

Build the smallest meaningful change → Test immediately against expected behavior → Log what changed, what passed/failed, and what to do next → Decide to iterate, escalate, or close based on evidence.

7.2

Planning Discipline

Rules

Start in plan mode for any non-trivial request. Define scope, constraints, and a clear "done" condition before implementation. If facts change or a step fails, pause execution and re-plan.

7.3

Task & Knowledge Management

The agent maintains its own workspace files as the source of truth.

~/.tinyclaw-workspace/
  ├── todo.md ← live task list, updated continuously
  ├── progress-log.md ← what changed, what passed/failed
  ├── tasks/
  │   └── lessons.md ← failure → root cause → prevention rule
  └── AGENTS.md ← agent behavior rules (see below)

7.4

Quality Gate

Never mark complete without proof

Every completed task requires passing tests, clean and well-understood logs, and observable correctness. Final check: "Would a staff engineer approve this as production-ready?"

7.5

Safety Rules

⚠ No YOLO System Changes

The agent must never make risky system changes (TinyClaw config, network settings, package installs or updates, source code modifications) without your explicit approval first. It must explain: (1) what it wants to change, (2) why, and (3) what could go wrong. Then wait for your go-ahead. If you're not available — it does not proceed. It is better for the agent to wait than to knock itself offline.

7.6

Escalation Rules

When to Stop & Ask

Escalate immediately for missing credentials, external outages, or ambiguous requirements. After three failed attempts on the same issue, stop and re-plan before continuing.

Phase 08

Daily Operations

Your agent is live. Here's how to interact with it, monitor it, and keep it healthy.

8.1

Quick Reference Commands

bash — daily operations

# Attach to the live agent session
tmux attach -t tinyclaw
# ...or
tinyclaw attach

# Check agent status
tinyclaw status

# View all logs
tinyclaw logs all

# Visualize team activity
tinyclaw team visualize mobiledev

# Update TinyClaw
tinyclaw update

# Check systemd service health
systemctl --user status tinyclaw.service

8.2

Talking to Your Agent

Message your agent through the configured channel (e.g., Telegram). TinyClaw routes messages by agent name. Prefix with @agentname to target a specific agent. Messages without a prefix go to the team leader.

Example Messages

@coder Write an Expo component for a settings screen with Swift interop.

@reviewer Review the latest PR for performance issues.

@builder Trigger an EAS build for iOS production.

8.3

Autonomous Improvement

Configure the agent for continuous autonomous improvement. Add this to your daily standing instructions:

Standing Order

"Every day, iterate on and improve the codebase. Ship one completed improvement daily that enhances existing workflows."

See the Standing Orders templates for copy-paste versions covering code quality, test coverage, dependency health, and more.

✓ The Safety Net

The "No YOLO" rule from Phase 07 ensures autonomous improvement stays safe. The agent can refactor code, write tests, and improve docs on its own — but system-level changes always require your sign-off.

8.4

Smoke Test (Definition of Done)

Setup is complete only when every check in the following list passes.

bash — final verification

# 1) Service is active
systemctl --user status tinyclaw.service --no-pager

# 2) tmux session exists
tmux ls | grep tinyclaw

# 3) TinyClaw is responsive
tinyclaw status

# 4) Channel roundtrip test
# Send "ping" to your bot and confirm a reply

# 5) Reboot survival
sudo reboot
# Reconnect and repeat checks 1-3

Ship Criteria

If any check fails, treat setup as incomplete. Fix the issue, then re-run the full list.

Architecture

What You've Built

┌─────────────────────────────────────────────────┐
│  You (phone / laptop)                            │
│    └── Telegram / Discord / WhatsApp              │
└───────────────────┬─────────────────────────────┘
                    │
          encrypted mesh (Tailscale)
                    │
┌───────────────────▼─────────────────────────────┐
│  $6/mo DigitalOcean Droplet                     │
│  Ubuntu 24.04 · no public SSH · fail2ban          │
│                                                   │
│  ┌─ TinyClaw ──────────────────────────────┐    │
│  │  systemd · tmux · auto-restart          │    │
│  │                                         │    │
│  │  @coder    → Claude Opus (development)  │    │
│  │  @reviewer → Claude Sonnet (review)     │    │
│  │  @builder  → Claude Opus (deployment)   │    │
│  │                                         │    │
│  │  heartbeat → lightweight model (pings)   │    │
│  └─────────────────────────────────────────┘    │
│                                                   │
│  Node v24 · gh · eas-cli · git backups         │
└─────────────────────────────────────────────────┘

The UltimateTinyClaw Setup

Required

Initial System Prep

Create a Non-Root User

SSH Key Authentication

Harden SSH

Firewall & Fail2Ban

Install & Authenticate Tailscale

Lock Down to Tailscale Only

Install Claude Code

Install TinyClaw

Run the Setup Wizard

What Each Wizard Prompt Means

Define Your Agent Team

Auto-Restart Script

Systemd User Service

Resurrection Script

Execution Loop

The Loop

Planning Discipline

Rules

Task & Knowledge Management

Quality Gate

Never mark complete without proof

Safety Rules

Escalation Rules

When to Stop & Ask

Quick Reference Commands

Talking to Your Agent

Example Messages

Autonomous Improvement

Standing Order

Smoke Test (Definition of Done)

The Ultimate
TinyClaw Setup