Clai (Conversational language Artificial Inteligence) version: TALOS is a free, self-hosted AI assistant focused on practical automation through Telegram and a local web dashboard.

It is intentionally a single-process Python system: easy to run, easy to debug, and easy to modify.

If you are searching for an easier OpenClaw alternative, a free Claude Cowork alternative for personal use, or a simple AI assistant that does not require platform-level setup, Clai TALOS is built for that use case.

Download or clone this repository, then open a terminal in the project folder:

cd Clai_TALOS

Run one script:

Linux/macOS:

./start.sh

Windows:

start.bat

Windows status: Supported for local runtime and EXE preview builds. Linux/macOS remain the most-tested platforms.

Open the dashboard:

Go to http://localhost:8080 and complete signup + onboarding.

For users who want the fastest install from a GitHub Release asset.

Linux/Ubuntu (.deb):

# Run in the folder where you downloaded the .deb
sudo apt install ./clai-talos_<version>_amd64.deb
sudo systemctl enable --now clai-talos
sudo systemctl status clai-talos --no-pager

If install fails with unmet dependencies like python3-venv or python3-pip not installable:

sudo add-apt-repository -y universe
sudo apt update
sudo apt install ./clai-talos_<version>_amd64.deb

macOS (.pkg):

# Run in the folder where you downloaded the .pkg
sudo installer -pkg ./clai-talos_<version>.pkg -target /

# Start and check background service
sudo launchctl kickstart -k system/com.claitalos.service
sudo launchctl print system/com.claitalos.service

# Optional: stop service
sudo launchctl bootout system /Library/LaunchDaemons/com.claitalos.service.plist

# Optional: tail logs
tail -f /usr/local/var/clai-talos/logs/stderr.log

macOS (.app / .dmg):

# If you downloaded the .app directly:
open "./Clai TALOS.app"

# If you downloaded the .dmg:
hdiutil attach ./clai-talos_<version>.dmg
cp -R "/Volumes/Clai TALOS <version>/Clai TALOS.app" /Applications/
hdiutil detach "/Volumes/Clai TALOS <version>"
open "/Applications/Clai TALOS.app"

# Optional: logs for the app bundle runtime
tail -f ~/.clai-talos/logs/stderr.log

Open the dashboard at http://localhost:8080.

Use either local build mode (for development) or image mode (no source build).

Local build mode (from repository root):

# Build and start
docker compose up -d --build

# View logs
docker compose logs -f talos

# Stop
docker compose down

Image mode (pull from GitHub Container Registry) aka Docker compose:

services:
  clai-talos:
    image: ghcr.io/vynavinv/clai-talos:sha-5532fd6
    container_name: clai-talos
    restart: unless-stopped
    ports:
      - "3000:8080"

Open the dashboard at http://localhost:8080.

Notes:

• Runtime data is persisted in the Docker volume talos-data.
• The container sets TALOS_DATA_DIR=/data.
• If port 8080 is occupied, set WEB_PORT before launch:

WEB_PORT=8090 docker compose up -d --build

In image mode, use:

WEB_PORT=8090 docker compose -f docker-compose.release.yml up -d

If docker: command not found appears:

• On Windows: install Docker Desktop and enable WSL integration.
• On Linux: install Docker Engine + Compose plugin, then restart the terminal.

For servers or remote machines without a browser:

./start.sh --headless

Windows also supports headless mode:

start.bat --headless

When no config exists, headless mode offers:

1. Tailscale + browser path - Connect Tailscale, start Funnel, and finish onboarding from any device.
2. Terminal-only path - Configure Telegram, model provider, API keys, and optional services directly in terminal.

The startup scripts (start.sh, start.bat) automatically:

1. Ensure required directories exist (projects, logs/...).
2. Verify a supported Python runtime (3.10 to 3.13).
3. Create/validate a virtual environment.
4. Install dependencies from requirements.txt.
5. Run setup.py checks (env defaults, package checks, browser defaults).
6. Launch dashboard and bot runtime.
7. On Linux, start.sh may configure passwordless sudo for TALOS setup tasks.

start.sh (Linux/macOS) also attempts best-effort Tailscale + Funnel setup.

TALOS currently uses an opinionated setup path for Linux convenience.

On Linux, start.sh can create /etc/sudoers.d/clai-talos containing a rule equivalent to:

<current-user> ALL=(ALL) NOPASSWD: ALL

This is used so setup steps can run non-interactively.

If this is not acceptable in your environment, review start.sh before running TALOS.

To remove the sudoers file later:

sudo rm -f /etc/sudoers.d/clai-talos
sudo -k

This behavior is Linux-specific.

• Who This Is For
• Why TALOS Instead of Heavy Platforms
• The Evolution of CLAI (2020-2026)
• Capability Overview
• Repository Layout
• Architecture
• Sudoers Behavior (Linux)
• First Boot and Onboarding
• Dashboard Guide
• HTTP Routes and API Reference
• Configuration Reference (.env)
• Built-in Tool Reference
• Advanced File Support
• Google Ecosystem Integration
• Himalaya Email Integration
• Browser Automation Notes
• Projects Gateway
• Data Storage and Persistence
• Security Model
• Operational Notes
• Troubleshooting
• Development Workflow
• Contributing
• Security Reporting
• Changelog
• Documentation Map
• License

Clai TALOS is a good fit if you want:

• a free personal AI assistant that you can self-host
• a simpler alternative to platform-style assistant stacks
• fast setup with one script and a guided onboarding flow
• local control (SQLite + files) instead of distributed infrastructure
• loud errors and straightforward debugging when something fails

It is not aimed at multi-channel enterprise orchestration, large plugin marketplaces, or microservice-heavy deployments.

The project philosophy comes from src/docs/philosophy.md: simplicity over features, fail loudly, and avoid architecture that hides failure points.

If you need broad team collaboration or many messaging channels, OpenClaw or Claude Cowork style stacks may be a better fit. If you want a personal assistant that is easier to set up and maintain, TALOS is designed for that.

CLAI began in 2020 as a personal experiment in automated interaction: a simple Discord bot built on legacy chatterbot-style architecture.

Over six years, the project evolved through repeated real-world failures, rewrites, and architectural simplification.

• 2020 (v1): Built as a reactive, Discord-based roasting bot to explore basic natural language parsing.
• 2021-2025 (v2-v3): Shifted into iterative chatbot experimentation focused on state management and response latency.
• Early 2026 (v4): Adopted early agentic framework patterns (including OpenClaw-style workflows), which exposed limitations in bloated, vision-heavy, and black-box orchestration.
• 2026 (v5 / TALOS): Rebuilt for reliability first. TALOS uses a high-density core prompt architecture, ephemeral tool injection, and a hybrid-automation design aimed at long-term maintainability.

TALOS is designed as the practical infrastructure this project needed from the beginning: user-first, inspectable, and sustainable for personal AI automation.

TALOS keeps all source code under src/ for a clean repository layout. Python modules, tool docs, web assets, and build scripts all live inside src/.

Structure overview:

• Source modules live in src/ (AI.py, core.py, telegram_bot.py, model_router.py, etc.).
• Tool docs and usage references live in src/tools/.
• Dashboard pages and static assets live in src/web/.
• Additional documentation lives in src/docs/.
• Runtime-generated data stays local and ignored (logs/, projects/, talos.db, .env, .credentials).

Telegram/Web Request
        |
        v
  core.process_message
        |
        v
    AI.respond
        |
        v
  Tool Selection + Execution
        |
        +--> terminal_tools / browser_automation / websearch / ...
        |
        +--> db + memory persistence
        |
        v
Response back to Telegram or Dashboard chat

• telegram_bot.py
• Owns the aiohttp web app, auth, onboarding, dashboard APIs, and Telegram runtime lifecycle.
• core.py
• Receives user messages, handles simple fast paths, calls AI.respond, and streams progress when configured.
• AI.py
• Central orchestrator that builds the system prompt, exposes tool schemas, executes tool calls, and manages subagent behavior.
• db.py
• Manages SQLite initialization, settings, chat history, and summaries.
• memory.py
• Handles long-term memory storage and relevance retrieval.

Unlike older versions, first run is now onboarding-first through the dashboard.

If no credentials exist, root route redirects to signup.

• Open http://localhost:8080
• Create username/password (stored in .credentials)
• Password is stored as bcrypt hash

If TELEGRAM_BOT_TOKEN is missing, authenticated users are redirected to onboarding.

Onboarding endpoints support:

• Telegram token + bot name
• model provider + API key + model selection (OpenAI, Anthropic, Gemini, ZhipuAI, NVIDIA, Cerebras, OpenRouter, or Ollama)
• Gemini key
• optional Gmail/Himalaya setup
• optional Google credentials
• Tailscale status check

TALOS can run in two modes:

• Full mode: dashboard + Telegram bot connected
• Web-only mode: dashboard available, Telegram not connected yet

If Telegram startup fails, TALOS continues in web-only mode with explicit console notice.

Base URL: http://localhost:8080

Main pages:

• /
• Root router that redirects to signup, login, onboarding, or dashboard based on state.
• /signup
• First-time credential creation page.
• /dashboard
• Primary control panel and status view.
• /keys
• API key management UI.
• /settings
• Bot/runtime/integration configuration UI.
• /tools
• Toggle built-in tool permissions (.tools_config).
• /projects
• Project gateway page for generated web projects.
• /static/chat.html
• Native web chat UI.

TALOS reads .env and supports hot reload for most runtime settings.

Ollama runs models locally with no API key. Install from ollama.com, start it, then set OLLAMA_MODEL to any model name. The model is pulled automatically on first use. Browse available models at ollama.com/library.

These tools are exposed by the orchestrator and can be toggled in the dashboard.

Supported actions:

• read_with_pandas
• edit_with_openpyxl
• recalculate_with_libreoffice
• verify_formula_errors
• apply_financial_color_coding

Recommended workflow for financial models:

1. Read with pandas (read_with_pandas) to inspect data quickly.
2. Edit with openpyxl (edit_with_openpyxl) so formulas and formatting are preserved.
3. Recalculate with LibreOffice (recalculate_with_libreoffice) using scripts/recalc.py.
4. Verify errors (verify_formula_errors) and ensure zero formula error tokens.
5. Apply financial color standards (apply_financial_color_coding).

Color rules implemented:

• Inputs: blue
• Formulas: black
• External links: red

LibreOffice recalculation requirements:

• LibreOffice installed
• soffice accessible on PATH or LIBREOFFICE_BIN set

Supported actions:

• create_with_docx_js
• edit_xml
• track_replace
• set_page_size_dxa
• set_table_widths_dxa
• normalize_text
• validate_xml

DOCX implementation behavior:

• New docs are generated with Node + docx package.
• Existing docs are modified by unpacking zip -> editing XML -> repacking.
• Tracked changes use explicit WordprocessingML tags (w:del, w:ins).
• Page and table sizing uses DXA units.
• Unicode bullets can be normalized to hyphen.
• Smart quotes/apostrophes can be normalized to XML entities.
• XML validation runs after writes.

Node requirement for DOCX creation:

npm install docx

Google path is centralized via google_execute.

Available patterns include:

• calendar reads/creates
• drive listing/exports
• sheets read/append
• custom Apps Script forwarding if GOOGLE_APPS_SCRIPT_URL is set

Operational expectations:

• OAuth is required for private user data.
• GOOGLE_API_KEY is optional and does not replace OAuth for user-private resources.
• Integration fails loudly on auth/config errors.

Email path is centralized via email_execute.

Supported action families:

• account and folder listing
• message listing and reading
• thread retrieval
• send/reply/forward
• move/copy/delete

Onboarding helper can auto-configure Gmail with app password, writing config under .himalaya/config.toml and setting env keys.

Browser automation is CDP-based and can reuse real logged-in Chrome state.

Key behavior:

• Connects to existing Chrome debug endpoint where possible
• Can start Chrome debug mode if configured
• Isolated fallback profile is opt-in (default off)
• Dashboard and tools expose state/connect/run/disconnect operations

If Chrome profile lock issues happen:

• close regular Chrome windows
• retry browser connect/start
• only enable isolated fallback if needed

gateway.py serves static projects from projects/ (or PROJECTS_DIR).

Main behaviors:

• Register project metadata in projects/gateway.json
• Serve project files at /projects/{name}/...
• Provide API for listing/registering projects
• Detect Tailscale base URL and produce full share links

Database file: talos.db

Key tables initialized by db.py:

• user_settings
• user_profiles
• cron_jobs
• chat_history

Memory storage is initialized by memory.py in table memories.

Implemented controls include:

• bcrypt password hashing in .credentials
• session cookies (HttpOnly, SameSite=Strict)
• CSRF token generation/validation
• login rate limiting and lockout window
• security event logging in .security.log
• path restrictions in file tools for protected dirs/secrets

Operational reminders:

• Use a strong unique dashboard username/password at first setup.
• Dashboard signup requires at least 10 characters.
• Linux users: review Sudoers Behavior (Linux), especially on shared or managed systems.
• Do not expose dashboard publicly without proper network controls.
• Review tool permissions in /tools before broad usage.

/api/status reports:

• bot runtime state
• tailscale state
• funnel state
• venv status
• credentials status
• uptime

• Hot reload (/api/reload): reloads env and clients without process replacement.
• Restart (/api/restart): replaces process and restarts runtime.

/api/context-usage reports current context usage percentage and state (safe, warning, critical) for web chat profile.

Likely causes:

• invalid TELEGRAM_BOT_TOKEN
• network restrictions
• Telegram startup failure

Actions:

1. Set token in onboarding or settings.
2. Trigger hot reload.
3. Check console output for startup error details.

Likely causes:

• Chrome not running with debug endpoint
• profile lock contention

Actions:

1. Use browser start/connect tools.
2. Close normal Chrome windows and retry.
3. Enable isolated fallback only if needed.

Likely causes:

• LibreOffice missing
• soffice not on PATH

Actions:

1. Install LibreOffice.
2. Set LIBREOFFICE_BIN if needed.
3. Retry recalculate_with_libreoffice.

Likely causes:

• Node not installed
• docx package missing

Actions:

1. Install Node.js.
2. Run npm install docx.
3. Retry create_with_docx_js.

Likely causes:

• missing cargo/brew for auto-install path
• invalid Gmail app password
• himalaya binary not on PATH

Actions:

1. Install Himalaya manually.
2. Set HIMALAYA_BIN and HIMALAYA_CONFIG in settings.
3. Verify account with email_execute list actions.

Likely causes:

• Ollama not installed or not running
• model name misspelled
• wrong OLLAMA_BASE_URL

Actions:

1. Install Ollama from ollama.com.
2. Start Ollama (ollama serve or launch the app).
3. Verify with ollama list in terminal.
4. Check OLLAMA_MODEL and OLLAMA_BASE_URL in settings.
5. Use the "Install & Set Model" button in Settings to auto-pull.

Recommended:

./start.sh

Manual:

cd src
python3 setup.py
source venv/bin/activate
python3 telegram_bot.py

Python dependencies are in src/requirements.txt.

Current core packages include:

• python-telegram-bot
• aiohttp
• python-dotenv
• bcrypt
• zhipuai
• google-genai
• openai
• anthropic
• httpx
• croniter
• playwright
• gTTS
• scrapy
• pandas
• openpyxl

Local build (PowerShell):

./src/scripts/build_windows_exe.ps1

Each run creates a new versioned artifact using timestamp-gitsha[-dirty]. You can also set your own label:

./src/scripts/build_windows_exe.ps1 -Version "v0.2.1"

This generates:

• dist/ClaiTALOS-windows-x64-<version>.zip
• dist/ClaiTALOS-windows-x64-latest.zip
• dist/SHA256SUMS.txt
• dist/SHA256SUMS-<version>.txt
• dist/build-manifest.json

CI release build:

• Workflow: .github/workflows/windows-exe-release.yml
• Trigger: manual dispatch or git tags matching v*
• Tagged builds publish EXE zip + checksums to GitHub Releases

Docker release image workflow:

• Workflow: .github/workflows/docker-image-release.yml
• Registry: ghcr.io/vynavinv/clai-talos
• Triggers: - Push to main (updates latest) - Tags matching v* (publishes version tags) - Manual dispatch

Use the image with:

docker compose -f src/docker-compose.release.yml up -d

On macOS:

chmod +x src/scripts/build_pkg.sh
./src/scripts/build_pkg.sh 0.1.0

This generates:

• dist/pkg/clai-talos_<version>.pkg

On macOS:

chmod +x src/scripts/build_app.sh
./src/scripts/build_app.sh 0.1.0

This generates:

• dist/app/Clai TALOS.app

On macOS:

chmod +x src/scripts/build_dmg.sh
./src/scripts/build_dmg.sh 0.1.0

This generates:

• dist/dmg/clai-talos_<version>.dmg

Two paths (see MAKING_TOOLS.md for full guide):

• Add native Python tool implementation and register in src/AI.py.
• Use dynamic tools (create_tool, list_dynamic_tools, delete_tool) for command-template style tools.

See CONTRIBUTING.md for local setup, coding standards, and pull request workflow.

See SECURITY.md for vulnerability reporting guidance.

See src/docs/CHANGELOG.md for release notes and notable changes.

Top-level docs:

• src/docs/philosophy.md - project philosophy and complexity boundaries
• CONTRIBUTING.md - contribution workflow and standards
• SECURITY.md - vulnerability reporting policy
• CODE_OF_CONDUCT.md - contributor behavior expectations
• src/docs/CHANGELOG.md - release history
• src/tools/*.md - per-tool usage documentation

Current tool docs:

• src/docs/MAKING_TOOLS.md
• src/tools/browser.md
• src/tools/cron.md
• src/tools/docx_execute.md
• src/tools/dynamic_tools.md
• src/tools/email.md
• src/tools/file_tools.md
• src/tools/gateway.md
• src/tools/google.md
• src/tools/memory.md
• src/tools/model_prefs.md
• src/tools/presentation.md
• src/tools/scrape_url.md
• src/tools/spreadsheet_execute.md
• src/tools/subagent.md
• src/tools/telegram.md
• src/tools/terminal.md
• src/tools/voice.md
• src/tools/websearch.md

MIT (see LICENSE).