paperclip/doc/plans/2026-04-08-agent-os-technical-report.md

Agent OS Technical Report for Paperclip

Date: 2026-04-08 Analyzed upstream: rivet-dev/agent-os at commit 0063cdccd1dcb1c8e211670cd05482d70d26a5c4 (0063cdc), dated 2026-04-06

Executive summary

agent-os is not a competitor to Paperclip's core product. It is an execution substrate: an embedded, VM-like runtime for agents, tools, filesystems, and session orchestration. Paperclip is a control plane: company scoping, task hierarchy, approvals, budgets, activity logs, workspaces, and governance.

The strongest takeaway is not "copy agent-os wholesale." The strongest takeaway is that Paperclip could selectively use its runtime ideas to improve local agent execution safety, reproducibility, and portability while keeping all company/task/governance logic in Paperclip.

My recommendation is:

1. Do not merge agent-os concepts into the Paperclip core product model.
2. Do evaluate an optional agentos_local execution adapter or internal runtime experiment.
3. Borrow a few design patterns aggressively:
   • layered/snapshotted execution filesystems
   • explicit capability-based runtime permissions
   • a better host-tools bridge for controlled tool execution
   • a normalized session capability model for agent adapters
4. Do not import its workflow/cron/queue abstractions into Paperclip core until they are reconciled with Paperclip's issue/comment/governance model.

What agent-os actually is

From the repo layout and implementation, agent-os is a mixed TypeScript/Rust system that provides:

• an AgentOs TypeScript API for creating isolated agent VMs
• a Rust kernel/sidecar that virtualizes filesystem, processes, PTYs, pipes, permissions, and networking
• an ACP-based session model for agent runtimes such as Pi, OpenCode, and Claude-style adapters
• a registry of WASM command packages and mount plugins
• optional host toolkits, cron scheduling, and filesystem mounts

The repo is substantial already:

• monorepo with packages/, crates/, and registry/
• roughly 1,200 files just across packages/, crates/, and registry/
• mixed implementation model: TypeScript public API plus Rust kernel/sidecar internals

Architecture notes

1. Public runtime surface

The main API lives in packages/core/src/agent-os.ts and exports an AgentOs class with methods such as:

• create()
• createSession()
• prompt()
• exec()
• spawn()
• snapshotRootFilesystem()
• cron scheduling helpers

This is an execution API, not a coordination API.

2. Virtualized kernel model

The kernel is implemented in Rust under crates/kernel/src/. It models:

• virtual filesystem
• process table
• PTYs and pipes
• resource accounting
• permissioned filesystem access
• network permission checks

That gives agent-os a much stronger isolation story than Paperclip's current "launch a host CLI in a workspace" local adapter approach.

3. Layered filesystem and snapshots

The filesystem design is one of the most reusable ideas. agent-os uses:

• a bundled base filesystem
• a writable overlay
• optional mounted filesystems
• snapshot export/import for reusing root states

This is cleaner than treating every execution workspace as a mutable checkout plus ad hoc cleanup. It enables reproducible starting states and cheap isolation.

4. Capability-based permissions

The kernel-level permission vocabulary is strong and concrete:

• filesystem operations
• network operations
• child-process execution
• environment access

The Rust kernel defaults are deny-oriented, but the high-level JS API currently serializes permissive defaults unless the caller provides a policy. That is an important nuance: the primitive is security-minded, but the product surface is still convenience-first.

5. Host-tools bridge

agent-os exposes host-side tools via a toolkit abstraction (hostTool, toolKit) and a local RPC bridge. This is a strong pattern because it gives the agent explicit, typed tools rather than ambient shell access to everything on the host.

6. ACP session abstraction

The session model is more uniform than most agent wrappers. It includes:

• capabilities
• mode/config options
• permission requests
• sequenced session events
• JSON-RPC transport through ACP adapters

This is directly relevant to Paperclip because our adapter layer still normalizes each CLI agent in a fairly bespoke way.

Paperclip anchor points

The most relevant current Paperclip surfaces for any future agent-os integration are:

• packages/adapter-utils/src/types.ts
  • shared adapter contract, session metadata, runtime service reporting, environment tests, and optional detectModel()
• server/src/services/heartbeat.ts
  • heartbeat execution, adapter invocation, cost capture, workspace realization, and issue-comment summaries
• server/src/services/execution-workspaces.ts
  • execution workspace lifecycle and git readiness/cleanup logic
• server/src/services/plugin-loader.ts
  • dynamic plugin activation, host capability boundaries, and runtime extension loading
• local adapters such as packages/adapters/codex-local/src/server/execute.ts and peers
  • current host-CLI execution model that an agent-os runtime experiment would complement or replace for selected agents

What Paperclip can learn from it

1. A safer local execution substrate

Paperclip's local adapters currently run host CLIs in managed workspaces and rely on adapter-specific behavior plus process-level controls. That is pragmatic, but weakly isolated.

agent-os shows a path toward:

• running local agent tooling in a constrained runtime
• applying explicit network/filesystem/env policies
• reducing accidental host leakage
• making adapter behavior more portable across machines

Best use in Paperclip:

• as an optional runtime beneath local adapters
• or as a new adapter family for agents that can run inside ACP-compatible agent-os sessions

This fits Paperclip because it improves execution safety without changing the control-plane model.

2. Snapshotted execution roots instead of only mutable workspaces

Paperclip already has strong execution-workspace concepts, but they are repo/worktree-centric. agent-os adds a stronger "start from known lower layers, write into a disposable upper layer" model.

That could improve:

• reproducible issue starts
• disposable task sandboxes
• faster reset/cleanup
• "resume from snapshot" behavior for recurring routines
• safe preview environments for risky agent operations

This is especially interesting for tasks that do not need a full git worktree.

3. A capability vocabulary for runtime governance

Paperclip has governance at the company/task level:

• approvals
• budgets
• activity logs
• actor permissions
• company scoping

It has less structure at the runtime capability level. agent-os offers a clear vocabulary that Paperclip could adopt even without adopting the runtime itself:

• fs.read, fs.write, fs.mount_sensitive
• network.fetch, network.http, network.listen, network.dns
• child process execution
• env access

That vocabulary would improve:

• adapter configuration schemas
• policy UIs
• execution review surfaces
• future approval gates for governed actions

4. Typed host tools instead of shelling out for everything

Paperclip's plugin system and adapters already have the beginnings of a controlled extension surface. agent-os reinforces the value of exposing capabilities as typed tools rather than raw shell access.

Concrete Paperclip uses:

• board-approved toolkits for sensitive operations
• company-scoped service tools
• plugin-defined tools with explicit schemas
• safer execution for common actions like git metadata inspection, preview lookups, deployment status checks, or document generation

This aligns well with Paperclip's governance story.

5. Better adapter normalization around sessions and capabilities

Paperclip's adapter contract already supports execution results, session params, environment tests, skill syncing, quota windows, and optional detectModel(). But much of the per-agent behavior is still adapter-specific.

agent-os suggests a cleaner normalization target:

• a standard capability map
• a consistent event stream model
• explicit mode/config surfaces
• explicit permission request semantics

Paperclip does not need ACP everywhere, but it would benefit from a more formal internal session capability model inspired by this.

6. On-demand heavy sandbox escalation

One of the best architectural choices in agent-os is that it does not pretend every workload fits the lightweight runtime. It has a sandbox extension for workloads that need a fuller environment.

Paperclip can adopt that philosophy directly:

• lightweight execution by default
• escalate to full worktree / container / remote sandbox only when needed
• keep the escalation explicit in the issue/run model

That is better than forcing all tasks into the heaviest environment up front.

What does not fit Paperclip well

1. Its built-in orchestration primitives overlap the wrong layer

agent-os includes cron/session/workflow style primitives inside the runtime package. Paperclip already has higher-level orchestration concepts:

• issues/comments
• heartbeat runs
• approvals
• company/org structure
• execution workspaces
• budget enforcement

If Paperclip copied agent-os cron/workflow/queue ideas directly into core, we would likely duplicate orchestration across two layers. That would blur ownership and make debugging harder.

Paperclip should keep orchestration authoritative at the control-plane layer.

2. It is not company-scoped or governance-native

agent-os is runtime-first, not company-first. It has no native concepts for:

• company boundaries
• board/operator actor types
• audit logs for business actions
• issue hierarchy
• approval routing
• budget hard-stop behavior

Those are Paperclip's differentiators. They should not be displaced by runtime abstractions.

3. It introduces meaningful implementation complexity

Adopting agent-os deeply would add:

• Rust build/runtime complexity
• sidecar lifecycle management
• new failure modes across JS/Rust boundaries
• more packaging and platform compatibility work
• another abstraction layer for debugging already-complex local adapters

This is justified only if we want stronger local isolation or portability. It is not justified as a general refactor.

4. Its security model is not a drop-in governance solution

The permission model is good, but it is low-level. Paperclip would still need to answer:

• who can authorize a capability
• how approval decisions are logged
• how policies are scoped by company/project/issue/agent
• how runtime permissions interact with budgets and task status

In other words, agent-os can supply enforcement primitives, not the control policy system itself.

5. The agent compatibility story is still selective

The repo is explicit that some runtimes are planned, partial, or still being adapted. In practice this means:

• good ideas for ACP-native or compatible agents
• less certainty for every CLI agent we support today
• real integration work for Codex/Cursor/Gemini-style Paperclip adapters

So the main near-term value is not universal replacement. It is selective use where compatibility is strong.

Concrete recommendations for Paperclip

Recommendation A: prototype an optional agentos_local adapter

This is the highest-value experiment.

Goal:

• run one supported agent type inside agent-os
• keep Paperclip heartbeat/task/workspace/budget logic unchanged
• evaluate startup time, isolation, transcript quality, and operational complexity

Good first target:

• pi_local or opencode_local

Why not start with Codex:

• Paperclip's Codex adapter is already important and carries repo-specific behavior
• agent-os's Codex story is present in the registry/docs, but the safest path is to validate the runtime on a less central adapter first

Success criteria:

• heartbeat can invoke the adapter reliably
• session resume works across heartbeats
• Paperclip still records logs, summaries, cost metadata, and issue comments normally
• runtime permissions can be configured without breaking common tasks

Recommendation B: adopt capability vocabulary into adapter configs

Even without using agent-os, Paperclip should consider standardizing adapter/runtime permissions around a vocabulary like:

• filesystem
• network
• subprocess/tool execution
• environment access

This would improve:

• schema-driven adapter UIs
• future approvals
• observability
• policy portability across adapters

Recommendation C: explore snapshot-backed execution workspaces

Paperclip should evaluate whether some execution workspaces can be backed by:

• a reusable lower snapshot
• a disposable upper layer
• optional mounts for project data or artifacts

This is most valuable for:

• non-repo tasks
• repeatable routines
• preview/test environments
• isolation-heavy local execution

It is less urgent for full repo editing flows that already benefit from git worktrees.

Recommendation D: strengthen typed tool surfaces

Paperclip plugins and adapters should continue moving toward explicit typed tools over ad hoc shell access. agent-os confirms that this is the right direction.

This is a good fit for:

• plugin tools
• workspace runtime services
• governed operations that need approval or auditability

Recommendation E: do not import runtime-level workflows into Paperclip core

Paperclip should not copy agent-os cron/workflow/queue concepts into core orchestration yet.

If we want them later, they must map cleanly onto:

• issues
• comments
• heartbeats
• approvals
• budgets
• activity logs

Without that mapping, they would create a second orchestration system inside the product.

A practical integration map

Best near-term fits

• optional local adapter runtime
• runtime capability schema
• typed host-tool ideas for plugins/adapters
• snapshot ideas for disposable execution roots

Medium-term fits

• stronger session capability normalization across adapters
• policy-aware runtime permission UI
• selective ACP-inspired event normalization

Poor fits right now

• moving Paperclip orchestration into agent-os workflows
• replacing company/task/governance models with runtime constructs
• making Rust sidecars a mandatory dependency for all local execution

Bottom line

agent-os is useful to Paperclip as an execution technology reference, not as a product model.

Paperclip should treat it the same way it treats sandboxes or agent CLIs:

• execution substrate underneath the control plane
• optional where the tradeoff is worth it
• never the source of truth for company/task/governance state

If we do one thing from this report, it should be a narrowly scoped agentos_local experiment plus a design pass on capability-based runtime permissions. Those two ideas have the best upside and the lowest architectural risk.