Aditya Kuniyil Kattil
The Archive4 min read
agentstypescriptinfralocal

AgentOS

Local-first runtime infrastructure for supervising coding-agent workflows.

Status
Active build
Role
Solo project
Stack
TypeScript · React · Tauri · Rust · Node.js · Git worktrees · Ollama

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 browser and desktop runtime surfaces. The browser bridge simulates native filesystem, command, and worktree operations and uses an in-memory store. It demonstrates the interface and event flow without performing those native operations.

The Tauri desktop backend exposes real git, filesystem, command, and SQLite operations to the shared React frontend. Some presentation and runtime paths remain simulated, so the existence of a desktop command does not mean every UI workflow uses a complete agent loop.

03Runtime engine

Task execution can create a git worktree from HEAD through the Rust bridge. Native command execution checks a fixed allowlist and blocked-pattern list before starting a process. Worktree file-write commands validate paths, and diff inspection and review steps sit around the execution workflow.

The desktop store persists projects, graph nodes and edges, events, sessions, and agent memories. Execution persistence records traces, tool calls, test results, diffs, terminal output, and completion metadata in session data. The orchestrator reads stored projects and events and rebuilds graph-derived runtime projections; this is record hydration, not resumption of a running process.

04Command risk classification

The UI models safe, medium-risk, and blocked commands with review or escalation states. Native execution separately enforces Rust-side policy: blocked substrings are rejected first, then the command must equal an allowed prefix or begin with that prefix followed by a space. Human review does not bypass this native policy.

The fixed native allowlist includes directory inspection, selected git read commands, and test commands. Blocked substrings include rm, sudo, git reset/clean/push, curl/wget, and several shell operators. These are string checks, not a session-scoped permission system or an operating-system sandbox.

05Worktree isolation

Task worktrees provide separate working directories and indexes on branches created from HEAD. They help isolate repository changes for review, but they share the host environment and do not contain every side effect of a command.

The backend exposes worktree removal, and the approved-merge path attempts removal after a successful merge. Failed operations, conflicts, and interrupted sessions still need inspection; the code does not establish a guarantee that every exit leaves no orphaned worktrees.

06Tauri and Rust bridge

The Rust backend exposes git, worktree, filesystem, process, and store operations through Tauri commands. Git operations invoke the git executable from Rust; the React frontend requests those operations through the desktop bridge.

This command boundary centralizes native validation. Path checks on worktree writes and command-policy checks are useful controls, but they do not make the application a hardened sandbox for adversarial code.

07Provider diagnostics and Ollama

Provider diagnostics and readiness checks help distinguish configuration or connectivity failures from task failures. The repository includes Ollama and OpenAI-compatible provider bridges; usable inference depends on the configured endpoint, model, and provider readiness.

Ollama supplies a local model path, while the OpenAI-compatible bridge supports configured remote endpoints. These provider paths coexist with simulated runtime and presentation paths; they should not be read as a guarantee that every displayed workflow is a completed live agent run.

08Known limitations

Browser native operations are simulated. The browser preview does not execute desktop commands or create real worktrees, and its store is not durable. Provider networking is a separate concern from that native-operation boundary.

Persistence is partially integrated. SQLite tables, store commands, session writes, and record hydration are implemented. In-memory live state and simulated runtime paths remain; persisted records do not establish complete session restoration or restart of an interrupted agent process.

Mixed implementation scope. Native operations and provider bridges are implemented alongside partial or simulated orchestration paths. End-to-end behavior depends on which path is active and on local configuration.

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

Key finding

Supervised execution needs controls at several layers: repository separation, command validation, review, and a durable record of what happened. Each control has a different boundary; a worktree alone cannot make an arbitrary command safe.

The Tauri/Rust boundary makes native operations explicit and gives validation a common entry point. Separating persisted records from live runtime state also makes recovery requirements easier to specify without promising that stored history can resume a process.