Agent OS: A Local-First Harness Around Coding Models

Eric Mono Earthwalker — Fri, 10 Jul 2026 16:48:13 +0000

A coding model can generate code.

That does not mean it can reliably finish software work.

Between a plausible diff and a completed task, a real software agent still needs memory, execution boundaries, verification, recovery, permissions, and delivery infrastructure.

That is the problem I have been exploring through Agent OS, which I have now released as an open-source project.

GitHub:

https://github.com/earthwalker17/agent-os

The model is only one part of the agent

Agent OS is a local-first AI Project Operating System: a harness around coding models.

The core architecture separates two responsibilities.

Main Agent: the brain

The Main Agent handles:

Conversation
Planning
Project memory
Context assembly
Orchestration
Delegation decisions

It cannot edit repository code or execute shell commands.

Coding Agent: the hands

The Coding Agent operates inside one sandboxed project workspace.

It can inspect files, edit code, and run bounded commands, but it cannot modify project memory or access another project’s workspace.

The two sides communicate through summaries and structured artifacts rather than unrestricted shared control.

“Done” must come from verification

Agent OS does not accept the model’s own claim that a task is complete.

A coding run must pass a real build or test command.

It can then:

Launch the application
Walk declared browser flows
Capture screenshots and runtime evidence
Run visual review
Classify failures
Propose or execute a bounded repair pass

Recovery is deliberately limited. The goal is not unlimited autonomy, but controlled progress with evidence and an audit trail.

External actions remain human-controlled

Git pushes, pull requests, deployments, database migrations, and Stripe test-mode operations use explicit preview-and-confirm contracts.

The agent can prepare the operation, but it cannot silently mutate an external system because it inferred that the user probably wanted it.

Testing the system on a real product

To pressure-test the architecture, I used Agent OS itself to build and deploy Pulseboard, a full-stack SaaS, from an empty repository.

The process included real build, runtime, browser, visual, deployment, and database failures. Those failures became the test for whether the system could collect evidence, expose the problem, and recover instead of simply producing a confident success message.

What is included in the first public release

Local filesystem and SQLite-based project state
Structured Markdown memory
Claude, GPT, Gemini, DeepSeek, Kimi, and GLM support
Sandboxed coding execution
Parallel agent teams in isolated workspaces
Command, browser, and visual verification
Typed bounded recovery
GitHub, Vercel, Supabase, and Stripe test-mode connectors
Apache-2.0 licensing
GitHub CI and 832 backend tests
One-command Windows installation

Current limitations

This is an early public release.

The Windows setup is currently the most thoroughly tested. macOS and Linux users need to follow the manual setup instructions. At least one supported model provider API key is required.

Local-first means that project memory, workspaces, credentials, and execution records remain under the user’s control. It does not currently mean that every supported model runs locally.

What I am looking for

I am especially interested in feedback on:

The separation between the Main Agent and Coding Agent
The first-run installation experience
The boundaries of automated recovery
Which internal components should become independent libraries

The repository, architecture documentation, installation guide, and production showcase are available here:

https://github.com/earthwalker17/agent-os

DEV Community: Eric Mono Earthwalker