AgentOS

01Problem

Coding agents running autonomously in local environments can make irreversible changes, execute unsafe commands, or corrupt repository state. Existing approaches either sandbox agents so heavily they can't complete real tasks, or give them full filesystem access with no guardrails.

The missing layer is a runtime that gives agents enough freedom to do real work while making the blast radius predictable and the change history inspectable — without constant manual intervention.

02Browser demo vs desktop runtime

AgentOS has two modes. The browser demo is a simulated environment that demonstrates the UI, event flow, and orchestration state using mock agent outputs. No real filesystem operations or git commands are executed in browser mode.

The desktop runtime is a Tauri application with a Rust backend. It executes real git worktree operations, runs commands through the allowlist engine, and manages actual filesystem state. The React frontend is shared between both modes; only the backend differs.

03Runtime engine

Session initialisation creates an isolated git worktree from the current HEAD via the Rust bridge. The agent's commands route through an execution layer that checks against a session-scoped allowlist before invoking any process. File writes are confined to the worktree boundary. Before any commit, a diff inspector reviews changes against the workspace policy.

Orchestration state is event-driven: each agent action (command request, file write, diff review, commit attempt) emits a typed event that drives UI state and is logged to the session trace.

04Command risk classification

Commands are classified into three tiers before execution: allowed (in the session allowlist — executed immediately); reviewed (outside the allowlist but not blocked — surfaced for human approval before execution); blocked (shell patterns that are always rejected regardless of allowlist configuration).

Blocked patterns include recursive deletes outside the worktree, git force-push to protected branches, process termination signals, and network calls to external endpoints. The block list is hardcoded in the Rust layer — it cannot be overridden by session configuration.

05Worktree isolation

Each agent session operates in its own git worktree, created from HEAD at session start. The worktree has a separate index — changes in the session don't affect the main working tree or any other active session.

Cleanup is explicit: the worktree persists until the human review step completes, then is deleted after merge or discard. Sessions do not accumulate orphaned worktrees on clean exit.

06Tauri and Rust bridge

The desktop backend is Rust, exposed to the TypeScript/React frontend via Tauri's IPC bridge. Git operations (worktree create, list, delete, diff, commit) are implemented as Tauri commands — they run in the Rust process, not in a Node subprocess.

This boundary is also a trust boundary: the frontend can only invoke defined Tauri commands, each individually permissioned. It cannot directly execute shell commands or access the filesystem outside the Tauri command surface.

07Provider diagnostics and Ollama

A provider diagnostics panel checks connectivity and model availability for configured LLM backends. For Ollama, it reports model pull status, context window size, and inference latency. For remote providers, it checks API reachability.

Ollama integration allows the agent runtime to use locally served models without an external API dependency. Model selection is configurable per session.

08Known limitations

Browser demo is simulated. The browser mode does not execute real commands or create real worktrees. It demonstrates UI and event flow only — it does not represent the desktop runtime's behaviour on a real repository.

No persistent storage. Session state (traces, allowlists, worktree mappings) is held in memory. Closing the application loses session history. Persistent session storage is not yet implemented.

Limited real integrations. The desktop runtime integrates with Ollama and local git. Remote provider integrations and deeper editor hooks are partial or planned.

Threat model: accidental, not adversarial. The allowlist and worktree isolation address accidental damage and runaway automation, not a hostile agent. This is a deliberate scope decision — adversarial containment requires a different isolation model (microVM, seccomp).

09What I learned