User Guide

What You Need

1. A Claude Pro subscription — sign up at claude.ai if you don't have one. Set this up first — Claude can then help you with every step that follows, including installing Taskmaster itself.
2. Taskmaster running on one of:
   • A Raspberry Pi (shipped to you pre-installed), or
   • A Mac (installed from a package file)

Installation

Option A: Raspberry Pi (pre-installed)

If you received a Taskmaster device:

1. Connect the power cable (USB-C) to the device
2. Plug it into a wall socket or power strip
3. Wait about 2 minutes for it to start up

Getting on the same network

The Pi has no WiFi configured out of the box. Until it is, your computer and the Pi must both be connected via ethernet to the same router — or connected directly to each other.

Is your computer connected via ethernet? Use Option 1. Is your computer on WiFi? Skip straight to Option 2.

Option 1 — Plug the Pi into your router (ethernet computers only)

Only works if your computer is also connected to the router via ethernet, not WiFi.

Connect the Pi to your router with an ethernet cable. Open a browser on your computer and go to:

http://taskmaster.local:18789

Option 2 — Connect the Pi directly to your computer (WiFi computers)

If your computer is on WiFi, plug the Pi directly into your computer with an ethernet cable and enable Internet Sharing. This puts the Pi and your computer on the same network, and gives the Pi internet access through your computer's WiFi connection.

You'll need: an ethernet cable, and if your computer has no ethernet port, a USB-to-ethernet adapter.

Mac

1. Open System Settings → General → Sharing
2. Click Internet Sharing in the list — don't turn it on yet
3. Set “Share your connection from” to Wi-Fi
4. In the “To computers using” list, tick your Ethernet port (or USB Ethernet adapter)
5. Now turn on the Internet Sharing toggle at the top of the row
6. Click Start if macOS asks for confirmation
7. Plug the ethernet cable between the Pi and your Mac — allow 15–30 seconds for the Pi to get an IP address

Open a browser on your Mac and go to http://taskmaster.local:18789.

Windows 11

1. Open Settings → Network & Internet → Advanced network settings → More network adapter options
2. Right-click your Wi-Fi adapter and choose Properties
3. Go to the Sharing tab and tick “Allow other network users to connect through this computer's Internet connection”
4. In the dropdown, select your Ethernet adapter
5. Click OK
6. Plug the ethernet cable between the Pi and your PC — allow 15–30 seconds for the Pi to get an IP address

Open a browser on your PC and go to http://taskmaster.local:18789.

Windows 10

1. Open Settings → Network & Internet → Change adapter options
2. Right-click your Wi-Fi adapter and choose Properties
3. Go to the Sharing tab and tick “Allow other network users to connect through this computer's Internet connection”
4. In the dropdown, select your Ethernet adapter
5. Click OK
6. Plug the ethernet cable between the Pi and your PC — allow 15–30 seconds for the Pi to get an IP address

Open a browser on your PC and go to http://taskmaster.local:18789.

Option B: Install on a Raspberry Pi (or any Linux OS) yourself

You'll need a Raspberry Pi running Raspberry Pi OS with an internet connection (ethernet or WiFi), plus a monitor, keyboard, and mouse connected to the Pi.

1. Open Terminal from the desktop taskbar (or press Ctrl+Alt+T)
2. Run:

   curl -fsSL https://taskmaster.bot/install.sh | sudo bash

3. Wait for it to finish (a few minutes — it installs Node.js if needed)
4. Open a browser on any device on the same Wi-Fi network and go to: http://taskmaster.local:18789/setup

You can also access the setup page from any other device on the same network at http://taskmaster.local:18789/setup.

Option C: Install on a Mac

Open Terminal (search for “Terminal” in Spotlight) and run:

curl -fsSL https://taskmaster.bot/install.sh | sudo bash

This installs Node.js (if needed), Taskmaster, and sets up the background service. Once finished, open your browser and go to: http://taskmaster.local:18789/setup

curl -fsSL https://taskmaster.bot/install.sh | sudo bash -s -- --port 19000

Option D: Install from a package file

If you received a .tgz package file (for offline install or when the install script isn't available):

1. Install Node.js (version 22 or later) from nodejs.org if you don't have it
2. Open a terminal and run:

   npm install -g ~/Downloads/rubytech-taskmaster-2026.2.14.tgz
   taskmaster provision

3. Open your browser and go to: http://taskmaster.local:18789/setup

Activating Your License

When you first open the setup page, you'll see a Device ID and a field for your license key.

The license activation screen — paste your license key and tap Activate

1. The setup page shows your Device ID — a code unique to your device
2. Send this Device ID along with your order number to our WhatsApp support
3. We'll send you back a license key tied to your device
4. Paste the key into the setup page and tap Activate
5. Wait for the green checkmark — the wizard will move on automatically

Your license is tied to this device. If you need to move it to a different device, contact support for a new key.

Premium Setup

If you ordered a Premium Setup, your device has already been configured for you — installation, license activation, Claude account, agent profiles, skills, knowledge base, and branding are all in place. You can skip straight to using your assistant. Here's what you need to know:

Accessing Your Control Panel

Your device hostname may have been customised during setup. If so, we will have communicated the address directly (e.g. http://yourbusiness.local:18789). The default http://taskmaster.local:18789 will not work if the hostname was changed.

Change Your PINs Immediately

Both your admin PIN and account PIN have been set to 123456 during setup. You must change these the first time you log in:

1. Open the control panel and enter 123456 when prompted
2. Go to Setup and scroll to the Security section
3. Change your admin PIN to something only you know (4–6 digits)
4. Change your account PIN to something different from your admin PIN

What's Already Done

Depending on your package, some or all of the following will already be configured:

• Claude account connected and ready
• Agent profiles tailored to your business
• Skills loaded with industry-specific capabilities
• Knowledge base pre-loaded with your business information
• Branding (business name, colours, logo) applied
• WhatsApp linked (if included in your package)

What You May Still Need to Do

• Link WhatsApp — if not included in your package, follow the “Link WhatsApp” step in the Setting Up section below
• Add admin phone numbers — go to the Admins page to add any phone numbers that should have admin access
• Review your knowledge base — go to Files and check what's been loaded; add or correct anything

Once your PINs are changed, you're ready to start chatting with your assistant.

Setting Up

Once your license is activated, you'll land on the setup dashboard where you can configure each part of your assistant at your own pace.

1. Connect to Claude (recommended)

Your assistant needs an AI provider to work. The easiest option is connecting your Claude Pro account:

1. On the setup dashboard, find the Claude Pro card and tap the action button
2. In the modal that opens, tap “Connect to Claude”
3. Sign in with your Claude Pro account in the browser window that opens
4. Copy the code shown and paste it into the code field
5. Tap Submit — once connected, the Claude Pro card turns green and shows In use

2. Link WhatsApp (optional)

WhatsApp is only needed if you want your assistant to handle customer messages or if you want to chat with it via WhatsApp. If you only plan to use the Chat page or iMessage (Mac), you can skip this step.

1. The setup page shows a QR code
2. On your phone: WhatsApp → Settings → Linked Devices → Link a Device
3. Scan the QR code on screen
4. Wait for all status lights to turn green

Scan the QR code with your phone to link WhatsApp

When all status lights turn green, your setup is complete:

The Status Dashboard — all services showing green means you're ready

Control Panel

After setup, you'll see a navigation bar at the top of the screen linking to all your pages:

The Setup page with status dashboard — all services showing green

Data Safety Alert

A shield icon appears in the navigation bar whenever your assistant writes a file to the public/ or shared/ folders. These are the folders visible to other assistants or customers, so you'll want to check that the right information ended up in the right place.

Tap the shield to see a list of recent writes — each entry shows the file name, which folder it went to, and when it happened. Once you've reviewed them, tap Mark All Reviewed to clear the list. The shield disappears until the next write.

This check runs automatically — the badge updates on its own without needing to refresh the page.

Secure Connection (HTTPS)

Taskmaster automatically enables HTTPS when accessed from other devices on your network. This is required for features like voice recording in the browser, which need a secure connection.

The first time you access the control panel, your browser will show a security warning about the certificate. This is normal — Taskmaster generates its own certificate, which your browser doesn't recognise yet.

To proceed:

• Chrome / Edge: Click “Advanced” then “Proceed to…”
• Safari: Click “Show Details” then “visit this website”, confirm in the dialog
• Firefox: Click “Advanced” then “Accept the Risk and Continue”

You only need to do this once per browser. After that, the control panel loads normally. All bookmarks and http:// links still work — they automatically redirect to the secure version.

sudo security add-trusted-cert -d -r trustAsRoot -k /Library/Keychains/System.keychain ~/.taskmaster/tls/gateway-cert.pem

Security & PINs

Your dashboard is protected by two layers of security:

1. Your network is the main barrier. The control panel only runs on your local network and your Tailscale network (if Remote Access is enabled). Nobody outside these networks can reach it. If you enable Internet Access, only the public chat is exposed — the control panel stays private.
2. PINs prevent casual access within your network. The PIN stops other people on the same WiFi — family, employees, guests — from opening accounts that aren't theirs.

If you enter the wrong PIN 5 times in a row, you'll be locked out for 5 minutes before you can try again.

The login screen — enter your PIN to access the dashboard

First Time

The very first time you open the dashboard, you'll be asked to set a PIN (4-6 digits). This is your admin PIN — it gives you full access to everything. You'll need it every time you open the dashboard.

First visit — set a PIN to protect your device

Logging In

When you return, a login screen asks for your PIN. The dropdown groups Admins (the main admin account and any named admin users) separately from Accounts (per-workspace account PINs). Select your login and enter your PIN. The main admin account gives access to all accounts. Once logged in, your username is shown next to the lock icon in the top navigation bar.

Named Admin Users

If multiple people need admin access to the dashboard, you can create named admin users — each with their own login, their own web chat history, and their own profile that the assistant builds over time.

1. Go to the Admins page and log in with the admin PIN
2. Click the Internal tab
3. Enter a username (e.g. alice) and a 4-6 digit PIN, then click Add Login User

Each named admin logs in by selecting their username from the login screen and entering their PIN. They have full access — the same as the main admin — but their web chat is a separate session. The assistant will introduce itself on first contact and learn who they are naturally.

To remove a named admin or reset their PIN, use the buttons next to their name on the Internal tab.

Named admins can change their own PIN at any time: on the login screen, select their username and click Change PIN.

Account PINs

If you share your device with other people (e.g. a business partner who manages a different account), each account can have its own PIN:

1. Go to the Setup page
2. Select the account from the dropdown at the top
3. Look for the Account PIN row in the status panel
4. Click Set PIN (or Change if one is already set)
5. Enter a new 4-6 digit PIN and confirm it

When someone logs in with an account PIN, they only see their own account — they can't access other accounts or change device settings.

Changing Your Admin PIN

1. On the login screen, make sure admin is selected in the dropdown
2. Click Change PIN below the unlock button
3. Enter your current PIN, then your new PIN twice
4. Click Change PIN

Locking

Click the lock icon in the top navigation bar to log out. Your session lasts 24 hours — after that you'll need to enter your PIN again.

Forgotten PIN

If you forget your PIN, you'll need to edit the configuration file on the device. Contact support via WhatsApp for assistance.

Two Assistants, One Number

Taskmaster runs two assistants on the same channel (WhatsApp, Telegram, or iMessage), each with a different job:

The Public Assistant handles messages from your customers. It can reply to messages and look up information you've taught it, but it cannot access your files, run commands, or see private notes. If a customer tries to trick it into doing something it shouldn't, it simply can't — those capabilities don't exist for it.

The Admin Assistant is your personal assistant. When you use the Chat page (or message yourself on WhatsApp), you're talking to this one. It has full access — it can manage files, browse the web, run scheduled tasks, and read everything.

How does Taskmaster know which is which?

There are two concepts to understand:

• Paired WhatsApp number — the WhatsApp account linked to your Pi during setup. This is the number your customers message. When you send yourself a message on this WhatsApp account (self-chat), it goes to the admin assistant.
• Admin phones — additional phone numbers (WhatsApp) or user IDs (Telegram) that get admin access. Useful if you have a separate personal phone, or if a business partner needs admin access from their own number.

By default, messages from anyone not registered as an admin go to the public assistant. You can add admins on the Admins page — WhatsApp admins by phone number, Telegram admins by numeric user ID.

The Admins page — manage which phone numbers get admin access

Using Your Assistant

Once setup is complete, open the Chat page and say hello. Your assistant will introduce itself and ask a few questions about you and your business — this is how it learns who you are and what you do. A simple “hi” is all it takes to get started.

After that first conversation:

• Customers message your WhatsApp or Telegram → The public assistant responds automatically
• You open the Chat page → You're talking to your admin assistant directly

The Chat page — talk to your admin assistant directly

The Chat page is the preferred way to talk to your admin assistant. It's always available in the navigation bar, works from any device on your network, and doesn't depend on WhatsApp or iMessage being connected. You can also reach your admin assistant by messaging yourself on WhatsApp or iMessage — all three channels connect to the same assistant with the same knowledge and memory.

Your assistant learns your business from the files in its workspace. The fastest way to get started is to upload your existing documents — price lists, service descriptions, terms and conditions, FAQs — via the Files page or by dragging them into the Chat page. Your assistant will read and remember everything. You can also teach it through conversation — just chat naturally about your business, pricing, and how you work, and it will save what it learns.

Sending Files

You can send files to your assistant by dragging and dropping them onto the chat area. Supported types on the Chat page are images, PDFs, and text documents (.md, .txt, .csv, and similar). Files appear as chips below the message box — you can remove them before sending by clicking the X. You can also add a message along with the file to explain what you'd like done with it.

Via WhatsApp you can also send voice notes and videos — these are automatically transcribed or analysed before your assistant sees them.

Sending Messages While the Assistant is Working

If your assistant is busy thinking, you can still type and send more messages. They appear immediately in the chat as normal messages and are delivered to your assistant in order once it finishes its current task.

Suggestion Chips

After each response, a suggested follow-up appears as a clickable chip below the conversation. Tap it to send the suggestion, or type your own message — the chip disappears as soon as you start a new message. When you open a fresh chat session, a starter suggestion helps you begin the conversation.

Model and Thinking Level

Below the message box you'll see two dropdown selectors:

• Model — Choose which AI model your assistant uses. Opus is the most capable (best for complex tasks), Sonnet is fast and capable (good all-round), and Haiku is the fastest (great for quick questions).
• Thinking — Controls how deeply the assistant reasons before responding. “Off” is fastest. “Low” through “High” give increasingly thorough reasoning at the cost of speed.

Changes take effect immediately for the next message. You can also use the /model and /think chat commands for the same thing.

Starting a New Session

If a conversation has gone off-track or you want a clean slate, tap the New button in the top-right corner of the Chat page. This resets the assistant's context — it forgets the current conversation but keeps its configuration, memory, and skills. The old transcript is archived. This is the same as the /new chat command.

What Your Admin Assistant Can Do

Your admin assistant has a wide range of capabilities beyond basic conversation. Here's what it can help you with.

Messaging & Communication

Your assistant can send messages, images, and reactions on your behalf — and relay messages you may have missed — all via the public agent.

Try asking:

• “Send Sarah a message saying I'll be 20 minutes late”
• “What messages did I miss today?”
• “React to that last message with a thumbs up”

Memory & Knowledge

Your assistant can search, read, and update your business knowledge. It has full file access within your account workspace — it can create, read, update, and organise files.

The Files page — browse, upload, and manage your workspace files

The Files page shows a status indicator next to the Re-index button — a green light means the index is up to date, red means files have changed since the last index. The count shows how many files and chunks are indexed. If the light is red or search results seem stale, click Re-index to rebuild.

Try asking:

• “What's our pricing for a full bathroom refit?”
• “Save a note that Mrs. Jones prefers morning appointments”
• “What do we know about the customer on +44 7700 900123?”
• “List what's in memory/users”

Web Search

Your assistant can search the web and read web pages to find information for you. This requires an API key for a search provider (see API Keys below).

Try asking:

• “Search for the current price of 15mm copper pipe”
• “What are the opening hours for Travis Perkins in Bromley?”
• “Read this page and summarise it: https://example.com/article”

Weather

Your assistant can check the weather for any location — current conditions, forecasts, humidity, wind, and more. No API key is needed.

Try asking:

• “What's the weather like in London?”
• “Will it rain tomorrow in Manchester?”
• “What's the forecast for this week?”

Images & Documents

Your assistant can analyse photos you send it and read common document formats.

Try asking:

• “What's wrong with the pipe in this photo?”
• “Read the attached invoice and tell me the total”
• “Summarise the key points from this PDF”

Image Generation

Your assistant can generate images from text descriptions using Google AI models. Ask for any kind of image — product photos, illustrations, logos, social media graphics — and it will guide you through style and model choices, then generate the image directly in the chat.

Image generation requires a Google AI API key (see API Keys below). Generated images are saved to your workspace and displayed inline in the chat.

Try asking:

• “Generate a product photo of a coffee mug on a white background”
• “Create a watercolour illustration of a sunset over the ocean”
• “Design a minimalist logo concept for a landscaping business”
• “Make a social media graphic for a summer sale, 1:1 square format”

Voice Notes & Video

When someone sends a voice note, image, or video, your assistant processes it automatically before responding — no extra steps needed.

Recording voice notes in the Control Panel: When the text input is empty, a microphone button appears next to the send button. You can use it two ways:

• Tap the mic to start recording — a timer, trash button, and send button appear. Tap send when done, or trash to discard.
• Hold the mic to record — release to send, or slide your finger left to cancel.

Voice notes are transcribed and an audio player appears in the chat history so you can replay them.

Contact Records

Your assistant can look up and update verified contact records that you manage on the Contacts page.

The Contacts page — manage verified contact data

Try asking:

• “Look up John Smith's account”
• “Mark the Johnson job as paid”
• “What's the status of the Henderson quote?”

Scheduling & Automation

Your assistant can manage recurring tasks, reminders, and automated routines. You can view and manage these on the Advanced page under the Events tab.

Try asking:

• “Remind me to chase the Henderson quote on Friday”
• “Set up a daily briefing at 7am every weekday”
• “Create a weekly reminder to check stock levels every Monday”

Proactive Outreach

Your assistant doesn't just respond to incoming messages — it reaches out on your behalf to win work, chase payments, and keep customers engaged.

Your assistant learns your customers, their service history, and your pricing through normal conversations. It then uses scheduled events (visible under Events on the Advanced page) to trigger outreach at the right time. You don't need to configure anything manually — the assistant sets up follow-ups as part of its normal workflow.

Daily Strategic Review

Taskmaster ships with a pre-configured Daily Strategic Review that analyses your recent conversations, audits your business materials, and suggests improvements. It runs as a scheduled event but is paused by default — you choose when to enable it.

To enable:

1. Open the Control Panel
2. Go to Advanced → Events
3. Find Daily Strategic Review and enable it

Once enabled, the review runs daily at 7:00 AM (your device's timezone). Results appear in the web chat, and are also sent via WhatsApp if you have an admin phone number connected.

You can edit the schedule, change the time, or disable it at any time from the Events tab.

Conversations & Sessions

Your assistant has full access to conversation history across all channels — WhatsApp, webchat, iMessage, and group chats. It can find specific messages, review entire conversations, and give you an overview of all activity.

Try asking:

• “Who messaged today?” — lists all conversations with recent activity
• “What did Sarah ask about yesterday?” — reviews a specific contact's history
• “Find any messages that mention boiler” — searches across conversations
• “Show me all WhatsApp messages from today” — filters by channel
• “What happened between 9am and 10am?” — filters by time range
• “Show me all customer messages from today” — aggregates across all conversations
• “Send a follow-up to the customer who asked about the boiler”

Admin Management

Your assistant can manage who has admin access — the same as using the Admins page, but via chat.

Try asking:

• “Add +44 7700 900456 as an admin”
• “Who are my current admins?”
• “Remove the old number ending in 789 from admins”

System Administration

Your assistant can check and manage many system settings directly through chat — the same things you'd normally check in the Setup page on the control panel. Think of it as a shortcut: instead of opening the control panel and navigating to the right setting, just ask.

Try asking:

• “How's the system doing?”
• “What's my usage this month?”
• “Is WhatsApp connected?”
• “Switch WhatsApp to a cheaper model”
• “Change the accent colour to blue”
• “Set opening hours to Mon-Fri 9am to 5pm”
• “Are we currently open?”
• “Enable public chat”
• “Show me the recent logs”

Web Browsing

Your assistant can open and interact with websites in a built-in browser — filling in forms, clicking buttons, and navigating pages. You can watch what it's doing on the Browser page in real time, and take over if it needs help (for example, to complete a CAPTCHA or log in to a site).

Try asking:

• “Help me get a free Tavily API key”
• “Go to the Travis Perkins website and find the price of 15mm copper pipe”
• “Log into my supplier portal and check my order status”

Business Idea Validation

Thinking about a new product, service, or direction for your business? Your assistant can walk you through the process of validating the idea before you invest time and money — from initial concept through customer discovery and assumption testing to a clear product brief.

Your assistant guides you through each phase conversationally — you don't need to know any frameworks or jargon. Just describe your idea and it will ask the right questions.

Try asking:

• “I have an idea for a new service — can you help me think it through?”
• “Help me validate whether this product idea is worth pursuing”
• “I want to write a product brief for a new offering”

How It Works

Understanding what happens behind the scenes helps you get the most from your assistant — and keep your API costs under control.

Sessions & Delegation

Every conversation starts a session. When you send a message, the main assistant reads it, decides what to do, and replies. For simple exchanges — a greeting, a quick answer, a short discussion — the main assistant handles everything directly.

When a task requires real work — looking something up, reading a document, searching the web, updating a contact — the main assistant delegates to a specialist sub-agent. The sub-agent runs in the background, completes the task, and reports back. You see the result as a normal reply.

This delegation happens automatically. You don't need to do anything differently — just send your message and the assistant figures out the best way to handle it.

Why Sessions Matter for Cost

Every time the assistant responds, it re-reads the entire session history to maintain context. This means longer sessions cost more per message — the AI provider charges for all the tokens it reads, not just the new ones. Here's what a single exchange typically costs:

The assistant keeps the last 10 user turns of history per session. Older messages are still searchable via memory, but they don't count against the session context. This keeps costs predictable while preserving recall.

Managing Sessions

You can view and manage all active sessions in the Control Panel → Advanced → Sessions tab. Each session shows its channel, AI model, context usage (as a percentage of the model's context window), and last activity time. From there you can:

• Reset a session — clears the conversation context but keeps the session's configuration. Good for when a conversation has gone off-track.
• Delete a session — removes it entirely. It recreates automatically when the next message arrives.

Watch the Context column — if a session is above 50%, it's consuming significant tokens per message. Resetting it brings the cost back down.

Tools & Skills

Tools are the actions your assistant can take: sending messages, searching contacts, reading files, browsing the web, generating images, and more. Different sub-agents have access to different sets of tools depending on what they need.

Skills are specialist knowledge modules that your assistant loads on demand. When a task matches a skill — setting up an API key, managing events, generating a QR code — the assistant reads the skill's instructions and follows a proven process. Skills ensure consistency: the same task is handled the same way every time.

You can see which skills are available in the Control Panel → Skills section. New skills can be added over time without changing the core assistant.

Message Costs

Every message uses AI tokens, which cost money. The amount depends on what the assistant needs to do:

API Keys

Your assistant uses AI services behind the scenes. Claude Pro is the only requirement — everything else is optional and adds extra capabilities.

Connecting to Claude

From the setup dashboard, tap the Claude Pro card to open the authentication modal. You have three options:

1. Sign in with Claude (recommended): Tap “Connect to Claude”, sign in with your Claude account, and paste the code shown
2. Import refresh token: If you already have Claude connected on another device, copy the refresh token from that device and paste it here — no need to re-authenticate with Anthropic
3. API key (advanced): Skip the Claude modal and enter an Anthropic API key directly in the Anthropic API key card on the setup dashboard

Optional API Keys

These unlock additional capabilities. All are optional — your assistant works without them. The Setup page shows the recommended keys prominently, with additional keys available under “Additional keys”.

Managing Keys

1. Go to the Setup page
2. Click on the API Keys row in the status dashboard
3. Enter a key next to any provider and click Save
4. To remove a key, click Remove next to it

The API Keys modal on the Setup page — enter your keys here

Recommended Free Keys

To get the most out of your assistant at no extra cost, we recommend signing up for two free services: Tavily (web search) and Google AI (voice notes and video). Both are free and take a couple of minutes each.

Getting a Tavily Key (Web Search)

1. Go to app.tavily.com
2. Click “Continue with Google” (easiest — no CAPTCHA) or sign up with your email
3. If using Google, select your Google account and grant permission
4. You'll land on the Tavily dashboard — your API key is shown in the API Keys table
5. If the key is hidden, click the eye icon to reveal it
6. Copy the key (it starts with tvly-)
7. Go to your Taskmaster Setup page, click the API Keys row, find Tavily, paste the key, and click Save

You get 1,000 free search credits per month — more than enough for daily business use.

Tavily signup — click 'Continue with Google' for the easiest path

Your Tavily API key appears on the dashboard after signup

Getting a Google AI Key (Voice Notes & Video)

1. Go to aistudio.google.com and sign in with your Google account
2. Click API keys in the left sidebar (or go directly to aistudio.google.com/api-keys)
3. If you already have a key listed, click the key name to view it. If not, click “Create API key”
4. Copy the key (it starts with AIza)
5. Go to your Taskmaster Setup page, click the API Keys row, find Google, paste the key, and click Save

The free tier works for low-volume use (a handful of voice notes or images per day). For higher volumes, you'll need to enable billing in your Google Cloud account — see Google AI pricing for details.

Google AI Studio — your API keys dashboard

Click a key name to see details, then copy it

Your Files

The Files page shows your full workspace — everything your assistant knows and how it's configured. The top-level folders are:

Inside memory/, files are organised by who can see them:

All files are markdown (.md) — plain text with simple formatting.

Uploading and Managing Files

Click any folder in the tree to set it as your working directory. The folder highlights with a left border to show it's selected. The Upload and New Folder buttons show where files will go — for example, "Upload to memory/public".

• Upload — Click the Upload button or drag .md files onto a folder in the tree
• New Folder — Creates a new folder inside the current directory (useful for adding skill packs or organising memory)
• Delete — Select a file and click Delete. The button changes to "Confirm delete?" — click again within 3 seconds to confirm. Empty folders show a small × on hover to remove them
• Move — Drag any file onto a different folder to move it there
• Multi-select — Hold Ctrl (or Cmd on Mac) and click multiple files, then use Download to save them all

When you add or change a file, your assistant picks it up automatically — no restart needed.

After a fresh install or upgrade, the embedding model downloads automatically (~330 MB). During the download, a full-screen overlay blocks all navigation with a "Downloading embedding model" message — this is a one-time download and typically takes a few minutes. Memory search is unavailable until the download completes.

When your assistant writes to public/ or shared/, a shield icon appears in the navigation bar so you can review what was written (see Data Safety Alert above).

Searching Memory

The Files page includes a memory search bar that lets you test what your assistant finds when it searches its knowledge base.

1. Type a query in the Search memory box and press Enter (or click Search)
2. Results show the file path, relevance score (as a percentage), matching line numbers, and a snippet of the matched text
3. Click any result to open the file preview
4. Use the agent selector dropdown next to the search bar to switch between agents (e.g., public vs admin) — this lets you verify what each assistant can see
5. Click Clear to return to the normal file tree view

This is useful for diagnosing search issues — if your assistant can't find something in conversation, test the same query here to see what comes back.

Status Dashboard

The setup page shows a Status Dashboard with status indicators for each service (shown above after completing setup):

Each service has a refresh button (circular arrow icon) you can tap to reconnect or restart. Tap the small (i) button next to any service to see detailed status information.

Refresh vs. Re-pair Buttons

The status dashboard has two different refresh mechanisms — use the right one to avoid creating unnecessary QR codes:

Refresh Status button (top of dashboard): Checks all services and refreshes their connection status. Use when WhatsApp shows yellow (linked but disconnected), or any service seems stuck. Does NOT create a new QR code — just refreshes the existing connection.

Circular arrow next to each service: Resets that specific service and generates a new QR code (for WhatsApp). Use when you need to completely re-pair WhatsApp from scratch. Creates a new QR code — you'll need to scan it again.

WhatsApp Settings

When WhatsApp is connected, you'll see a small gear icon next to the WhatsApp label. Tap it to open the Public Agent Settings panel, which has three options:

• Enabled — When ticked, your assistant replies to messages from customers (anyone who isn't you). When unticked, only you can talk to the assistant.
• Model — Choose which AI model handles customer messages. You can pick Opus (most capable), Sonnet (balanced), or Haiku (fastest and cheapest). This only affects the public assistant.
• Thinking — Controls how deeply the public assistant reasons before responding to customers. “Off” is fastest. “Low” through “High” give increasingly thorough reasoning at the cost of speed.

Public Agent Settings — control how your assistant responds to customers

Agent Settings

The Agents row on the Setup page opens the Agent Settings panel — the central place to configure how each assistant behaves.

• Public — Model — Choose which AI model handles customer messages (Opus, Sonnet, Haiku).
• Public — Thinking — How deeply the public assistant reasons before responding. “Off” is fastest. “Low” through “High” give increasingly thorough reasoning at the cost of speed.
• Admin — Model — Choose which AI model you chat with as the business owner.
• Admin — Thinking — How deeply your admin assistant reasons. Same scale as above.
• Memory Search — Provider — Which engine searches your assistant's memory. “Local” runs on-device. “OpenAI” and “Gemini” use cloud embeddings (requires the corresponding API key).
• Memory Search — Fallback — Backup provider if the primary is unavailable.

Changes take effect immediately for the next message — no restart needed.

Branding

Each account can have its own branding — a logo and colour scheme that appears on the control panel and on public chat pages (both the full page and the embeddable widget).

What you can customise

How to set up branding

1. Go to the Setup page
2. Find the Branding row in the status dashboard
3. Click Edit — a modal opens with your branding options
4. Upload a logo — click Upload and select an image (PNG, JPEG, SVG, or WebP, max 2 MB). The logo appears in the navigation header and on public chat pages.
5. Choose your accent colour — click the colour picker, or type a hex code (e.g. #7C8C72) directly into the text field and press Enter
6. Choose your background tint — click the colour picker or type a hex code to add a colour wash across page backgrounds, cards, chat bubbles, and input fields (optional)
7. Close the modal with the × button — changes are applied immediately

To clear an individual colour without resetting everything, click the Clear button next to that colour.

To see what each setting does, click the (i) button on the Branding row.

Per-account branding

Branding is set per account. If you have multiple accounts, switch to each account using the dropdown at the top of the page and set up branding for each one separately. When you switch accounts, the control panel immediately updates to show that account's colours and logo.

Resetting to defaults

To remove all custom branding and return to the default colours, open the Branding modal and click Reset to defaults. To remove just one colour, click Clear next to it. To remove just the logo, click Remove next to the logo preview.

Where branding appears

• Control panel — accent colour and background tint update immediately across all pages
• Public chat page — visitors see your logo, accent colour, and background tint
• Chat widget — the embedded widget on your website uses your accent colour for the chat button and background tint for the overlay

Advanced

The Advanced page has five tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.

The Advanced page — Events tab showing scheduled tasks and automations

Opening Hours

The Opening Hours tab lets you control when your public assistant responds to customers, based on a weekly schedule.

To set up a schedule:

1. Go to the Advanced page and select the Opening Hours tab
2. Tick Enable opening hours
3. Choose how the schedule works using the Agent responds selector:
   • During hours — the assistant replies within the times you set, and goes silent outside them. Use this for a standard business hours setup.
   • Outside hours — the assistant replies outside the times you set, and goes silent within them. Use this for after-hours or evening cover.
4. Set the weekly schedule — for each day, enter the relevant time window (e.g., 08:00–17:00), or tick Closed / All day to mark a day with no time window
5. Optionally add closed dates for specific days when the assistant should always be silent (e.g., bank holidays) — these override the schedule regardless of mode
6. Tap Save

Changes take effect on the next incoming message — no restart needed. Times are in your local timezone, detected automatically when you save.

What happens when the assistant is silent:

• Customer messages on WhatsApp stay as “delivered” (grey ticks) — read receipts are suppressed so customers don't see “read” with no reply
• Messages are stored in the conversation history so the assistant picks up context when it resumes
• If you reply manually via WhatsApp, the assistant is aware of your reply and won't contradict it when it resumes

You can also ask your admin assistant to check or change these settings in chat using the opening_hours command.

Events

This is where you can see and manage everything your assistant does on a schedule — reminders, daily briefings, recurring tasks. Your assistant creates these when you ask it to (“remind me every Monday” or “send me a briefing at 7am”), and they appear here as cards.

Each event card shows its name, schedule, and whether it's on or off. You can:

• Tap a card to see full details and recent activity
• Pause or resume an event using the pause/play icon
• Run now — trigger an event immediately
• Delete an event using the trash icon
• Create a new event — tap “New Event” to open the form

Skills

Skills are specialised abilities your assistant has — handling customer enquiries, creating quotes, checking the weather, and more. The Skills tab shows every skill that is installed, whether it's active, and if anything is missing (such as an API key the skill needs).

Preloaded vs User labels. Each skill is labelled Preloaded (built-in and always available) or User (created by you or your assistant).

Filtering. Use the All, Preloaded, and User buttons at the top of the list to filter which skills are shown.

Viewing skill details. Tap any skill to open its detail view. From here you can read the skill's instructions and browse its reference files using the tabs at the top of the detail panel.

Editing a skill. While viewing a skill's detail, click Edit to open the editor. If you are viewing a reference tab when you click Edit, the editor opens directly on that reference file. The editor has tabs for the main SKILL.md file and each reference file.

Enable, disable, and delete. User skills can be enabled or disabled with the toggle, or deleted entirely. Preloaded skills cannot be disabled or deleted.

Drafts workflow:

• Ask your assistant to create a skill — it walks you through the process and saves a draft when you're happy
• Open Drafts in the Skills tab to see pending drafts
• From the drafts list you can Edit (review and modify), Install (activate the skill), or Delete the draft
• Editing a draft and saving keeps it in drafts until you explicitly install it. Editing an already-installed skill and saving updates it immediately.
• The draft editor has tabs for the main SKILL.md file and any reference files, just like the installed-skill editor

Sessions

The Sessions tab shows every active conversation session across all channels — WhatsApp DMs, group chats, Telegram conversations, public chat visitors, and the admin chat. Each row shows:

• Channel — where the conversation is happening (WhatsApp, Telegram, Web Chat, Discord, iMessage, System, etc.)
• Type — Direct (1-to-1), Group, or Global
• Model — which AI model the session is using
• Context — how much of the AI's context window is used, shown as a percentage with token counts (e.g. “24% (48k / 200k)”)
• Last active — when the session last had activity

If the session belongs to a known contact, their name appears alongside the session identifier.

Filtering. Use the dropdowns at the top to filter by type (All, Direct, Group, Global) and by channel (WhatsApp, Telegram, Web Chat, etc.). The channel filter only appears when sessions span multiple channels. The count shows how many sessions match your current filters.

Actions:

• Reset — starts a fresh AI context for the session. The assistant forgets the current conversation but keeps its configuration (model, thinking level, etc.). The old transcript is archived. Use this when a conversation has gone off-track or needs a clean slate.
• Delete — removes the session entry entirely and archives its transcript. The session will be recreated automatically the next time a message arrives on that channel.

Both actions require a two-tap confirmation — the first tap arms the action, the second confirms it. If you don't confirm within a few seconds, the action disarms automatically.

Session settings. Tap the gear icon on any session row to expand an inline settings panel. From here you can change the AI model and thinking level for that specific session — without affecting other sessions or resetting the conversation. Choose “Default” to clear the override and fall back to the agent's configured default. If a session has any overrides active, a Reset to defaults button appears to clear them all at once.

Logs

The Logs tab has two views, selectable with the toggle at the top:

Session Logs show the actual conversations your assistant is having — messages from customers, the assistant's responses, tool calls it makes, and any errors. You can filter by:

• Type — show only certain kinds of entries (messages, tool calls, thinking, errors)
• Agent — show only entries from a specific agent (e.g., public or admin)
• Search — free-text search across all entries

System Logs show the internal machinery of the gateway — connections, heartbeats, startup messages. This is mainly useful for troubleshooting when something isn't working. Tap Filters to expand the filter chips and select which log levels to show (info, warning, error, etc.). You can also export logs to share with support. System Logs are only available when logged in as admin — account-PIN users see the Session Logs tab only, because system logs contain information from all accounts on the device.

Both views support auto-follow (available in the Filters panel — keeps the view scrolled to the latest entries) and export to download a log file. Filter chips are collapsed by default to keep the log view uncluttered.

WiFi (Raspberry Pi)

If your Pi is connected by Ethernet cable, you can switch to WiFi directly from the Control Panel — no monitor or keyboard needed.

1. Go to the Setup page
2. Find the WiFi row in the status dashboard (only appears on Raspberry Pi)
3. Tap Edit — a modal opens with WiFi management controls
4. Tap Scan inside the modal — a list of nearby WiFi networks appears, sorted by signal strength
5. Tap the network you want to connect to
6. If the network is password-protected, enter the password and tap Connect (or press Enter)
7. The WiFi row updates to show the connected network name, signal strength, and IP address

Signal bars next to each network name show the signal strength — more lit bars means a stronger signal.

Auto-reconnect: Once connected, your Pi remembers the WiFi network and password. If the connection drops (e.g. router reboot, temporary signal loss), the Pi automatically reconnects without any action needed. The WiFi row shows “Saved: (network name)” when a saved network exists but the connection is temporarily down.

Reconnecting: If WiFi was manually disconnected and you want to reconnect to the saved network, tap Reconnect inside the WiFi modal — no need to re-enter the password.

Disconnecting: Tap Disconnect inside the modal to intentionally drop the current WiFi connection. This prevents auto-reconnect until you tap Reconnect or connect to a new network.

Forgetting a network: Tap Forget inside the modal to remove the saved WiFi password entirely. After forgetting, you'll need to scan and enter the password again to reconnect.

Changing Network Settings

You can change the port and hostname directly from the Setup page — no terminal access needed.

• Port — The number at the end of your control panel URL (e.g., http://taskmaster.local:18789)
• mDNS hostname — The friendly name before .local (e.g., taskmaster in taskmaster.local)

What is the port and why would I change it?

The port is like an apartment number for your Taskmaster server. The default is 18789.

When to change it:

• Another device on your network is already using port 18789
• Your router or firewall blocks that port
• You're running multiple Taskmaster instances and need them on different ports

What happens when you change it: Your control panel URL changes. If you set the port to 19000, you'll access Taskmaster at http://taskmaster.local:19000.

What is the mDNS hostname and why would I change it?

The mDNS hostname is the friendly name you use to access your device on your local network. The default is taskmaster, so your control panel is at taskmaster.local.

When to change it:

• You're running multiple Taskmaster instances on the same network (they'll conflict if they all use taskmaster.local)
• You want custom branding (e.g., dave.local, assistant.local, plumbing-helper.local)

What happens when you change it: Your control panel URL changes. If you set the hostname to dave, you'll access Taskmaster at http://dave.local:18789.

How to change port and hostname

1. Go to the Setup page
2. Find the Network row in the status dashboard — it shows your current hostname and port
3. Tap Edit — a modal opens with two fields: Hostname and Port
4. Change whichever values you need (hostname: letters, digits, and hyphens only, 1–63 characters; port: 1024–65535)
5. Tap Save
6. The gateway restarts automatically and your browser redirects to the new URL

Fallback: CLI method

If you can't reach the Control Panel (e.g. the gateway is down), you can make the same changes from the terminal.

Changing the port:

taskmaster config set gateway.port 19000
taskmaster daemon install --force

Changing the hostname (Linux / Raspberry Pi):

sudo hostnamectl set-hostname dave
sudo sed -i "s/127\.0\.1\.1.*/127.0.1.1\tdave/" /etc/hosts
sudo systemctl restart avahi-daemon

rm -rf ~/.config/chromium/Singleton*

Changing the hostname (macOS):

sudo scutil --set LocalHostName dave

After either method, access the control panel at the new URL (e.g. http://dave.local:19000).

Flushing DNS Cache on Other Devices

After a hostname change, the device you're browsing from (your phone, laptop, etc.) may have cached the old name. If the control panel doesn't load from another device, flush the DNS cache:

After flushing, open your browser and navigate to the new URL (e.g. http://dave.local:19000). If you still can't connect, try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or open a new private/incognito window to rule out browser caching.

Still Can't Connect?

If the control panel still doesn't load from another device:

1. Use the IP address directly — on the device, run hostname -I (Linux/Pi) or check System Preferences > Network (Mac) to get its IP address, then open http://192.168.1.XXX:18789 (use your IP and port) from the other device. If this works, the problem is mDNS resolution, not the gateway.
2. Check you're on the same network — mDNS only works between devices on the same WiFi/LAN. It won't work across VLANs or guest networks.
3. Contact support with: what you changed (port/hostname), the output of hostname, and taskmaster daemon status.

Hostname changed to taskmaster-2.local (or similar)

If your control panel URL suddenly stops working and the hostname has a -2 (or -3) suffix, the Pi detected a name conflict on the network and renamed itself.

When this happens: If you unplug the Ethernet cable while the Pi is already running on WiFi, the Pi briefly had two network connections active at the same time. Its hostname detection saw its own name coming from the Ethernet side and treated it as a conflict, adding a -2 suffix.

Fix:

1. Power the Pi off completely (not just restart — fully power off)
2. Wait at least 2 minutes (this lets the mDNS name cache clear on all devices on the network)
3. Power the Pi back on
4. Access the control panel using your normal URL

To avoid this in future: Connect via WiFi first, then remove the Ethernet cable — don't unplug Ethernet while the Pi is running with both cables connected.

Static IP Address

You don't need to assign a static IP address — Taskmaster uses a .local hostname that resolves automatically via mDNS, even if the IP changes after a reboot or DHCP renewal. You'll always find your control panel at the same .local address.

That said, if your IT team prefers to pin devices to static IPs (common on managed business networks), they can do so via DHCP reservation on your router. They'll need the device's MAC address:

1. SSH into the Pi (see Enabling SSH below)
2. Run:

   ip link show

3. Look for the link/ether line under the active interface (eth0 for wired, wlan0 for WiFi)
4. Give that MAC address to your IT team to create a DHCP reservation

This is entirely optional and is a network preference, not a Taskmaster requirement.

Troubleshooting

Start here: ask your assistant

Before digging into the Control Panel or exporting logs, ask your assistant. It has direct access to the system and session logs and can read them, identify patterns, and explain what's wrong in plain language — far faster than manual inspection.

Try asking:

• “Can you review the logs and tell me if anything looks wrong?”
• “Is the system healthy?”
• “Are there any errors or warnings I should know about?”

Your assistant will scan both system logs and session logs, triage any issues by severity, and tell you what happened, why, and what to do. This is the quickest first step for any problem you can't immediately explain.

Daily Log Review — if you'd like this to happen automatically every day, go to Advanced → Events in the Control Panel, find the Daily Log Review event, and enable it. Your assistant will run a health check each morning and send you a report.

If the assistant surfaces an issue it can't resolve, it will advise you to forward the report to Taskmaster support on WhatsApp. That report contains everything the support team needs — no separate log export required.

Can't access the Control Panel?

If you can't load the Control Panel in your browser:

1. Same network? — Make sure your device is on the same WiFi or LAN as Taskmaster
2. Check the URL — go to http://taskmaster.local:18789 and port 18789. Both http and https work — HTTP automatically redirects to HTTPS
3. Certificate warning? — On first access, your browser shows a security warning. Click through it (see Secure Connection above for steps). This is a one-time step
4. Wait for boot — after powering on the device, it takes 2–3 minutes for everything to start. If you just plugged it in, give it a moment
5. Try a different browser — some browsers have trouble with .local addresses. Try Chrome or Safari
6. Use the IP address — if .local doesn't resolve, find the device's IP address on your router and go to http://<ip-address>:18789 instead

Messages not getting through?

1. Go to http://taskmaster.local:18789/setup
2. Check which indicator is not green
3. Tap the circular arrow button next to the problem service

WhatsApp shows yellow (Linked but not connected)?

WhatsApp is linked but the connection dropped. This often resolves itself. If not:

1. Go to http://taskmaster.local:18789/setup
2. Tap “Refresh Status” — it may reconnect automatically
3. If still yellow after a minute, tap the circular arrow next to WhatsApp to relink

WhatsApp messages failing with “No sessions” or “Bad MAC” errors?

The WhatsApp connection for one of your accounts has lost sync. This can happen after a power cut, an unclean shutdown, or when WhatsApp rotates its security keys. Other accounts on the same device are not affected — only the account with the problem stops sending or receiving.

Try a restart first:

1. Go to http://taskmaster.local:18789/setup
2. Tap the circular arrow next to Gateway to restart it
3. Wait 30 seconds — if WhatsApp reconnects and turns green, you're done

On a Raspberry Pi, you can also just unplug the device, wait 10 seconds, and plug it back in.

If restarting doesn't fix it, re-pair WhatsApp from scratch (see below).

WhatsApp needs re-pairing (linking fails, status red, or out of sync)?

If WhatsApp linking keeps failing, the status stays red despite showing “linked” on your phone, or the connection data is corrupted — you need to start fresh:

1. Go to http://taskmaster.local:18789/setup
2. Tap “Reset WhatsApp” (red button)
3. On your phone: WhatsApp → Settings → Linked Devices
4. Remove “macOS” (Taskmaster's connection) from the list if present
5. Scan the new QR code

Claude connection expired?

1. Go to http://taskmaster.local:18789/setup
2. Tap the Claude Pro card on the dashboard to open the authentication modal
3. Tap Reconnect, sign in and enter the code, or import a refresh token from another device
4. If you want to remove the connection entirely, tap Disconnect instead

Gateway not responding?

1. Go to http://taskmaster.local:18789/setup
2. Tap the circular arrow next to Gateway to restart it
3. Wait 30 seconds for it to come back online
4. If still not working, try unplugging your Taskmaster device, waiting 10 seconds, and plugging it back in

Assistant not replying during an AI service outage?

Occasionally, AI providers like Claude experience temporary outages or slowdowns. When this happens, Taskmaster automatically tries to get a reply from a different AI provider instead.

• If you have backup providers configured (e.g., a Google AI key or OpenAI key added on the Setup page), your assistant switches to those automatically. You don't need to do anything — replies keep coming, just from a different AI model behind the scenes.
• If only one provider is configured, messages sent during the outage won't get a reply. The customer's message is received but the assistant can't respond until the service recovers.
• You'll be notified. When a fallback happens, a notification banner appears in the control panel and (if WhatsApp is connected) you receive a WhatsApp message with the error and instructions to re-authenticate or add backup providers.
• Messages are not queued. If a message arrives during an outage and all providers are down, it won't be retried automatically. The customer (or you) will need to send the message again once the service is back.
• Your conversation history is safe. An outage doesn't corrupt or lose any previous conversations. Once the service recovers, everything picks up where it left off.

What you can do to stay protected:

1. Add backup API keys — Go to the Setup page, tap API Keys, and add keys for Google AI and/or OpenAI alongside your Claude connection. These act as automatic backups.
2. Check your logs — If replies are failing, open Advanced → Logs → Session Logs and filter by “errors” to see what's happening.
3. Wait it out — Most AI service outages resolve within minutes to hours. Your assistant will automatically use the primary provider again once it's back.

Sharing logs with support

If you're still stuck after trying the steps above, export your logs and send them to Taskmaster support on WhatsApp. Logs give the support team exact error messages and timing, which speeds up diagnosis.

1. Go to the Advanced tab in the Control Panel and tap Logs
2. Select the view that covers your issue:
   • Session Logs — for problems with replies, conversations, or tool errors
   • System Logs — for connection, startup, or gateway issues
3. Tap Filters to open the filter panel
4. Tap Export — the browser downloads a log file to your device
5. Send the file to Taskmaster support on WhatsApp

Tip: If you're not sure which view to use, export both — Session Logs and System Logs — and send them together.

“sudo: unable to resolve host taskmaster” warning?

This harmless warning appears when the Pi's hostname isn't listed in /etc/hosts. Every sudo command still works — it's just a cosmetic message. To fix it, open a terminal on the Pi and run:

sudo sh -c 'echo "127.0.1.1	taskmaster" >> /etc/hosts'

Replace taskmaster with your actual hostname if you changed it (e.g., taskmaster-19000 for a custom port). The warning disappears immediately.

Multiple Accounts

You can run more than one account on the same Taskmaster device. Each account gets its own assistant identity, customer knowledge, and WhatsApp number — completely separate from your other accounts.

Adding a Second Account

1. Go to the Setup page
2. Scroll down to Your Accounts
3. Tap “+ Add Account”
4. Enter a name for the account (e.g., “My Plumbing Company”)
5. Tap Create — the system will set up the workspace and restart
6. When the QR code appears, scan it with the WhatsApp number for this account
7. Your new account is live

How It Works

• Each account has its own public assistant (handles customers) and admin assistant (handles you)
• Each account has its own files and memory — customers of one account don't see data from another
• Each account connects to its own WhatsApp number
• You manage all accounts from the same Setup page

Renaming Your Account

The name you see in the account selector and dashboard can be changed at any time:

1. Go to the Setup page
2. Click the pencil icon next to your account name in the dashboard header
3. Type the new name (e.g., “Joe's Coffee Shop”)
4. Press Enter to save, or Escape to cancel

The rename takes effect immediately across all pages with no restart needed.

Removing an Account

1. Go to the Setup page
2. Find the account under Your Accounts
3. Tap the X button next to it
4. Confirm removal

This removes the assistant and routing but keeps the account files on disk.

iMessage (Mac only)

If you're running Taskmaster on a Mac, you can also talk to your assistant by messaging yourself in the Messages app — no WhatsApp needed.

What it does

When you send a message to yourself in Messages.app, your assistant replies in the same conversation. It works just like the admin chat on WhatsApp, but through iMessage.

One account at a time

Unlike WhatsApp — where each account has its own phone number — iMessage shares a single Messages app across all accounts. Only one account can use iMessage at a time.

• The account that's selected when you enable iMessage gets it
• Other accounts will show “Not connected — iMessage is connected to {Account Name}”
• To move iMessage to a different account, select that account and tap the refresh button

Self-chat only

iMessage is for self-chat only — messages from other people are not processed. It works like your private admin channel, separate from WhatsApp which handles customer messages.

How to enable

1. Go to the Setup page
2. Select the account you want to connect (if you have more than one)
3. Find the iMessage row in the status dashboard
4. Tap the circular arrow button
5. A confirmation message appears — tap Enable
6. The gateway will restart automatically
7. When the iMessage row turns green, you're ready

Before you start

iMessage support requires two things on your Mac before running Taskmaster setup:

1. Xcode or Xcode Command Line Tools (up to date)
   • If you don't have Xcode at all — open Terminal and run: xcode-select --install
   • If you have Xcode from the App Store but it's outdated — open the App Store, find Xcode, and click Update
   • If you don't want to update Xcode — run: sudo xcode-select --switch /Library/Developer/CommandLineTools
2. Homebrew — if you don't already have it, open Terminal and run:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Requirements

• Mac only — iMessage is not available on Raspberry Pi
• Xcode Command Line Tools or up-to-date Xcode (see “Before you start” above)
• Homebrew (see “Before you start” above)
• Full Disk Access for the Node.js binary (see “Grant Full Disk Access” below)
• When macOS asks to control Messages.app, click OK (first time only)

Grant Full Disk Access

Taskmaster's iMessage helper needs permission to read the Messages database. There are three steps:

Step 1: Sign the binaries

sudo codesign --force --sign - $(realpath $(which imsg))
sudo codesign --force --sign - $(realpath $(which node))

Step 2: Grant Terminal Full Disk Access

1. Open System Settings > Privacy & Security > Full Disk Access
2. Click the + button
3. Navigate to Applications > Utilities > Terminal and click Open
4. Make sure the toggle next to Terminal is on
5. Quit Terminal completely (Cmd+Q) and reopen it

You can verify it worked by running imsg chats --limit 5 in Terminal — if you see a list of chats, Full Disk Access is working.

Step 3: Grant the Node.js binary Full Disk Access

1. Open Terminal and run: realpath $(which node)
2. Open a Finder window and press Cmd+Shift+G
3. Paste the folder path and press Enter
4. Open System Settings > Privacy & Security > Full Disk Access
5. Drag the node file from Finder onto the list
6. Make sure the toggle is on

iMessage Troubleshooting

“permission denied” errors in logs?

Full Disk Access has not been granted to imsg. Follow the “Grant Full Disk Access” steps above.

“Xcode too outdated” or “imsg installation failed”?

1. Update Xcode — open the App Store and update Xcode
2. Switch to Command Line Tools — run: sudo xcode-select --switch /Library/Developer/CommandLineTools
3. Install Command Line Tools — run: xcode-select --install

After any of the above, re-run: pnpm taskmaster daemon install --force

iMessage row stays grey after enabling?

Open Terminal and type imsg --version. If it says “command not found”, re-run: pnpm taskmaster daemon install --force. Check that Full Disk Access is granted to imsg (see above), then restart the gateway.

Messages not getting through?

Open Terminal and run imsg watch — you should see messages appear when you text yourself. If nothing appears, Full Disk Access is not set correctly for imsg.

Multiple Apple IDs?

If you have more than one Apple ID linked to your iMessage account, only the first registered account supports self-chat — regardless of which account you choose to “start new conversations from” in Messages settings.

Telegram

You can connect one or more Telegram bots to any account so your assistant responds to Telegram messages.

Connecting Telegram

1. Open the control panel and select the account you want to connect
2. Find Telegram in the dashboard and click the + button
3. Create a bot with @BotFather in Telegram — send /newbot, choose a name and username
4. Paste the bot token and click Verify Token
5. Choose whether to enable Admin routing (see below)
6. Click Save & Connect

Each account can have its own Telegram bots — switch accounts using the selector at the top of the page.

Admin Bot vs Public Bot

Each Telegram bot has an Admin routing toggle:

• Admin bot (toggle ON) — Only users listed as Telegram admins can message this bot. Everyone else is silently ignored. Messages route to the admin agent. No DM policy applies.
• Public bot (toggle OFF) — DM policy applies to everyone equally, including admins. Messages route to the public agent.

A common setup is two bots: one admin bot for the business owner, one public bot for customers.

Telegram Admin Management

Admin user IDs control who can talk to admin bots. You need your numeric Telegram user ID — not your username, since usernames can be changed or claimed by someone else.

Finding your Telegram user ID:

1. Open Telegram and search for @userinfobot
2. Start the chat and send /start
3. The bot replies with your numeric ID (e.g., 1311221864)

Adding admins from the UI:

1. Go to the Admins page
2. Select the Telegram tab
3. Enter the numeric user ID and click Add

From the admin agent:

• “Add 1311221864 as a Telegram admin”
• “Remove 1311221864 from Telegram admins”
• “List Telegram admins”

Multiple Telegram Bots

You can connect multiple Telegram bots to one account — for example, an admin bot for private use and a public bot for customers.

1. Go to Setup → Telegram section
2. Click the + button to add a bot
3. Enter the token from @BotFather and click Verify Token
4. Choose whether to enable Admin routing
5. Click Save & Connect

Public bots have independent DM policy settings:

• Respond to everyone — open access, anyone can chat
• Require approval — new users receive a pairing code; admin must approve
• Whitelist only — only listed user IDs can message
• Disabled — bot ignores all DMs

Admin bots have no DM policy — they only accept messages from users with admin bindings.

To disconnect, click the gear icon next to Telegram, expand the bot, and click Disconnect.

Using Your Pi as a Desktop

Your Raspberry Pi is a full computer — you can connect a monitor, keyboard, and mouse and use it directly.

What you need

• A micro-HDMI cable (or micro-HDMI to HDMI adapter) to connect a monitor or TV
• A USB keyboard and USB mouse

What you can do

Browse your files — Open the file manager from the desktop and navigate to the home folder. You'll see your workspace files — the same ones that appear on the Files page.

Access the dashboard locally — Open the web browser and go to http://localhost:18789 to use the full Taskmaster dashboard directly on the Pi.

General desktop use — The Pi runs a full desktop environment. You can browse the web, view documents, and use any standard Linux applications.

Finding Your Pi's IP Address

You need the IP address to connect from another device on your network (e.g., SSH, or if taskmaster.local isn't working).

From the Pi itself (monitor + keyboard):

1. Open Terminal (taskbar or Ctrl+Alt+T)
2. Run:

   hostname -I

3. The first number shown is your IP address (e.g., 192.168.1.42)

From your Mac or PC (without a monitor on the Pi):

• Before install: Run ping -c 1 raspberrypi.local — a fresh Pi advertises this hostname by default
• After install (default port): Run ping -c 1 taskmaster.local — the install changes the hostname to “taskmaster”
• After install (custom port): Run ping -c 1 taskmaster-19000.local — when using --port 19000, the hostname includes the port
• Router: Check your router's admin page (usually 192.168.1.1) — look for a device called “taskmaster” or “raspberrypi” in the connected devices list

Once you have the IP, you can access the setup page at http://<your-pi-ip>:18789/setup or connect via SSH with ssh admin@<your-pi-ip>.

Enabling SSH on Your Pi

SSH lets you connect to your Pi from another computer on the same network — no monitor or keyboard needed. Raspberry Pi OS has SSH turned off by default. To enable it:

Option 1: From the Pi desktop (monitor + keyboard)

1. Click the Raspberry Pi menu (top-left corner of the desktop)
2. Go to Preferences → Raspberry Pi Configuration
3. Click the Interfaces tab
4. Set SSH to Enabled
5. Click OK

Option 2: From the Pi terminal

1. Open Terminal (taskbar or Ctrl+Alt+T)
2. Run:

sudo systemctl enable --now ssh

Option 3: Before first boot (headless setup — no monitor needed)

If you're setting up the Pi using Raspberry Pi Imager:

1. In Raspberry Pi Imager, click the gear icon (or press Ctrl+Shift+X) before writing the SD card
2. Check Enable SSH and set a password
3. Write the SD card and boot the Pi

Or, if the SD card is already written:

1. Insert the SD card into your computer
2. Create an empty file called ssh (no extension) in the boot partition
3. Eject the card and boot the Pi

After enabling SSH, connect from another computer:

ssh [email protected]

Enter the password when prompted. The default password is password for pre-installed devices, or whatever you chose during Raspberry Pi OS setup.

Public-Facing Messages (DM Policy)

By default, your assistant responds to messages from anyone who contacts your WhatsApp number. You can turn this off so that only admin phones get through.

Toggling Public Messages

1. Go to the Setup page
2. In the status dashboard, find the Public facing toggle (under your WhatsApp connection)
3. Toggle it on to accept messages from anyone, or off to block unknown senders

When public messages are off:

• You (the phone that scanned the QR code) can still message your assistant
• Admin phones (added on the Admins page) can still message your assistant
• Everyone else is blocked — they won't get a response

When public messages are on: Anyone who messages your WhatsApp number gets a response from your public assistant.

No restart is needed — the change takes effect immediately.

Remote Access

Remote Access lets you reach the control panel from anywhere — your phone, another computer, or while away from home. It uses Tailscale to create a private, encrypted connection with a trusted HTTPS certificate (no browser warnings).

What you need

• Tailscale installed on the Taskmaster device (the Raspberry Pi or Mac running Taskmaster)
• Tailscale installed on every device you want to access the control panel from (your phone, laptop, etc.)
• All devices logged into the same Tailscale account

Tailscale is free for personal use (up to 100 devices). Apps are available for iOS, Android, Mac, Windows, and Linux.

Enabling Remote Access

1. Open the control panel setup page
2. Find the Remote Access row in the status dashboard
3. If Tailscale is not connected, click Connect — scan the QR code with your phone and sign in with your Google or Microsoft account
4. Once connected, click the power icon to enable
5. A URL appears like https://taskmaster.tail0e0afb.ts.net
6. Bookmark this URL on your other devices — it's your personal, trusted HTTPS address for the control panel

Accessing from other devices

1. Install Tailscale on the device (phone, laptop, etc.)
2. Log in with the same account you used on the Taskmaster device
3. Open the bookmarked URL — no certificate warnings, just a normal secure connection

Disabling Remote Access

Click the power-off icon on the Remote Access row. You'll be asked to confirm — click Confirm to proceed. The tailnet URL stops working immediately (no gateway restart needed).

Internet Access

By default, Taskmaster is only reachable on your local network and via Tailscale (if enabled). To let people outside your network use the public chat — for example, embedding it on your website — you need to enable Internet Access.

There are two ways to do this:

• Cloudflare Tunnel (recommended) — gives you two addresses on your own custom domain: one for the control panel (admin.yourdomain.com) and one for the public chat (public.yourdomain.com/chat/your-account). Requires a domain registered with Cloudflare.
• Tailscale Funnel — gives your device a public HTTPS address on Tailscale's shared domain (e.g. taskmaster.tail0e0afb.ts.net). No custom domain needed.

Cloudflare Tunnel

Cloudflare Tunnel gives your device two dedicated addresses on your own domain — one for the admin control panel and one for the public chat. It requires a domain managed by Cloudflare (either purchased through Cloudflare or transferred to it).

Prerequisites

• A Cloudflare account (free at cloudflare.com)
• A domain added to your Cloudflare account — you can buy one through Cloudflare or transfer an existing one

Ask your Taskmaster assistant to “help me set up Cloudflare Tunnel” and it will walk you through getting a domain if you don't have one.

Setting up

1. Go to the Setup page and find the Cloudflare row
2. If cloudflared is not installed, tap Install — the system handles it automatically
3. Tap Connect — a browser window opens. Sign in to Cloudflare, select your domain, and click Authorize
4. Once connected, tap the settings icon to open the tunnel wizard. It will show the two addresses that will be created: admin.yourdomain.com and public.yourdomain.com
5. Tap Create Tunnel — the DNS records are created automatically (no Cloudflare dashboard needed)
6. Set a remote access password — this protects the admin control panel when accessed from outside your network
7. Tap Enable Tunnel — both addresses go live immediately

What you get

• admin.yourdomain.com — the control panel, accessible from anywhere with your remote password. Your PIN is still required after that.
• public.yourdomain.com/chat/your-account — the public chat, accessible to anyone with no login required
• Nothing else is exposed — only these two endpoints are routed through the tunnel

Tailscale Funnel

Tailscale Funnel gives your device a public HTTPS address on Tailscale's shared domain. No custom domain is needed — useful if you're already using Tailscale for Remote Access.

1. Go to the Setup page and find the Remote Access row
2. Enable Remote Access first if not already active
3. Click the globe icon on the Remote Access row to enable Internet Access (Funnel)
4. If prompted, enable Funnel on your Tailscale account at the link shown, then try again
5. Your public URL appears (e.g. https://taskmaster.tail0e0afb.ts.net)

To disable: click the globe-off icon. The public URL stops working immediately.

Embedding the chat widget on your website

Once Internet Access is enabled (via either method), you can add a floating chat button to any website. Add this code just before the closing </body> tag:

<script src="https://YOUR-PUBLIC-URL/public/widget.js"></script>
<script>
  Taskmaster.init({
    server: "https://YOUR-PUBLIC-URL",
    accountId: "your-account-id"
  });
</script>

Replace YOUR-PUBLIC-URL with your public address — for Cloudflare it's https://public.yourdomain.com, for Tailscale it's the URL shown on the Remote Access row. Replace your-account-id with your account name (e.g. taskmaster).

A chat button appears in the bottom-right corner of the page. Clicking it opens a chat window where visitors can talk to your assistant — no WhatsApp required.

You can optionally set colours to match your website: color controls the floating chat button, and bgColor controls the chat overlay background. If you've set up branding on the Setup page, the widget uses your brand colours automatically — these init options override them if provided.

Visitor Verification

By default, anyone who opens the public chat can start a conversation immediately (anonymous mode). If you want to verify visitors before they chat — for example, to collect contact details or reduce spam — you can enable identity verification.

1. Go to the Setup page
2. Find the Public Chat status card
3. Click the settings icon to open the verification settings modal
4. Choose an auth mode: Anonymous (no verification), Verified (must verify before chatting), or Visitor chooses (can chat immediately or verify for cross-device continuity)
5. Select which verification channels to enable — three independent checkboxes:

   Channel	How it works	What you need
   WhatsApp	Verification code sent via WhatsApp	A connected WhatsApp account
   SMS	Verification code sent by text message	Same Brevo API key as email, plus prepaid SMS credits in your Brevo account
   Email	Verification code sent by email	A Brevo API key and a verified sender (free, no credit card)

   When both WhatsApp and SMS are enabled, phone verification tries WhatsApp first and falls back to SMS. To use SMS only, uncheck WhatsApp.

6. Enter your provider credentials — add the Brevo API key in the API Keys section on the Setup page. The same key serves both email and SMS verification. For SMS, purchase SMS credits in your Brevo dashboard.
7. Settings auto-save when you change a checkbox or leave a field

Once enabled, visitors must authenticate before they can send their first message. Verified contact details are stored and available to the agent, so your assistant knows who it's talking to.

Chat Commands

You can control your assistant's behaviour by typing slash commands in any conversation. These are intercepted by the system — the assistant never sees them.

How commands work

• Type a command on its own (e.g., /filler on) — the system responds with a confirmation
• Type a command without an argument (e.g., /filler) — the system shows the current setting and valid options
• Commands work in WhatsApp, iMessage, and the Chat page
• Only admin phone numbers can use most commands

Common commands

Voice replies (Text-to-Speech)

Your assistant can reply with voice notes instead of text. Two providers are available:

Control voice replies with the /tts command:

How it works: When TTS is enabled, the assistant writes its reply as normal text, and the system automatically converts it to a voice note before sending. If the selected provider fails (e.g. missing API key), it falls back to the next available provider. Emojis are automatically stripped so they don't get read aloud.

Quick start: Type /tts always — Edge TTS works immediately with no setup. To upgrade to Hume's expressive voice, add a Hume API key in the Control Panel and type /tts provider hume.

Examples

You: /filler
System: Filler messages: off. Options: on, off.

You: /filler on
System: Filler messages enabled.

You: /think high
System: Thinking level set to high.

You: /tts always
System: TTS mode set to always.

You: /tts provider hume
System: TTS provider set to hume (fallbacks: edge).

Groups

Your assistant can respond in WhatsApp group chats. By default, groups are disabled.

Enabling Groups

Open the Control Panel, go to the WhatsApp section, and tap the settings (gear) icon on your WhatsApp account. In the settings modal, tick Group chats. This allows your assistant to respond in any WhatsApp group it's added to.

How the Assistant Responds

When you enable groups, you choose how the assistant responds:

• When mentioned (default) — the assistant only responds when someone @mentions it
• Always respond — the assistant responds to every message in every group

Per-Group Override

Group members can override the response mode for their specific group using chat commands:

• /activation always — respond to every message in this group
• /activation mention — only respond when @mentioned

Only the business owner can change the activation mode.

Updating Taskmaster

Checking for Updates

Taskmaster checks for updates automatically when you open the Setup page. The Software row in the Status Dashboard shows your current version and whether an update is available:

• Green — You're running the latest version
• Yellow — An update is available (shows the new version number, e.g., “v1.0.38 → v1.0.39”)
• Grey — Not yet checked

If the row shows “Unknown”, tap the refresh button (circular arrow) to check manually. Tap the (i) button to see version details (current version, latest version, and status).

Installing an Update

1. Open the Setup page
2. Look for the Software row — if it's yellow, an update is available
3. Tap the download button (down-arrow icon)
4. A progress overlay appears showing each step of the update (fetching, building, running checks, etc.)
5. When the update completes, the gateway restarts automatically
6. The page reconnects on its own — you'll see a result banner showing the version change (e.g., “Updated: v1.0.38 → v1.0.39”)
7. The Software row should now show green

You don't need to refresh the page — the overlay stays visible during the update and the page reconnects automatically after the gateway restarts.

Alternative: Re-run the Installer

You can also update by re-running the install command in Terminal:

curl -fsSL https://taskmaster.bot/install.sh | sudo bash

This detects your existing installation and upgrades it in place.

If an Update Fails

If something goes wrong during the update:

• The progress overlay shows which step failed (marked with an X)
• A result banner appears with the failure reason
• Your previous version remains running — a failed update does not leave your system broken
• Tap Dismiss to close the result banner

If the page loses connection during the update and doesn't reconnect within two minutes, refresh the page manually. If the gateway doesn't come back, try power-cycling your device (unplug and replug).

Automatic Recovery from Bad Updates

On Raspberry Pi and Linux devices, Taskmaster includes an automatic safety net. If an update installs a version that crashes on startup, the system detects the crash loop and automatically rolls back to the previous working version. You don't need to do anything — the rollback happens on its own and the dashboard comes back online within about 30 seconds.

After an automatic rollback, a banner on the Setup page shows what happened (e.g., “Auto-rollback to v1.0.70 after 3 consecutive startup failures”). You can try updating again later — the issue may be fixed in a newer version.

Command Line (CLI)

Taskmaster includes a command-line tool called taskmaster that you can run in a terminal (Terminal on Mac, or via SSH on a Pi). You don't need the command line for day-to-day use — the Control Panel handles everything — but it's useful for troubleshooting, updating when the Control Panel isn't accessible, or automating tasks.

How to access the terminal

• Mac: Open Terminal (search for “Terminal” in Spotlight)
• Raspberry Pi (direct): Plug in a keyboard and monitor, open Terminal from the taskbar
• Raspberry Pi (remote): From another computer, run ssh [email protected] (replace taskmaster with your hostname if changed)

Essential commands

Configuration commands

When to use the CLI instead of the Control Panel

• Can't reach the Control Panel — If the web UI is down, SSH into the device and use CLI commands to restart or update
• Updating from a specific version — taskmaster update works even when the Control Panel can't load
• Changing network settings when the UI is unreachable — Port and hostname are normally changed from the Setup page, but the CLI works as a fallback (see “Changing Network Settings” above)
• Diagnosing problems — taskmaster doctor runs automated health checks that can detect and fix issues the UI can't show
• Scripting and automation — CLI commands can be combined in scripts for advanced setups

Getting help for any command

Add --help to any command to see its options:

taskmaster update --help
taskmaster daemon --help
taskmaster config set --help

Or run taskmaster help to see all available commands.

Uninstalling Taskmaster

From the Control Panel

1. Open the Setup page
2. Scroll to the bottom of the dashboard
3. Tap Uninstall Taskmaster (in red)
4. Type UNINSTALL in the confirmation box
5. Tap the Uninstall button

This stops the gateway, removes all configuration, workspace files, and attempts to remove the npm package. If the package could not be removed automatically (permissions), the page will show a command to run manually.

From the command line

To remove everything in one command:

taskmaster uninstall --purge --yes

This removes the gateway service, configuration (~/.taskmaster), workspace files (~/taskmaster), and the npm package itself.

Getting Help

• Email: [email protected]
• WhatsApp: +44 7591 215452

Taskmaster — Your admin assistant that works while you work.