Arbitr Light

Local-first desktop AI farm for designing, running, and monitoring autonomous task workflows.

Agent workflow map

The application includes a visual workflow editor backed by the native Rust core:

• drag, connect, add, and configure agent stages;
• assign a role, model, worker, and system instructions to every stage;
• launch an existing task through planner, executor, tester, and reviewer stages;
• automatically return rejected work to the executor for another iteration;
• pause or resume one active run without stopping the rest of the farm;
• stop a run safely, close its pending permission gates, and return its task to the queue;
• monitor live progress, attempts, verdicts, and the complete run trace;
• persist maps, runs, and run steps in local SQLite storage.

The orchestration state machine can execute real model calls. If a provider has no saved credentials, the workflow remains usable through an explicit simulated fallback and marks those Model I/O records as simulated.

Workflow library

The map builder supports multiple independent routes instead of a single global graph:

• create a new route from the production-ready Delivery Loop template;
• duplicate the current route with its agents, connections, prompts, and result contracts but without run history;
• switch between maps while preserving their own live runs and traces;
• show node, run, and active-run counts directly in the library selector;
• prevent switching with unsaved canvas changes and prevent deletion of the system map or any map with run history;
• keep the catalog, maps, and timestamps in native SQLite storage.

The React Flow editor is loaded as a separate lazy chunk, keeping the main desktop interface responsive when the map screen is not open.

Workflow version control

Every route now has a protected publication lifecycle instead of treating each save as production-ready:

• edit and save a working draft without rewriting the last published route;
• publish immutable numbered versions with a required change note;
• block workflow launches natively while unpublished changes remain;
• browse the release timeline and compare a historical version with the current draft by nodes, edges, name, and description;
• restore any archived version into a new draft while preserving the complete publication history;
• prevent publishing or restoring while a route has an active run;
• migrate existing workflow maps automatically to a published v1 snapshot in local SQLite.

The detailed comparison panel is loaded only when version history is opened, so the canvas remains responsive during normal editing.

Native execution queue

New work is dispatched by the desktop supervisor directly from SQLite:

• bind every queued task to a published workflow and pin its exact version when execution starts;
• order eligible work by high, medium, or low priority and then by schedule/creation time;
• defer execution until an optional local date and time, stored as UTC;
• enforce a persisted global limit of 1–16 simultaneously running tasks;
• promote queued work or make a scheduled item eligible immediately from Queue Control;
• automatically retry failed workflows after a short cooldown while attempts remain;
• resume the last failed stage without discarding completed steps, consumed budgets, or immutable agent/model configuration;
• reject checkpoint retries when the workflow was republished, is currently a draft, or has exhausted its token/cost budget.

Legacy seed tasks continue through the lightweight local worker simulator, while every newly created task uses the selected published agent map.

Workflow preflight

Every saved map is inspected by the native core before a task can spend tokens or enter the execution queue:

• require one planner entry point and one final reviewer;
• detect dead ends, ambiguous forward routes, unreachable stages, and forward cycles;
• allow loops only through a single reviewer rejected transition;
• verify every stage references an existing enabled agent and an enabled provider;
• surface role mismatches and unhealthy provider checks as non-blocking warnings;
• return stable diagnostic codes and node references so the map inspector can jump directly to the broken stage;
• reject start_workflow natively when any blocking diagnostic remains, even if the frontend is bypassed.

The constructor shows READY, PENDING, or BLOCKED, along with expandable error and warning details. Draft maps remain editable and saveable while incomplete.

Execution policies and transitions

Each stage carries native execution limits that are enforced by the desktop supervisor:

• configure from 0 to 5 retries for provider or timeout failures;
• limit every model request to 10–120 seconds;
• cap each stage response at 256–32,768 output tokens across every supported provider;
• assign a 1,000–1,000,000 token budget to each run and show live usage in the run history and trace;
• use the selected task's dollar budget as a native, persisted run-cost ceiling;
• calculate input and output spend independently in integer micro-USD using the assigned agent's editable tariffs;
• snapshot each assigned model, provider, prompt, and tariff when the run starts so later profile edits cannot rewrite its accounting;
• account for initial, tool-continuation, contract-repair, and final model rounds exactly once;
• show token and monetary usage together, then stop before the next model call when either limit is exhausted;
• claim model calls transactionally and hold a process-level database lock so two desktop instances cannot execute the same paid step;
• restore interrupted claims on restart and backfill historical run usage from existing Model I/O logs;
• wait 15 seconds between retries to avoid a tight paid-error loop;
• fail the run terminally and return the task for operator review after the retry budget is exhausted;
• persist retry counters in SQLite and expose them in the live run trace.

Select any connection on the canvas to edit its label and routing condition. default and always form the forward route, while rejected is reserved for the reviewer rework loop. Native validation remains authoritative when the map is saved or launched.

Verified result contracts

Every stage has an editable completion contract instead of relying on an unstructured model answer:

• define observable success criteria and whether evidence is mandatory;
• require specific relative workspace files from executor and tester stages;
• accept only a strict arbitr-result JSON envelope with summary, evidence, artifacts, and an explicit reviewer decision;
• reject traversal paths, missing files, malformed JSON, extra fields, empty evidence, and invalid reviewer decisions;
• ask a configured model to repair an invalid result up to two times, then stop the run for operator review instead of creating an unbounded paid retry loop;
• persist the validated result separately from the raw response and show evidence/file counts in the run trace.

Reviewer routing now uses the validated decision field, so prose such as “approved” cannot accidentally complete a run.

Result Center

Completed and interrupted workflow runs are collected in a dedicated acceptance workspace:

• search the full run index and filter it by accepted, active, or operator-attention states;
• page through the native run catalog without inheriting the live-map snapshot limits;
• inspect the final structured output together with deduplicated evidence and declared workspace artifacts;
• trace every stage, iteration, reviewer verdict, provider retry, token total, and exact run cost;
• preserve the immutable workflow and stage names from the exact published version that produced the result;
• accept a task, continue a failed run from its last checkpoint, or open the related isolated workspace without losing context;
• let the native core expose whether a checkpoint is retryable after validating attempts, capacity, budgets, in-flight calls, and workflow-version safety;
• load the entire interface as a separate application chunk so normal desktop startup remains fast.

Background supervisor

The native Rust core owns task execution independently from the React window:

• a background Supervisor advances the farm and agent workflows while the desktop process is running;
• an atomic execution gate prevents overlapping scheduler cycles during long provider calls;
• active runs and steps remain in SQLite and resume automatically after an application restart;
• a persisted heartbeat records the current desktop session, health state, tick sequence, active runs, paused runs, pending permissions, and safe infrastructure errors;
• Tauri events notify the interface after supervisor changes, while React performs read-only refreshes instead of driving execution;
• the global farm switch stops new cycles but keeps the heartbeat alive so the operator can distinguish a deliberate pause from a crashed runtime.

Agent builder and Model I/O

• create and edit local agent profiles for OpenAI, Anthropic, Google AI, Ollama, or a custom provider;
• assign up to 12 distinct roles to the same model;
• enable or disable agents used by the autonomous queue;
• maintain estimated input and output prices per million tokens, including zero-cost local models;
• select a registered agent and one of its roles directly on the workflow map;
• store request/response logs with task, run, step, provider, model, role, token counts, latency, and calculated cost;
• redact API-key and authorization-like values before writing logs to SQLite.

Local FinOps analytics

The dedicated FinOps workspace turns the native Model I/O journal into an operational cost view:

• compare spend for the last 7, 30, or 90 days without sending telemetry outside the desktop app;
• inspect cost, calls, and tokens by provider, agent, and task;
• track task and active-run budget utilization against persisted monetary limits;
• monitor error rate, average model latency, daily spend, and a 30-day run-rate projection;
• aggregate money as integer micro-USD in Rust so totals do not drift through floating-point rounding;
• load the analytics interface as a separate lazy chunk and keep the primary desktop shell lightweight.

Model providers

• connect OpenAI Responses API, Anthropic Messages API, Google Gemini, local Ollama, or an OpenAI-compatible endpoint;
• keep remote API keys in the operating system Keychain rather than SQLite or frontend storage;
• test every provider from Settings before running a workflow;
• use only HTTPS for remote endpoints and loopback HTTP for a local runtime;
• execute configured stages asynchronously and record response text, token usage, latency, status, and safe provider errors;
• retry provider failures with a short cooldown instead of producing a tight request loop.

Provider credentials are never included in agent profiles, task data, activity text, or Model I/O logs.

Isolated task workspaces

Executor and tester agents can now perform multi-round workspace actions through a provider-neutral JSON protocol:

• read, write, and list UTF-8 files inside a workspace dedicated to one task;
• search workspace text in Rust and inspect repository state with strictly validated git command forms;
• return tool results to the same model for up to three continuation rounds;
• record every model round and tool action with its target, safe output, status, and duration;
• browse generated artifacts and the live tool audit from the Workspace screen.

Paths containing absolute roots, .., symlinks, or system prefixes are rejected. On macOS, Git commands run through sandbox-exec with no network, a 60-second timeout, capped output, an empty environment, and write access restricted to the task workspace. Windows and Linux use the same fixed Git allowlist, canonical workspace boundary, empty environment, disabled hooks/config, capped output, and timeout; Docker remains the hardened cross-platform path for executing project tests and builds.

Container checks

Executor and tester agents can request fixed node_test, node_build, node_lint, rust_test, and rust_check presets. Arbitr Light runs them through Docker with:

• no network, all Linux capabilities dropped, no-new-privileges, a read-only root filesystem, PID/CPU/memory limits, and a 180-second timeout;
• the task workspace mounted read-only and copied into an ephemeral memory-backed directory before package scripts execute;
• fixed Node and Rust images prepared explicitly from Settings rather than arbitrary user-controlled images or commands;
• output redaction, truncation, and the same per-task tool audit as file operations.

Docker Desktop must be running. The Settings screen reports daemon and image readiness and can pull the two required public images. Runtime checks remain offline; third-party packages are supplied through the explicit task dependency cache described below.

Task dependency cache

The Workspace screen can prepare isolated dependency caches for projects that include reproducible lockfiles:

• Node preparation requires package.json and package-lock.json, runs npm ci --ignore-scripts, and stores only node_modules in a task-scoped Docker volume;
• Rust preparation requires Cargo.toml and Cargo.lock, runs cargo fetch --locked, and stores Cargo registry data in a separate task-scoped volume;
• outbound network access exists only during this explicit operator action; model-driven checks mount caches without network and cannot write to the source workspace;
• preparation status, safe output, image, and timestamp are persisted in SQLite and shown per task.

Preparation containers never receive provider keys, Docker credentials, the Docker socket, or writable host paths. Repeated preparations are serialized to prevent concurrent cache corruption.

Operator permission gates

Agents cannot open the network or install packages on their own. When an offline check needs dependencies declared by a trusted lockfile, the agent can submit a scoped Node or Rust preparation request with a reason:

• the current workflow step pauses without losing its run, agent, or iteration context;
• Workspace shows the request, requesting agent, timestamp, and explicit approve/reject controls;
• approval runs the existing isolated cache preparer; rejection performs no external action;
• every request and decision is persisted in SQLite and surfaced in the operator history;
• after either decision, the same step resumes automatically with the operator result included in its next model prompt;
• duplicate pending requests are coalesced and repeated requests are capped per step.

This gate does not give the model access to Docker commands, arbitrary packages, credentials, or writable host paths.

Telegram task board

Each farm can connect one Telegram bot from Settings:

• store the bot token only in the operating system credential vault, under a farm-specific account;
• allow commands from one exact private or group Chat ID and silently ignore every other chat;
• show due, unclaimed queue items with /tasks;
• atomically reserve work with /take AL-…, inspect it with /mine, and return it with /release AL-…;
• remove claimed tasks from both the bot board and the native AI scheduler until they are released;
• prevent the same bot token from being polled by two running farms through an inter-process token lease;
• rate-limit commands, cap Telegram output, validate IDs, and never include the bot token in SQLite, logs, or user-facing network errors.

Create the bot through @BotFather, copy its token into Settings, enter the numeric Chat ID, save, test the connection, and then enable command polling.

Multiple farm instances

The Settings screen contains a farm generator. A generated farm receives:

• its own SQLite database and exclusive process lock;
• its own supervisor, task queue, Telegram credential, workflow state, and workspaces;
• farm-scoped Docker dependency volumes, so equal task IDs cannot share or corrupt caches;
• a separate native process and desktop window;
• a shared lightweight registry that reports which instances are currently running.

The primary farm keeps the existing database location. Generated farm data lives under the application-data farms/<farm-id>/ directory, so processes cannot execute the same run or overwrite one another's workspaces.

Windows builds

Arbitr Light includes Windows icons, WebView2-compatible Tauri configuration, Windows Credential Manager support through the native keyring, Git/Docker executable discovery, and release installers for both NSIS (.exe) and MSI.

The Desktop builds GitHub Actions workflow verifies Rust, TypeScript, and native tests on windows-latest, then publishes both installer formats as the arbitr-light-windows artifact on master, tags, or manual dispatch. Build locally on Windows with:

npm ci
npm run dist:windows

Run locally

npm install
npm run dev

To test the production desktop build:

npm run desktop

To create an installer for the current platform:

npm run dist

MVP architecture

• Tauri 2 provides a compact native desktop shell and secure Rust bridge.
• React + TypeScript + React Flow power the local operator dashboard and node editor.
• Rust + SQLite own the task ledger, agent registry, Model I/O journal, settings, and orchestration state.
• The database uses WAL mode and lives in the operating system's application-data directory.
• React communicates with the native core through typed Tauri IPC commands; browser preview uses an in-memory fallback only.

On macOS the database is stored at:

~/Library/Application Support/ai.arbitr.light/arbitr-light.sqlite3

On Windows it is stored under the current user's application-data directory for ai.arbitr.light. Generated farms are placed in the farms subdirectory on both platforms.

Native core tests

cargo test --manifest-path src-tauri/Cargo.toml

The current tests cover persistence and supervisor recovery across restarts, exclusive execution gates, persisted heartbeats, global and per-run pause behavior, safe run stopping, token and monetary budget enforcement, exact model-cost rounding, indexed FinOps aggregation, multi-role agent profiles, secret redaction, provider URL restrictions and response parsing, strict result-contract validation and persistence, the reject → retry → approve workflow loop, workspace path traversal, command allowlisting, macOS sandbox enforcement, audited file actions, permission-gated workflow pause/resume behavior, atomic Telegram claims, scheduler exclusion, token/chat validation, and isolated farm-directory generation.