Getting Started

System Requirements

Installation

AumaTron is available as a Windows installer or a portable package.

Windows Installer (Recommended)

1. Download the installer from aumatron.com/download
2. Run the installer — it bundles Node.js, so no pre-installation needed
3. AumaTron installs to your AppData folder and creates a desktop shortcut
4. Launch AumaTron from the desktop shortcut or Start menu

Portable Package

1. Download the portable ZIP from aumatron.com/download
2. Extract to any folder on your machine
3. Ensure Node.js 18+ is installed on your system
4. Open a terminal in the extracted folder and run npm install
5. Start with npm start or node server/index.js

First Run Setup

On first launch, AumaTron automatically:

• Generates a .env file with secure random keys (ENCRYPTION_KEY, SESSION_SECRET, JWT_SECRET)
• Creates the SQLite database and runs all migrations
• Starts the server on port 3000

Open your browser and navigate to http://localhost:3000. You'll be prompted to create your first account using an invite code.

Setting Your Workspace

The workspace is the root folder where AumaTron reads and writes files. All file operations (AI tools, file browser, uploads) are restricted to this folder for security.

1. Go to Settings → General
2. Under Workspace Path, enter the folder path (e.g. C:\Users\YourName\AumaTron-Files)
3. Click Save

Quick Start

Once installed, here's the fastest way to see AumaTron in action:

1. Set an AI provider — Go to Settings → AI Providers. For the quickest start, paste your OpenAI API key. For free/private, set up a local model (see Local AI).
2. Send a message — Type something in the chat like: "Go to wikipedia.org and tell me today's featured article"
3. Watch it work — AumaTron will launch a browser, navigate to the site, extract the content, and respond in chat.

That's it. You're automating with AI.

AI Providers

Local AI (Llama)

Run AI completely offline on your own hardware. No API costs, no data leaving your machine.

Setup

1. Download a GGUF model file (e.g. Llama 3, Mistral, Phi-3) from Hugging Face or similar
2. Go to Settings → AI Providers → Local AI
3. Set the path to your GGUF model file
4. Configure GPU layers (higher = faster, but uses more VRAM)
5. Click Save — AumaTron will start the llama.cpp server automatically

Recommended Models

OpenAI, Claude, Deepseek

Cloud providers offer more powerful models without needing local GPU resources. Available on all plans — just add your API key. Custom providers (Groq, Mistral, etc.) require a Pro plan or higher.

OpenAI

1. Get an API key from platform.openai.com
2. Go to Settings → AI Providers → OpenAI
3. Paste your API key and select your preferred model (GPT-4o, GPT-4o-mini, etc.)

Anthropic Claude

1. Get an API key from console.anthropic.com
2. Go to Settings → AI Providers → Claude
3. Paste your API key and select a model (Claude Sonnet, Haiku, etc.)

Deepseek

1. Get an API key from platform.deepseek.com
2. Go to Settings → AI Providers → Deepseek
3. Paste your API key

Custom Providers

Add any OpenAI-compatible API endpoint as a custom provider. This works with Groq, Mistral, Together AI, Ollama, LM Studio, and many others. Pro+

1. Go to Settings → AI Providers → Custom Providers
2. Click Add Provider
3. Enter a name, the API endpoint URL, your API key, and the model name
4. Test the connection, then save

Any provider that follows the OpenAI chat completions API format (/v1/chat/completions) will work.

Choosing the Right Provider

Browser Automation

How It Works

AumaTron controls real browsers using Playwright and Puppeteer. When you ask the AI to interact with a website, it:

1. Launches a browser window (or uses an existing persistent session)
2. Navigates to the URL you specify
3. Reads the page content and determines the best action
4. Clicks buttons, fills forms, scrolls, extracts data — whatever your instruction requires
5. Reports back the results in chat

No scripting or coding required. Just describe what you want in plain language.

Browser Types

Select your default browser in Settings → General → Browser Settings. Pro+ plans can switch between browsers at any time.

Saved Sites & Credentials

Save frequently visited websites with their login credentials so the AI can log in automatically.

1. Go to Settings → Saved Sites
2. Click Add Site
3. Enter the site URL, username, and password
4. Optionally add custom instructions (e.g. "Always click 'Accept Cookies' first")
5. Save

Now when you mention the site in chat or Telegram, AumaTron automatically uses the saved credentials to log in. All passwords are encrypted with AES-256-GCM.

WordPress Mode

For WordPress sites, enable WordPress mode on the saved site. This provides dedicated support for WP admin operations like publishing posts, managing plugins, and checking updates.

Stealth & Anti-Detection

Chrome Incognito mode includes anti-detection stealth features:

• Fingerprint spoofing (WebGL, Canvas, AudioContext)
• Realistic browser headers and navigator properties
• Human-like mouse movement and typing delays
• Persistent session cookies across runs

This helps avoid bot detection on sites that actively check for automated browsers.

Tips for Reliable Automation

• Be specific: "Click the blue 'Submit Order' button" works better than "submit the form"
• Use saved sites: Pre-saved credentials eliminate login failures
• Add pre-actions: Configure sites to dismiss popups or accept cookies before the main task
• Use persistent sessions: Staying logged in avoids 2FA prompts and CAPTCHAs on repeat visits (Pro+)
• Check screenshots: If a task fails, the AI often takes a screenshot showing what went wrong

Task Scheduler & Workflows

Creating Tasks

Scheduled tasks let AumaTron run automations on a recurring basis without your involvement.

1. Go to Settings → Scheduler
2. Click New Task
3. Enter a name and the prompt (natural language instruction for the AI)
4. Set the schedule (daily, weekly, or custom cron expression)
5. Optionally select a specific AI provider for this task
6. Save and enable the task

Cron Scheduling

Tasks use cron-style scheduling. Common examples:

Multi-Step Workflows

Workflows chain multiple tasks into a sequence that runs automatically. Each step executes in order, and the workflow loops until its time limit is reached.

1. Create a new task and enable Workflow mode
2. Add steps — each step is a prompt that the AI executes
3. Set a time limit for the overall workflow
4. Save and schedule it like any other task

Workflows are useful for multi-part jobs like: scan a folder for receipts → OCR each one → write a summary → archive processed files.

Task Chaining

Trigger a follow-up task automatically when another task completes. Pro+

1. Open an existing task
2. Under On Completion, select another task to trigger
3. The chained task starts as soon as the first one finishes

This lets you build pipelines: Task A collects data → Task B processes it → Task C sends a report.

Per-Task AI Models

Assign different AI providers and models to individual tasks. Pro+

This is useful for cost optimization:

• Use a cheap/fast model (GPT-4o-mini, local Llama) for simple repetitive tasks
• Use a powerful model (GPT-4o, Claude) for complex tasks that need reasoning
• Use Deepseek for tasks where cost is the primary concern

Telegram Bot

Setup Guide

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create a bot
3. Copy the bot token that BotFather gives you
4. In AumaTron, go to Settings → General → Telegram
5. Paste the bot token and click Save
6. Send a message to your new bot in Telegram — AumaTron will respond

Commands

You can send natural language messages to your bot just like chatting in the AumaTron web interface. The AI has full access to all tools — browser automation, file management, and OCR.

Remote Control

Telegram gives you full remote access to AumaTron from your phone. Some things you can do:

• Browse websites and receive screenshots
• Manage files in your workspace
• Trigger automations on demand
• Receive task completion notifications

Smart credential injection means that when you mention a saved site URL in Telegram, AumaTron automatically uses the stored login details.

File Management

Workspace Path

All file operations are scoped to your workspace folder. This is a security measure — the AI cannot read or write files outside this folder.

Set your workspace in Settings → General → Workspace Path.

File Browser Panel

Click Files in the header to open the file browser panel. It provides:

• Directory navigation with breadcrumb trail
• File preview (text files with syntax highlighting, images with preview)
• File metadata (size, modification date, type)

The file browser is available on all plans for browsing and previewing.

File Operations

Full file management from the browser panel. Pro+

• Create File — Create a new empty text file in the current folder
• Create Folder — Create a new subfolder
• Upload — Upload files from anywhere on your PC into the workspace (50 MB max per file)
• Rename — Rename any file or folder
• Edit — Open text files in an editor, make changes, and save
• Delete — Delete files or folders (folders are deleted with all contents)

AI File Tools

The AI can manage files through chat commands. These tools are available when talking to the AI in chat, Telegram, or scheduled tasks:

• read_file — Read the contents of a text file
• write_file — Create a new file (auto-converts to append if file has content)
• append_to_file — Add content to the end of a file
• create_folder — Create a new directory
• copy_file — Copy a file to a new location
• move_file / rename_file — Move or rename files
• delete_file — Delete a file
• list_folder — List the contents of a directory

All file tools respect the workspace boundary and include safety guards to prevent accidental data loss.

OCR & Receipt Processing

Overview

AumaTron includes built-in OCR (Optical Character Recognition) powered by Tesseract.js. It can read text from images of receipts, invoices, documents, and more.

OCR is commonly used in scheduled tasks to automatically process receipt images, extract totals and dates, and write summaries to a log file.

Language Support

Built-in support for:

• English — Full support
• Thai — Full support including Thai numerals and Buddhist Era dates

OCR runs with both Thai and English language packs simultaneously for accurate results on bilingual documents.

Smart Extraction

After reading the text, AumaTron applies intelligent extraction:

Amount Detection (3-tier)

1. Keyword match — Looks for amounts near keywords like "Total", "Grand Total", "Net" (in English and Thai)
2. Repeated amounts — If the same amount appears multiple times, it's likely the total
3. Largest amount — Falls back to the largest reasonable number found

Date Detection

Recognizes multiple date formats:

• DD/MM/YYYY, DD-MM-YY, DD Mon YYYY
• Buddhist Era years (e.g. 2568 = 2025 CE) — auto-converted

Validation

• Confidence threshold: OCR results below 40% confidence are auto-skipped
• Amount validation: Rejects tracking numbers (>9 digits) and zero/unreasonable values
• Results are cached per task run to prevent redundant processing

Best Practices

• Good lighting: Well-lit, high-contrast receipt photos give the best results
• Flat and straight: Avoid crumpled or angled receipts
• Reasonable resolution: 300+ DPI or a clear phone photo works well
• Use the OCR sidecar app: Install the Receipt OCR app from Settings → Apps for enhanced preprocessing (sharpening, contrast adjustment) that improves accuracy
• Check the confidence: If OCR frequently produces garbage results, the image quality may be too low

Brain System

Personalities

Personalities shape how the AI behaves, its tone, focus areas, and response style.

Using Personalities

1. Create a .md file in the brain/personalities/ folder (or the brain/ root folder)
2. Write instructions for the AI's behavior (e.g. "You are a helpful assistant focused on e-commerce. Always be concise.")
3. Select the personality when starting a new conversation or assigning it to a scheduled task

Each conversation and each scheduled task can use a different personality.

Memory Files

Memory files give the AI persistent knowledge that it can recall based on context.

1. Create .md files in the brain/ folder
2. Write facts, preferences, or reference data the AI should know
3. The AI automatically retrieves relevant memories by matching keywords from your messages against memory file names and content

Token Budgets

The brain system automatically manages token usage to stay within provider limits:

If the personality + memories exceed the budget, the system automatically truncates: first reducing personality to 50% of budget, then reducing to 2 memories, then dropping memories entirely.

Voice (STT & TTS)

Speech-to-Text

Configure your STT provider in Settings → STT.

Text-to-Speech

Configure your TTS provider in Settings → TTS.

Apps & Custom API Tools

Installing Apps

Apps are sidecar services that extend AumaTron's capabilities.

1. Go to Settings → Apps
2. Enter the app's URL (e.g. http://localhost:3001)
3. AumaTron fetches the app's manifest to verify its capabilities
4. Click Install

Once installed, the app's endpoints are automatically registered as AI tools. For example, the Receipt OCR app becomes available as a tool the AI can call during tasks.

First-Party App: Receipt OCR Extractor

The Receipt OCR app provides enhanced receipt scanning with Sharp image preprocessing (sharpening, contrast, binarization) plus Tesseract OCR. It produces better results than the built-in OCR for difficult receipts.

Run it alongside AumaTron on port 3001. If the app goes down, AumaTron gracefully falls back to built-in OCR.

Custom API Tools

Create tools that let the AI call any external API. Pro+

1. Go to Settings → API Tools
2. Click New Tool
3. Configure:
   • Name — Tool identifier (becomes api_yourname)
   • API URL — The endpoint to call
   • HTTP Method — GET, POST, PUT, DELETE
   • Auth — None, Bearer token, API key header, or Basic auth
   • Parameters — Define what the AI can pass to the API
4. Click Test Connection to verify it works
5. Save

The AI will automatically use the tool when relevant to your request. All credentials are encrypted with AES-256-GCM.

Security & Privacy

Encryption

AumaTron encrypts all sensitive data at rest:

• Saved site passwords — AES-256-GCM encrypted in the database
• API keys — AES-256-GCM encrypted
• Custom API tool credentials — AES-256-GCM encrypted
• Session tokens — JWT with signed secrets

The encryption key is generated automatically on first run and stored in your .env file. If you need to rotate keys, a migration script is included.

Website Filtering

Control which websites the AI can access. Pro+

• Whitelist mode — Only allow specific domains
• Blacklist mode — Block specific domains, allow everything else

Configure in Settings → General → Security.

Running Fully Offline

AumaTron can run with zero internet connectivity:

1. Use Local AI (Llama) as your AI provider
2. Use Web Speech API for voice (works offline in some browsers)
3. Use Browser TTS for text-to-speech
4. All data stays on your machine — no cloud calls needed

The only feature that requires internet is browser automation for external websites (obviously). Everything else — file management, OCR, scheduling, chat — works fully offline.

Plans & Billing

Plan Comparison

Annual billing saves 17%: Pro is $120/year ($10/mo), Ultra is $490/year (~$40.83/mo).

Upgrading

Upgrade from Settings → General → Plan, or from the pricing page. Your data and configuration are preserved — no migration needed.

• 14-day money-back guarantee on Pro and Ultra
• Cancel anytime — access continues until the end of the billing period
• Downgrade to Free at any time — you keep your data, but gated features become unavailable

Troubleshooting

FAQ

Common Issues