TigrimOSR is a native desktop AI agent platform for orchestrating teams of specialist AI agents from a single self-contained binary — and for building your own agentic loop. Define swarms in YAML, wire them with inter-agent protocols (TCP, Bus, Queue, Blackboard), and let them collaborate autonomously. Then shape how the loop itself runs: pick the tools, MCP servers, and skills each agent may use, override its model and system prompt, tune self-verification and context compaction — all in simple YAML profiles you can edit from the desktop app or any browser. When the job is done, TigrimOSR doesn't take the agent's word for it: an independent tool-using judge verifies the deliverables actually exist before the answer reaches you. And you don't have to be at your desk for any of it — chat with your agent and drive it with slash commands straight from Telegram or LINE.

• Multi-agent orchestration — 6 modes (hierarchical, mesh, hybrid, pipeline, P2P, P2P orchestrator) with real protocols and a shared blackboard.
• Your agent loop, your rules — customize the whole agent loop as YAML profiles: which tools it may call, which MCP servers and skills it sees, model & system-prompt overrides, loop limits, self-verification, and context compaction — editable from the desktop app and the web UI.
• Don't trust — verify (job evaluation) — LLM agents love to declare success: "Done!" with a missing file, a half-finished swarm job, a confident summary backed by nothing. TigrimOSR closes that trust gap: after the whole job finishes, an independent tool-using judge (optionally a different model, so the agent never grades its own work) checks the result against your objective and rubric — opening the output files to confirm the claimed artifacts actually exist — and feeds any gaps back so the orchestrator delegates targeted fixes before the answer reaches you. One verification per job, not per agent, so even big swarms stay fast.
• Any LLM, any provider — OpenAI, Anthropic, DeepSeek, Kimi, Gemini, Ollama, or any OpenAI-compatible API — plus 3 local CLI agents (Claude Code, Gemini CLI, Codex) with no API keys.
• Full tool calling — web search, Python, file I/O, shell, MCP servers, and the ClawHub skill marketplace. Charts, images, and docs render inline with click-to-zoom.
• Browser control — let the agent drive a real browser to search Google and read the live web directly. Choose your engine: Chrome / Chromium via Playwright, or the stealthy, Node-free Obscura engine (a single Rust binary with built-in anti-detection). It's a real browser, not a paid search-API — no API keys, free of charge, saves money. Opt-in toggle, off by default for safety.
• Plugin system — zip plugins bundling skills, MCP servers, agents, and connectors. Compatible with Claude Desktop/Code plugins and npm MCP packages.
• Run it your way — as a native Rust desktop UI on your machine, headless on a machine or in Docker, and connect from any browser via the built-in web UI. Toggle Local/Remote from one interface.
• Telegram & LINE bots — chat with your agent from the messaging apps you already use, and control it with slash commands (/agents, /model, /mode, /loop, /new, /stop, /status): live progress while it works, approve/deny buttons for tool approvals, and fail-closed user allow-lists. Telegram needs no public URL at all — see Telegram & LINE Bots.
• Private remote access (VPN) — reach a remote host over your own Tailscale VPN instead of exposing it publicly — devices talk over private 100.x addresses, nothing is published to the internet. Opt-in toggle, an alternative to the public Cloudflare tunnel.
• Built in Rust — fast, low-memory, single binary, no Node/Python runtime. Rewritten from TigrimOS (TypeScript/Python). Because both the app and the Obscura browser engine are native Rust, the whole thing — desktop UI, embedded server, and a live embedded browser — idles at only ~270 MB RAM (≈210 MB app + ≈60 MB browser), a fraction of what a Chromium/Electron stack needs just to open a tab.

Install it on your machine and run the UI as a native Rust app — a single, fast binary with quick startup and low memory.

Above: the native desktop app — ask for a plot and the agent runs Python (matplotlib) and embeds the chart inline in its answer.

Because TigrimOS is native Rust end-to-end — the app and its Obscura browser engine — the whole stack stays remarkably light. On an idle desktop session with browser control on and a live browser attached, measured resident memory is:

TigrimOS (app + embedded server)   ≈ 210 MB
obscura (Rust browser engine)      ≈  60 MB
────────────────────────────────────────────
Total, with a live browser         ≈ 270 MB

That's roughly where a Chromium browser process alone tends to start. The reason is structural: most agent stacks pay for two heavy layers TigrimOS doesn't — an interpreted runtime (Node.js/Python) plus a multi-process Chromium driven by Playwright. TigrimOS replaces both with a single Rust binary and a single-process Rust browser.

For rough context, here's how that compares to two popular open-source browser agents. Only the TigrimOS figure is our own measurement; the others are third-party/community-reported and vary widely with workload — treat them as ballpark, not benchmarks:

A single Chromium instance commonly uses 800 MB–2.5 GB depending on the page, and per-agent-browser setups multiply that. Chromium/Playwright stacks also have to actively manage renderer-process accumulation and orphaned browsers across restarts (e.g. OpenClaw #29685) — failure modes TigrimOS avoids with per-session process groups and per-agent browsers that shut down with the session.

Not fixed: ~270 MB is the idle baseline with a browser attached. Real usage grows as Obscura renders heavy pages (its V8 heap climbs per page/tab) and as the app holds conversation, session, and swarm state — expect more under load, but still far below a Chromium-based stack.

Run TigrimOS anywhere — as a native desktop app, headless on a machine, or in Docker — then connect from any browser or your phone. The screenshots below show a cloud server controlled entirely from a mobile browser: full chat with inline charts, tool execution, and file browsing.

• Multi-agent system — hierarchical, mesh, hybrid, pipeline, P2P, and P2P orchestrator modes via YAML config
• Agent loop profiles — user-defined YAML profiles controlling the agent loop: tool allowlist/denylist, MCP server & skill selection, model/system-prompt override, loop knobs (rounds, temperature, reflection, step verification), job evaluation (outer loop, tool-using judge) and context compaction — see Agent Loop Profiles
• Local CLI agents — Use Claude Code, Gemini CLI, or OpenAI Codex as agent backends without API keys
• Plugin system — Zip-based plugins with skills, MCP servers, agents, and connectors. Accepts TigrimOS, Claude Desktop, Claude Code, and npm MCP formats
• Tool calling — web search, Python execution, file read/write, shell commands, skill loading, MCP tools
• Browser control — opt-in toggle that lets the agent drive a real Chromium/Chrome browser (navigate, click, type, screenshot, tabs, JS) via Playwright MCP, or the stealthy Obscura engine (single Rust binary, no Node required) — see Browser Control
• Remote access — Headless mode + embedded web UI for controlling from any browser or mobile phone
• Telegram & LINE bots — chat with the agent from Telegram or LINE and control it with slash commands (/agents, /model, /mode, /loop, /new, /stop, /status), with live progress and approve/deny buttons for tool approvals — see Telegram & LINE Bots
• Remote server dashboard — Connect your Mac app to remote TigrimOS instances
• Private VPN access (Tailscale) — reach a remote host over your own tailnet instead of a public tunnel — see Remote access over a private VPN
• VM integration — Built-in Ubuntu VM with SSH terminal and tool routing
• Customizable themes — color presets (Default, Dark, Minimal, Transparent, Colorful), full per-color editing, font selection (Inter, Geist, Roboto, IBM Plex Sans, Plus Jakarta Sans, or your own) and per-style sizes — all saved to data/theme.yaml
• Output panel or inline files — render images (PNG/JPG), markdown, CSV tables, JSON, PDF, HTML either in a side panel or embedded inline in chat with click-to-zoom (default)
• Agent history log — JSONL logs per session in data/agent_history/
• Skills system — loadable skill modules from skills/ directory
• Sandboxed Python — matplotlib plots auto-saved as PNG via Agg backend
• Resizable layout — drag handles for chat sidebar and output panel widths
• Session management — persistent chat history with project context
• LaTeX math — KaTeX rendering in web UI for equations and formulas

Two ways to install TigrimOS — pick one:

Not sure? Use Docker — it's the fastest and safest, and the agent's code execution stays isolated inside the container.

Run TigrimOS as a self-contained web server in a container — no Rust toolchain, Python, or system libraries to install on your machine. You use it from your browser, and all agent code execution stays sandboxed inside the container, isolated from your host.

• Docker with the Compose plugin (Docker Desktop on macOS/Windows already includes it). Verify with:

  docker --version && docker compose version

Three ways to start, fastest first:

• macOS — one command → run the docker-start.sh script (auto-token, builds, opens the browser).
• macOS / Linux — manual → the four steps below.
• Windows → Headless on Windows.

All three build the same container and share the same data, commands, and security model documented further down.

If you just want it running, this single script checks Docker, auto-generates your login token, builds the container, starts the server, and opens the browser for you — no manual .env editing:

curl -sSL https://raw.githubusercontent.com/Sompote/TigrimOSR/main/docker-start.sh | bash

Want Browser Control too? Add INSTALL_BROWSER=true (bakes the browser into the image, ~400 MB):

curl -sSL https://raw.githubusercontent.com/Sompote/TigrimOSR/main/docker-start.sh | INSTALL_BROWSER=true bash

Already cloned the repo? Run it in place instead:

./docker-start.sh                      # or: INSTALL_BROWSER=true ./docker-start.sh

It prints your token (also saved to .env) at the end — paste it into the web UI to log in. Re-running is safe: it reuses your existing token. Prefer to do it by hand? Follow the four steps below.

1. Get the code

git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR

2. Create your login token. Copy the example env file and put a strong random token in it. This token is what you'll type into the web UI to log in.

cp .env.example .env

# Generate a token and write it into .env:
echo "ACCESS_TOKEN=$(openssl rand -hex 32)" > .env

Keep .env private — it holds your login secret. It is already git-ignored. (On Windows, see Headless on Windows for the PowerShell equivalent.)

3. Build and start. The first build compiles the Rust binary and takes a few minutes; later starts are instant.

docker compose up -d --build

4. Open the app. Go to http://localhost:3001/web/ in your browser and log in with the token from your .env. Then set your AI provider and API key under Settings (saved to ./data, so it persists).

Want Browser Control in Docker? It's off by default to keep the image slim. Bake the browser in by adding INSTALL_BROWSER=true to your .env (or docker compose build --build-arg INSTALL_BROWSER=true), then docker compose up -d --build. The container always runs headless, so it auto-uses headless mode — just enable Browser Control in Settings → AI / API.

docker compose ps         # STATUS should show "Up ... (healthy)"
docker compose logs -f    # should print "Running in headless mode" + listening on :3001

docker compose logs -f         # follow logs
docker compose down            # stop (your data is kept)
docker compose up -d           # start again
docker compose up -d --build   # rebuild after pulling new code

irm https://raw.githubusercontent.com/Sompote/TigrimOSR/main/docker-start.ps1 | iex

$env:INSTALL_BROWSER='true'; irm https://raw.githubusercontent.com/Sompote/TigrimOSR/main/docker-start.ps1 | iex

.\docker-start.ps1                          # or: $env:INSTALL_BROWSER='true'; .\docker-start.ps1

docker --version
docker compose version

git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR

Copy-Item .env.example .env

# Generate a strong random token and write it to .env:
"ACCESS_TOKEN=$([guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N'))" `
  | Out-File -Encoding ascii .env

docker compose up -d --build

Build TigrimOS natively from source for the desktop app (and features the container can't provide, like the VM/QEMU terminal). The one-command installer below clones, builds, and sets up the app for you; manual step-by-step guides per OS follow.

Prerequisites: Install Rust first (if not already installed):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

macOS:

curl -sSL https://raw.githubusercontent.com/Sompote/TigrimOSR/main/install.sh | bash

Linux (Desktop):

curl -sSL https://raw.githubusercontent.com/Sompote/TigrimOSR/main/install-linux.sh | bash

Select "Desktop mode" when prompted.

Windows (PowerShell — recommended, fully automatic):

irm https://raw.githubusercontent.com/Sompote/TigrimOSR/main/install.ps1 | iex

This installs everything for you — git, the Rust MSVC toolchain, the C++ Build Tools (a UAC prompt appears), Python + libraries — then clones, builds, and creates a shortcut. Run it in a normal PowerShell window; approve the Administrator prompt when the build tools install. Need ~10 GB free disk space. If a freshly-installed tool isn't picked up, open a new terminal and run the command again.

Windows (Command Prompt): Download and run install.bat. Unlike the PowerShell installer, the .bat requires git, Rust, and the MSVC C++ Build Tools to already be installed (see the manual steps below) — it then clones, builds, installs Python libraries, and makes a shortcut.

The installer will:

1. Check prerequisites and auto-install what's missing — git, Rust toolchain, and (Windows) the MSVC C++ build tools
2. Let you choose an install location
3. Clone and build in release mode
4. Install Python + the data libraries the tools use (search, charts, data analysis)
5. Create a native app (macOS .app / Linux .desktop / Windows shortcut)
6. Optionally launch the app

Windows note: the one-line PowerShell installer auto-installs git, the Rust MSVC toolchain, the C++ Build Tools (UAC prompt), and Python + libraries. If a tool was just installed and isn't found, open a new terminal and re-run. The built-in VM/QEMU terminal feature is macOS/Linux only; everything else (chat, tools, Python, web/remote UI) works on Windows.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

rustc --version
cargo --version

brew install python
pip3 install duckduckgo-search matplotlib numpy pandas requests

brew install node
npx @playwright/mcp@latest install-browser chrome-for-testing

git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR
cargo build --release
./target/release/tigrimos

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

rustc --version
cargo --version

# Debian / Ubuntu
sudo apt update
sudo apt install build-essential libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libgtk-3-dev

# Fedora
sudo dnf install @development-tools libxcb-devel libxkbcommon-devel gtk3-devel

# Arch
sudo pacman -S base-devel libxcb libxkbcommon gtk3

# Debian / Ubuntu
sudo apt install python3 python3-pip
pip3 install duckduckgo-search matplotlib numpy pandas requests

# Debian / Ubuntu
sudo apt install -y nodejs npm
# Fedora: sudo dnf install -y nodejs ; Arch: sudo pacman -S nodejs npm
npx @playwright/mcp@latest install-browser chrome-for-testing

npx playwright install-deps chromium

git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR
cargo build --release
./target/release/tigrimos

winget install --id Git.Git -e

winget install --id Rustlang.Rustup -e

rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc

winget install --id Microsoft.VisualStudio.2022.BuildTools -e `
  --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

rustc --version
cargo --version

winget install --id Python.Python.3.12 -e
python -m pip install duckduckgo-search matplotlib numpy pandas requests

winget install --id OpenJS.NodeJS.LTS -e
npx @playwright/mcp@latest install-browser chrome-for-testing

git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR
cargo build --release
.\target\release\tigrimos.exe

How the pieces fit together — the Rust core, the agent/tool runtime, the inter-agent protocols (TCP, Bus, Queue, Blackboard), and the desktop/web/remote front-ends that all talk to the same engine.

Above: the overall system architecture — one binary serving the native UI, the embedded web UI, and remote/headless access.

The native Rust desktop UI: a chat-centric workspace with the conversation in the middle, sessions/sidebar on the left, and an output area for files and charts the agent produces.

Above: the main chat view where you talk to the agent, watch tool calls stream live, and see generated files render inline.

10 built-in providers including 3 local CLI agents (Claude Code, Gemini CLI, Codex) — no API keys needed for local providers.

Above: the Settings → AI panel — pick a provider, paste an API key (or use a key-free local CLI agent), and set the model and harness parameters.

Design multi-agent systems visually — create architectures manually or generate them automatically with AI. Supports hierarchical, hybrid, mesh, pipeline, and P2P orchestration modes.

Above: the visual swarm editor — drag agents onto the canvas, draw connections, and pick each link's protocol; or let AI generate the whole architecture.

• Rust 1.75+ (rustup recommended)
• Python 3.8+ with pip (for tool execution)
• macOS 12+ (primary target; Linux and Windows supported)
• Node.js 18+ with npx — optional, only for Browser Control and the local CLI agents below

• Claude Code — npm install -g @anthropic-ai/claude-code
• Gemini CLI — npm install -g @anthropic-ai/gemini-cli
• OpenAI Codex — npm install -g @openai/codex

pip install duckduckgo-search matplotlib numpy pandas requests

On first launch, go to Settings to configure:

Connect your desktop/phone to a remote TigrimOS host privately, over a Tailscale VPN, instead of exposing the host to the public internet. Both devices join your personal tailnet and talk over private 100.x addresses — nothing is published publicly. This is the recommended way to reach a home/office machine from elsewhere.

VPN and the public Cloudflare tunnel are alternative remote-connection methods — pick one. The VPN toggle is off by default, so nothing changes unless you opt in.

VPN is exclusive. While the VPN toggle is on, TigrimOS binds only to loopback (127.0.0.1) and your tailnet IP (100.x). The ordinary LAN/public IP can no longer reach the server, even with a valid token — so "running over VPN" is genuinely private rather than just an extra path. Turn the VPN toggle off to return to the default token-based behavior (reachable on all interfaces). If Tailscale isn't up at startup, TigrimOS falls back to loopback-only and logs a warning — start Tailscale, then restart.

# macOS (CLI via Homebrew)
brew install tailscale
sudo tailscaled install-system-daemon      # installs + starts the daemon
tailscale up                                # prints a login URL — open it & sign in

# Linux
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

macOS users can instead install the Mac App Store app, which bundles the daemon. Sign in with the same account on every device so they share a tailnet.

Verify it's connected:

tailscale status      # should show "Running"
tailscale ip -4       # your 100.x.y.z address

In Settings → Remote:

1. Enable Remote agent access and Generate a remote token (copy it).
2. Check Use VPN (Tailscale) for remote connect.
3. Save, then restart TigrimOS (the network bind decision happens at startup).

After restart the Connect address field shows http://100.x.y.z:3001. Click Copy. If it shows (not detected), click Start VPN / Refresh status and confirm tailscale status is Running.

Settings → Remote → Add Remote Instance:

Open the Remote tab and select the instance — a green dot means connected. Chat, tasks, terminal, and files now run against the host over the private VPN.

• VPN mode is exclusive and takes precedence over token mode. While the VPN toggle is on, the server binds only to loopback (127.0.0.1) and your tailnet IP (100.x) — the ordinary LAN/public IP is not reachable, even with a valid token. This is what makes "run over VPN" genuinely private instead of just adding a second path. The token is still required on every request over the tailnet.
• Token mode is the default (VPN toggle off): with a remote token set the server binds all interfaces (0.0.0.0) so the token works from any IP/LAN/mobile. Turn the VPN toggle off to return to this behavior.
• A token is still required for VPN mode (remoteToken set) — without one the server stays on loopback only, since an unauthenticated TigrimOS must never be on a network.
• If Tailscale isn't up at startup, VPN mode fails closed to loopback-only and logs a warning — start Tailscale, then restart.
• VPN start/stop/status is owner-only: a remote-access token cannot control the host's VPN.
• You must restart the host after toggling for the bind change to take effect.
• The host control endpoints live at /api/vpn/{status,start,stop} (owner token).

# 1. Install + connect Tailscale on that box
curl -fsSL https://tailscale.com/install.sh | sh    # Linux (macOS: brew install tailscale)
sudo tailscale up
tailscale ip -4                                      # note the 100.x.y.z

# 2. Enable the setting without a browser (or use Settings → Remote in the web UI)
#    data/settings.json:
#    { "remoteEnabled": true, "remoteToken": "<token>", "vpnEnabled": true }

# 3. Restart — boot log prints: [VPN] Reachable at http://100.x.y.z:3001
PORT=3001 ./tigrimos --headless

curl -H "Authorization: Bearer <OWNER_TOKEN>" http://127.0.0.1:3001/api/vpn/status

Enable sub-agents in Settings and select an agent config file. Included configs in data/agents/:

system:
  name: My Agent System
  orchestration_mode: hierarchical  # hierarchical | mesh | hybrid | pipeline | p2p | p2p_orchestrator

agents:
  - id: orchestrator
    name: Project Manager
    role: orchestrator
    persona: You are an expert project manager...
    responsibilities:
      - Analyze the user request
      - Delegate tasks to specialist agents
    bus:
      enabled: true

  - id: analyst
    name: Data Analyst
    role: worker
    persona: You are a data analysis expert...
    responsibilities:
      - Analyze datasets
      - Generate charts using Python

workflow:
  sequence:
    - step: 1
      agent: orchestrator
      outputs_to: [analyst]
    - step: 2
      agent: analyst

connections:
  - from: orchestrator
    to: analyst
    protocol: tcp

Customize the agent loop itself — not just the agents — with user-defined YAML profiles stored in data/agent_loops/*.yaml. A profile controls what the loop is allowed to do and how it behaves:

Editing:

• Desktop app — Settings → Agent Loop: form editor (tool/MCP/skill checkboxes, sliders) plus a raw Edit as YAML mode with validate-on-save.
• Web / mobile / headless — Settings → Agent Loop tab in the web UI: active-profile picker, YAML editor with server-side validation, and a catalog of all tool/MCP/skill names.
• REST — GET/POST/DELETE /api/agent-loops, GET /api/agent-loops/catalog, POST /api/agent-loops/reset-default.

Example:

name: research-lite
description: Web research only — no shell, only the browser MCP server
tools:
  mode: allowlist            # allowlist | denylist | all
  list: [web_search, fetch_url, read_file, write_file, run_python, list_files]
mcp:
  mode: selected             # all | selected | none
  servers: [browser]
skills:
  mode: selected             # all | selected | none
  list: [web-search]
model:                       # omit to inherit the main AI settings
  model: claude-sonnet-4-20250514
system_prompt:
  text: |
    Answer in Thai. Cite every source URL.
  replace_base: false        # false = appended to the built-in prompt
loop:
  max_rounds: 20
  temperature: 0.4
  reflection_enabled: true   # judge the final answer, retry gaps
  reflection_threshold: 0.8
  step_verification: true    # judge each team agent's finished step
compaction:
  enabled: true              # periodic compression (safety compaction always stays on)
  interval: 5                # compress every N rounds
  window: 10                 # keep the last N messages uncompressed
  max_context_tokens: 100000
  model: deepseek-chat       # optional cheaper summarizer
evaluation:                  # outer loop: tool-using judge, runs once after the WHOLE job
  enabled: true
  threshold: 0.8             # scores below this trigger a gap-fixing retry
  max_retries: 2             # judge→fix cycles before accepting the result
  max_judge_rounds: 3        # tool rounds the judge may spend verifying
  model: deepseek-chat       # optional dedicated judge model (empty = session model)
  rubric: |                  # success criteria the judge must verify
    A markdown review file must exist with at least 10 papers, each with a DOI.
  allow_execute: false       # true also lets the judge run_python/run_shell (e.g. run tests)

How it behaves:

• default.yaml mirrors your current settings — seeded automatically on first start and selected as the active profile, so nothing changes until you edit it. Reset default regenerates it from live settings at any time.
• Omitted sections inherit the built-in behavior — an empty profile is a no-op.
• Per-agent overrides in team YAML — any agent in data/agents/*.yaml can carry its own tools:, mcp_servers:, skills:, loop:, compaction:, and system_prompt: fields; spawn_subagent children inherit the parent's profile unless they define their own.
• Per-project pinning — a project's agent override can pin its own profile; the web chat also accepts a per-request agent_loop_profile.
• Job evaluation runs once per job, at the top level only — sub-agents keep the cheap per-step text judge (step_verification); the tool-using outer judge fires after the whole group finishes, so a big swarm pays for one verification, not one per agent. Its verdict is visible: the activity log shows evaluator:* verification calls and the chat shows [evaluation] ✓ Passed — score … or the gap-fixing retry.
• Safety is not bypassable — coordination tools (send_task, wait_result, spawn_subagent, …) are never removed while sub-agents are enabled, tool-approval prompts still apply regardless of the profile, over-budget/overflow context compaction always stays on, and checkpoints refuse to resume under a different profile than the one they were saved with.

TigrimOS supports a zip-based plugin system that bundles skills, MCP servers, agent configs, and service connectors into a single distributable package. Install one zip — get everything registered automatically. From the UI: Settings → Plugins → Install Plugin.

curl -X POST http://localhost:3001/api/plugins/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@my-plugin.zip"

my-plugin.zip
├── plugin.yaml
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── mcp/
│   └── server.json
├── connectors/
│   └── service.py
└── README.md

See PLUGINS.md for the full developer guide — manifest format, connector config fields, MCP server config, Claude format compatibility, and the REST API reference.

Let the agent drive a real web browser — navigate to pages, read content, click, fill forms, take screenshots, manage tabs, and run JavaScript. It's powered by Playwright MCP running through TigrimOS's built-in MCP client, and is off by default for safety (once on, the agent can act in the browser — submit forms, click buttons, use logged-in sessions — as you).

Playwright MCP runs on Node, so the npx command must be available.

# macOS (Homebrew)
brew install node

# Ubuntu / Debian
sudo apt-get install -y nodejs npm

# Windows — download the LTS installer from https://nodejs.org

Verify both are present:

node --version    # e.g. v20.x or v22.x
npx --version     # e.g. 10.x

Playwright MCP drives its own managed Chrome for Testing build (~280 MB), not the browser you normally use. Download it once:

npx @playwright/mcp@latest install-browser chrome-for-testing

You should see a download progress bar ending in Chrome for Testing ... downloaded to .../ms-playwright/chromium-XXXX.

npm permission error? If you see EPERM / "root-owned files" from npm, fix the cache ownership once and re-run the command above:

sudo chown -R $(id -u):$(id -g) ~/.npm

• Desktop app: Settings → Security → Browser Control → ☑ Enable browser control.
• Web / mobile UI: Settings → AI / API → Browser Control → ☑ Enable browser control.

It's off by default — tick the box, then choose the engine (Step 4).

⚠️ ARM64 Linux (e.g. AWS Graviton, Hetzner ARM, Raspberry Pi): there is NO Google Chrome. Google has never shipped a google-chrome-stable package for desktop Linux on ARM — the .deb is amd64-only and apt will reject it with "unmet dependencies / not installable". On these hosts you must use Chromium (which has a native ARM64 build). Set browserEngine: "chromium", install it with npx playwright install chromium + npx playwright install-deps chromium, then restart. Many cloud instances are ARM — check with uname -m (aarch64/arm64 → Chromium only).

Saving the setting reconnects MCP immediately — no restart needed. The agent now has tools like mcp_browser_browser_navigate, browser_snapshot, browser_click, browser_type, and browser_take_screenshot, and screenshots render inline in chat.

# Example: macOS Intel (x86_64). Swap the asset name for your platform.
curl -L -o obscura.tar.gz \
  https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-macos.tar.gz
tar xzf obscura.tar.gz
sudo mv obscura obscura-worker /usr/local/bin/
obscura --version          # e.g. obscura 0.1.9

{
  "browserControlEnabled": true,
  "browserEngine": "obscura",
  "browserObscuraPath": "obscura"
}

[MCP] Browser control enabled (obscura) — 35 tool(s)

In a chat, ask:

"Open a browser to example.com and take a screenshot."

Expect the agent to call browser_navigate → browser_snapshot → browser_take_screenshot, then show the screenshot inline. For sites that need a login, the browser keeps a dedicated persistent profile (<data-dir>/browser-profile-<engine>, separate from your everyday browser) — log in once in that window and the session is remembered for later runs.

npx @playwright/mcp@latest --browser <chromium|chrome> \
  --user-data-dir <data-dir>/browser-profile-<engine> \
  --output-dir <data-dir>/browser-output

<browserObscuraPath> mcp --stealth

{
  "browserControlEnabled": true,
  "browserEngine": "chrome",
  "browserHeadless": false,
  "browserObscuraPath": "obscura"
}

Chat with your TigrimOS agent from Telegram or LINE — and control it with slash commands — from anywhere. Telegram needs no public URL at all (outbound long-polling); LINE uses the built-in Cloudflare tunnel for its webhook. Bot conversations run through the same pipeline as web chat, so they appear in the web UI history, stream progress while the agent works, and honor the same tool-approval settings.

Anything else you type is sent to the agent as a chat message. While it works you get throttled progress updates (the tools being called), then the final answer — long answers are split safely on UTF-8 boundaries (Thai and emoji included). One task runs at a time per chat; if you send another message mid-run the bot asks you to /stop first. When a tool needs approval (e.g. run_shell with approval enabled), the bot shows Approve / Deny buttons — a Telegram inline keyboard or a LINE confirm template. No answer = automatically denied after 120 seconds, so nothing ever hangs.

1. Create a bot with @BotFather and copy the token.
2. Open Settings → Messaging (desktop app or web UI), enable Telegram bot and paste the token.
3. Message your bot once — the "Unauthorized" reply shows your numeric user ID.
4. Add that ID to Allowed user IDs and save. Applies within ~30 seconds — no restart needed (the poller re-reads settings every cycle).

Telegram uses long-polling (getUpdates), which is outbound-only: it works behind NAT and firewalls with no tunnel, no open port, and no webhook.

1. Create a Messaging API channel in the LINE Developers console.
2. In Settings → Messaging, enable LINE bot and paste the Channel secret and Channel access token from the console.
3. Click Start tunnel, then copy the shown Webhook URL (https://<tunnel-host>/line/webhook) into the LINE console under Messaging API → Webhook settings — press Verify and enable Use webhook.
4. Message the bot once — the reply shows your U… user ID; add it to Allowed user IDs and save (LINE settings apply immediately).

Notes: quick tunnels get a new URL every time they start — re-paste the webhook URL into the LINE console after a tunnel restart (the current URL is always shown in Settings → Messaging and at GET /api/messaging/status). Progress updates on LINE are limited to one push per run to conserve the free plan's monthly push-message quota; the final answer is always delivered.

• Fail-closed allow-lists — an empty allow-list rejects everyone; the rejection reply includes the sender's ID so setup is copy-paste.
• Signature-verified LINE webhook — every delivery is authenticated by an HMAC-SHA256 over the raw body (X-Line-Signature, constant-time compared) with your channel secret; the endpoint sits outside bearer auth (LINE can't send your token) and retried deliveries are deduplicated by event id.
• Tunnel control is owner-only — POST /api/messaging/tunnel/{start,stop} is blocked for remote access tokens, since starting a tunnel exposes the host publicly.
• Masked secrets — the bot token, channel secret and access token are masked in GET /api/settings like every other API key.

telegramEnabled · telegramBotToken · telegramAllowedUserIds · lineEnabled · lineChannelSecret · lineChannelAccessToken · lineAllowedUserIds — all editable in Settings → Messaging (desktop and web/mobile UI). Connection state, errors and the LINE webhook URL are reported by GET /api/messaging/status.

TigrimOS can run on any cloud server (AWS, DigitalOcean, Hetzner, etc.) as a headless AI agent backend. You control it from your Mac desktop app, a mobile browser, or any web browser.

curl -sSL https://raw.githubusercontent.com/Sompote/TigrimOSR/main/install-linux.sh | bash

Select "Headless mode" — the installer handles systemd, nginx, firewall, and optional HTTPS.

After install:

sudo systemctl start tigrimos    # start server
sudo systemctl stop tigrimos     # stop server
sudo systemctl restart tigrimos  # restart after config change
sudo journalctl -u tigrimos -f   # view live logs

# SSH into your server
ssh user@your-server-ip

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Clone and build
git clone https://github.com/Sompote/TigrimOSR.git
cd TigrimOSR
cargo build --release

# Run headless — prompts for a security token
./target/release/tigrimos --headless

# Or set token + port via environment variables
ACCESS_TOKEN=my-secret-token PORT=3001 ./target/release/tigrimos --headless

# 1. Install + connect Tailscale on the server, note the 100.x.y.z address
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale ip -4

# 2. Enable VPN + remote token in data/settings.json (or Settings → Remote in the web UI):
#    { "remoteEnabled": true, "remoteToken": "my-secret-token", "vpnEnabled": true }

# 3. (Re)start headless — on boot the log prints the tailnet URL:
#    [VPN] Reachable at http://100.x.y.z:3001
ACCESS_TOKEN=my-secret-token PORT=3001 ./target/release/tigrimos --headless

curl -H "Authorization: Bearer my-secret-token" http://127.0.0.1:3001/api/vpn/status
# → {"running":true,"ip":"100.x.y.z","url":"http://100.x.y.z:3001"}

===========================================
  TigrimOS Headless Mode — Security Setup
===========================================

Enter access token (min 8 chars): ********

Token set. Use this to connect from your Mac or browser.
  Web UI:  http://<server-ip>:3001/web/
  Token:   your-token-here

sudo nano /etc/systemd/system/tigrimos.service

[Unit]
Description=TigrimOS Headless AI Agent Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/TigrimOSR
ExecStart=/root/TigrimOSR/target/release/tigrimos --headless
Environment=ACCESS_TOKEN=my-secret-token
Environment=PORT=3002
Environment=SANDBOX_DIR=/root/TigrimOS/sandbox
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable tigrimos   # start on boot
sudo systemctl start tigrimos    # start now

cd TigrimOSR && git pull origin main && cargo build --release
sudo systemctl restart tigrimos

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 1800s;  # 30 min for long AI tasks
    }
}

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

sudo ufw allow 3001/tcp   # direct access
sudo ufw allow 80/tcp     # nginx HTTP
sudo ufw allow 443/tcp    # nginx HTTPS

• Telegram & LINE bots — Chat with the agent from Telegram or LINE and control it with slash commands: /agents, /model (global switch), /mode and /loop (per chat), /new, /stop (cancels the run and kills its process tree), /status, /help. Non-command text runs through the same pipeline as web chat, so bot conversations appear in the web UI history. See Telegram & LINE Bots.
• Live progress + approvals in chat apps — While the agent works you get throttled progress updates (a single edited status message on Telegram; one quota-friendly push on LINE), then the final answer split safely on UTF-8 boundaries. Tool approvals arrive as Approve/Deny buttons (Telegram inline keyboard / LINE confirm template) with a 120 s default-deny so nothing hangs.
• No-restart Telegram, tunnel-backed LINE — Telegram uses outbound long-polling (works behind NAT, token/enable changes apply within ~30 s without a restart). LINE's webhook (/line/webhook) is verified by an HMAC-SHA256 X-Line-Signature over the raw body (constant-time compare, retry dedupe) and gets its public URL from the Cloudflare tunnel — new owner-only POST /api/messaging/tunnel/{start,stop} endpoints control it, and GET /api/messaging/status reports bot state + the webhook URL to paste into the LINE console.
• Fail-closed access control — Per-platform user allow-lists reject everyone when empty; the rejection reply includes the sender's ID for copy-paste setup. Bot secrets are masked in GET /api/settings like other keys.
• Settings UI on desktop + web — New Settings → Messaging tab in both the native app and the web/mobile UI: enable toggles, tokens, allow-lists, live Telegram connection status, and tunnel Start/Stop with a copyable LINE webhook URL.

• Job evaluation — outer loop with a tool-using judge — New evaluation: section in agent-loop profiles: after the whole job finishes (top-level main agent only — never sub-agents, so a swarm pays for one verification, not one per agent), an LLM judge scores the final result against the user's objective. Unlike the reflection loop's text-only judge, this judge calls read-only tools (read_file, list_files) to verify that claimed files/artifacts actually exist before scoring. Below the threshold, the judge's gap list is injected back and the orchestrator gets bounded extra rounds to delegate targeted fix-up tasks (max_retries judge→fix cycles, max_fix_rounds per cycle), then re-judges.
• Rubric (user success criteria) — An optional per-profile rubric defines binding pass conditions (e.g. "a markdown review with ≥10 papers, each with a DOI, must exist"). Criteria are enforced in the judge's system prompt: any unmet criterion fails the evaluation regardless of how good the answer text looks.
• Dedicated judge model — evaluation.model / api_url / api_key run the judge on a different (cheaper or stronger) model so the agent doesn't grade its own work; empty fields inherit the session model.
• Optional executing judge — allow_execute: true additionally grants the judge run_python/run_shell (e.g. actually run the produced script or tests before passing it); off by default and flagged with a warning on save.
• Visible verdicts — The judge's verification calls appear in the activity log as evaluator:read_file / evaluator:list_files, and the chat shows [evaluation] ✓ Passed — score 0.95/1.0 on success or [evaluation] Score 0.5/1.0 — addressing gaps: … when re-entering the loop.
• UI + API — Global toggle in Settings → AI/API → Agent Harness (Enable job evaluation); full per-profile controls in Settings → Agent Loop → Job Evaluation (Outer Loop) (threshold, retries, judge rounds, judge model, rubric, allow-execute); /api/agent-loops validation rejects out-of-range thresholds and warns on clamped values and allow_execute.
• Backward compatible — Existing reflection_* knobs keep working unchanged (text-only judge, any depth); when both are enabled, the outer evaluation wins at the top level so a job is never judged twice. Existing profiles without an evaluation: section are untouched; evaluation is off by default.

• Agent Loop Profiles (custom agent loop) — Customize the agent loop itself with user-defined YAML profiles in data/agent_loops/: tool allowlist/denylist, MCP server and skill selection, model + system-prompt overrides (append or replace-base), loop knobs (max rounds/tool calls, temperature, max tokens, sub-agent spawn depth, checkpoints) and context compaction (interval, window, token budget, optional cheaper summarization model). Omitted sections inherit the built-in behavior. See Agent Loop Profiles.
• Seeded default.yaml — On first start the server seeds agent_loops/default.yaml from your current settings (a behavior-identical mirror) and selects it as the active profile, so nothing changes until you edit it. A Reset default button regenerates it from live settings.
• Native editor — New Settings → Agent Loop section in the desktop app: form editor with tool/MCP/skill checkboxes, model & prompt fields, loop/verification/compaction controls, plus a raw Edit as YAML mode with typed validate-on-save (bad YAML is rejected with the error inline; unknown tool names surface as warnings).
• Web/mobile editor — New Agent Loop tab in the remote web UI: active-profile picker (saves instantly), YAML editor with server-side validation, create/delete/reset-default, and a catalog listing every tool (protected ones marked), MCP server, and installed skill.
• Verification loops exposed — The reflection loop (an LLM judge scores the final answer against the objective and re-enters the loop with the gap list) and realtime step verification (judge each team agent's finished step, retry failures) are now user-tunable per profile (reflection_enabled / reflection_threshold / max_reflection_retries / step_verification).
• Per-agent overrides in team YAML — Agents in data/agents/*.yaml can carry their own tools:, mcp_servers:, skills:, loop:, compaction:, and system_prompt: fields; spawn_subagent children inherit the parent's profile unless they define their own. Projects can pin a profile via their agent override, and the web chat accepts a per-request agent_loop_profile.
• Safety guarantees — Profiles cannot brick or weaken the system: coordination tools (send_task, wait_result, spawn_subagent, …) are never removed while sub-agents are enabled; tool-approval prompts still apply regardless of profile; over-budget and overflow context compaction stay always-on; checkpoints record the profile and refuse to resume under a different one (no cross-profile transcript hijacking); reasoning-model temperature pinning still wins over profile temperature.
• REST API — New /api/agent-loops endpoints (list/get/save/delete), /api/agent-loops/catalog (tools + MCP servers + skills for editors), and /api/agent-loops/reset-default.

• Web/mobile UI themes — A new Appearance tab in the remote Settings with a one-click theme picker: Light, Dark, Transparent (frosted blur), Vivid, ChatGPT, Minimal, and Teal. Each theme recolors the whole web remote (cards, drawers, modals, inputs) via CSS variables, applies instantly with a live swatch preview, and is remembered per-device in localStorage — so it's applied before first paint with no flash of the default.
• Private VPN for remote connect (Tailscale) — A new opt-in way to reach a host remotely over your own Tailscale tailnet instead of a public Cloudflare tunnel (the two are mutually-exclusive alternatives). Toggle Use VPN (Tailscale) for remote connect in Settings → Remote (web/mobile and desktop); the host then surfaces its private 100.x connect address with a copy button, and binds for tailnet reachability when a remote token is set. Off by default, with Start/Stop/Refresh controls and owner-only /api/vpn/{status,start,stop} endpoints. See Remote access over a private VPN.
• Router mode (routing agentic system) — A new agent mode that triages each request, then routes work across a heterogeneous pool of LLMs. Configure a model pool in Settings → Sub-Agent → Router Model Pool (per-model model, api_url/api_key, tier, and free-text strengths); the orchestrator builds a flat team and assigns each agent the best-fit model by matching its sub-task to the model's strengths/tier. Workers run in parallel, each in its own isolated browser window (no shared-Chrome clobbering), and the orchestrator merges their results. Includes automatic provider failover and Router / Router Ultra tiers (fast vs deep).
• User-set orchestrator model — A free-text Orchestrator model field in the Router Model Pool sets which model does the triaging, team-building and merging (blank = main model; a pool id uses that entry's endpoint/key; any other id runs on the main endpoint/key). Worker agents keep their own per-agent models.
• Per-agent isolated browsers — In a parallel swarm, each sub-agent now drives its own Chromium window via a dedicated Playwright MCP instance (launched on first use), so concurrent agents no longer fight over a single shared page.
• Browser process cleanup — MCP servers now run as their own process group, and a finished or cancelled chat SIGKILLs the whole browser tree (npx → node → Chromium) instead of orphaning Chromium and holding memory. Router chats tear down their per-agent browser windows on completion.
• Reasoning-model temperature fix — Models that only accept the default temperature (e.g. Kimi K2 / MiniMax reasoning models) are auto-pinned to temperature = 1, with a reactive retry if a provider rejects the value.

• Browser control (opt-in) — New Browser Control toggle (desktop Settings → Security, web/mobile Settings → AI / API) lets the agent drive a real Chromium/Chrome browser (navigate, click, type, screenshot, tabs, JS) via Playwright MCP. Off by default for safety; pick the bundled Chromium or your installed Chrome. Auto-runs headless on a headless server, which also prompts to install the browser on first interactive startup. Requires Node.js (npx) and a one-time browser install (npx @playwright/mcp@latest install-browser chrome-for-testing).
• Persistent stdio MCP connections — MCP servers launched over stdio now stay alive across tool calls instead of respawning per call, so stateful servers (like the browser) keep their session — a page opened by one call is still there for the next. Auto-restarts on crash.

TigrimOSR/
├── src/
│   ├── main.rs              # Entry point (GUI + headless mode)
│   ├── ui/
│   │   ├── app.rs           # Main app frame, logo, tab routing
│   │   ├── chat.rs          # Chat UI, streaming, info card, log panel
│   │   ├── agents_view.rs   # Agent architecture canvas, connection editor
│   │   ├── files_view.rs    # Sandbox file browser with image preview
│   │   ├── tasks_view.rs    # Active/Scheduled/Finished/Remote task management
│   │   ├── remote_view.rs   # Remote server dashboard (connect to remote instances)
│   │   ├── settings.rs      # Settings UI with harness parameters
│   │   ├── terminal_view.rs # VM Terminal via SSH
│   │   ├── output_panel.rs  # File output panel (images, MD, CSV, etc.)
│   │   └── skills_view.rs   # Skills browser and ClawHub marketplace
│   ├── server/
│   │   ├── services/
│   │   │   ├── toolbox.rs    # Tool execution + multi-agent loop + CLI providers
│   │   │   ├── compact.rs    # 9-step context compression pipeline
│   │   │   ├── protocols.rs  # TCP, Bus, Queue, Blackboard protocols
│   │   │   ├── clawhub.rs    # ClawHub skill marketplace
│   │   │   ├── mcp.rs        # MCP client (stdio/SSE/HTTP)
│   │   │   ├── plugin.rs     # Zip-based plugin system
│   │   │   └── tunnel.rs     # Cloudflare tunnel management
│   │   ├── routes/
│   │   │   ├── plugins.rs    # Plugin REST API endpoints
│   │   │   ├── remote.rs     # Remote task API endpoints
│   │   │   └── web_ui.rs     # Embedded web UI serving
│   │   └── data.rs           # Data models and persistence
│   └── vm/
│       ├── manager.rs        # QEMU VM lifecycle management
│       └── config.rs         # VM configuration constants
├── PLUGINS.md               # Plugin developer guide
├── static/
│   └── index.html            # Embedded web UI (SPA with KaTeX)
├── data/
│   └── agents/              # YAML agent config files
├── assets/
│   └── icon.png             # App icon
├── skills/                  # Loadable skill modules (SKILL.md)
└── Cargo.toml

• Enter — send message
• Shift+Enter — new line in input

Apache License 2.0 — see LICENSE.