# Vision

`pyro-mcp` should become the disposable MCP workspace for chat-based coding
agents.

That is a different product from a generic VM wrapper, a secure CI runner, or
an SDK-first platform.

`pyro-mcp` currently has no users. That means we can still make breaking
changes freely while we shape the chat-host path into the right product.

## Core Thesis

The goal is not just to run one command in a microVM.

The goal is to give a chat-hosted coding agent a bounded workspace where it can:

- inspect a repo
- install dependencies
- edit files
- run tests
- start and inspect services
- reset and retry
- export patches and artifacts
- destroy the sandbox when the task is done

The sandbox is the execution boundary for agentic software work.

## Current Product Focus

The product path should be obvious and narrow:

- Claude Code
- Codex
- OpenCode
- Linux `x86_64` with KVM

The happy path is:

1. prove the host with the terminal companion commands
2. run `pyro mcp serve`
3. connect a chat host
4. work through one disposable workspace per task

The repo can contain lower-level building blocks, but they should not drive the
product story.

## What This Is Not

`pyro-mcp` should not drift into:

- a YAML pipeline system
- a build farm
- a generic CI job runner
- a scheduler or queueing platform
- a broad VM orchestration product
- an SDK product that happens to have an MCP server on the side

Those products optimize for queued work, throughput, retries, matrix builds, or
library ergonomics.

`pyro-mcp` should optimize for agent loops:

- explore
- edit
- test
- observe
- reset
- export

## Why This Can Look Like CI

Any sandbox product starts to look like CI if the main abstraction is:

- submit a command
- wait
- collect logs
- fetch artifacts

That shape is useful, but it is not the center of the vision.

To stay aligned, the primary abstraction should be a workspace the agent
inhabits from a chat host, not a job the agent submits to a runner.

## Product Principles

### Chat Hosts First

The product should be shaped around the MCP path used from chat interfaces.
Everything else is there to support, debug, or build that path.

### Workspace-First

The default mental model should be "open a disposable workspace" rather than
"enqueue a task".

### Stateful Interaction

The product should support repeated interaction in one sandbox. One-shot command
execution matters, but it is the entry point, not the destination.

### Explicit Host Crossing

Anything that crosses the host boundary should be intentional and visible:

- seeding a workspace
- syncing changes in
- exporting artifacts out
- granting secrets or network access

### Reset Over Repair

Agents should be able to checkpoint, reset, and retry cheaply. Disposable state
is a feature, not a limitation.

### Agent-Native Observability

The sandbox should expose the things an agent actually needs to reason about:

- command output
- file diffs
- service status
- logs
- readiness
- exported results

## The Shape Of The Product

The strongest direction is a small chat-facing contract built around:

- one MCP server
- one disposable workspace model
- structured file inspection and edits
- repeated commands in the same sandbox
- service lifecycle when the workflow needs it
- reset as a first-class workflow primitive

Representative primitives:

- `workspace.create`
- `workspace.status`
- `workspace.delete`
- `workspace.sync_push`
- `workspace.export`
- `workspace.diff`
- `workspace.reset`
- `workspace.exec`
- `shell.open`
- `shell.read`
- `shell.write`
- `service.start`
- `service.status`
- `service.logs`

These names are illustrative, not a promise that every lower-level repo surface
should be treated as equally stable or equally important.

## Interactive Shells And Disk Operations

Interactive shells are aligned with the vision because they make the agent feel
present inside the sandbox rather than reduced to one-shot job submission.

They should remain subordinate to the workspace model, not replace it with a
raw SSH story.

Disk-level operations are useful for:

- fast workspace seeding
- snapshotting
- offline inspection
- export/import without a full boot

They should remain supporting tools rather than the product identity.

## What To Build Next

Features should keep reinforcing the chat-host path in this order:

1. make the first chat-host setup painfully obvious
2. make the recipe-backed workflows feel trivial from chat
3. keep the smoke pack trustworthy enough to gate the advertised stories
4. keep the terminal companion path good enough to debug what the chat sees
5. let lower-level repo surfaces move freely when the chat-host product needs it

The completed workspace GA roadmap lives in
[roadmap/task-workspace-ga.md](roadmap/task-workspace-ga.md).

The follow-on milestones that make the chat-host path clearer live in
[roadmap/llm-chat-ergonomics.md](roadmap/llm-chat-ergonomics.md).

## Litmus Test

When evaluating a new feature, ask:

"Does this make Claude Code, Codex, or OpenCode feel more natural and powerful
when they work inside a disposable sandbox?"

If the better description is "it helps build a broader VM toolkit or SDK", it
is probably pushing the product in the wrong direction.