docs/mvp-first.md
Rama main · réplica de lectura del repositorio original.
# MVP-first implementation track
The full architecture is the north star. It is not the first milestone.
## Gate -1 — Adopt, adapt, or build
Evaluate existing products and open-source MCP servers first.
Choose deliberately:
- Adopt if an existing solution already satisfies the requirements.
- Adapt if an existing implementation is close enough.
- Build only when the required combination is missing.
The differentiating first-release target is:
~~~text
ChatGPT Web / compatible MCP client
+ self-controlled Linux host
+ server-side policy
+ Scoped autonomy
+ optional temporary elevation
+ Broker under operator control
~~~
The north-star product is broader: a vendor-neutral multi-node, multi-AI control and communication layer with AI-to-AI delegation. See `vision.md` and `roadmap-multinode-control-plane.md`.
## Gate 0A — Prove the ChatGPT product surface
**Status: completed on 2026-09-28 for the supported integrated OAuth + ChatGPT Web path.**
This gate was required before the privileged product path could be considered validated.
Primary target: ChatGPT Web.
As of 2026-09-26, public OpenAI documentation described narrower plan availability than the operator later observed in practice. Product availability varies by plan, account, surface, region and rollout.
On 2026-10-06, the operator's ChatGPT Plus environment exposed Portico write-capable tools and successfully completed a real scoped write/read/delete proof through the Broker. Treat this as verified evidence for that environment, not as a universal promise for every Plus account.
Choose and validate one supported route:
1. Private development route — a workspace/plan that supports private full MCP write.
2. Plus Web route — use the actual account surface when custom MCP/app access and required write actions are exposed; verify with an audited end-to-end write proof.
3. Protocol-only route — MCP Inspector while the distribution route is unresolved.
### Gate 0A success
Record:
~~~text
target_surface:
target_plan:
integration_route:
read_available:
write_available:
private_or_published:
tested_date:
~~~
The supported route must continue to be revalidated when ChatGPT product surfaces change. If a future target account does not expose custom MCP registration, stop at that product boundary or change only the distribution route. Do not weaken the server.
## Gate 0B — Safe MCP POC
Build the smallest server as an unprivileged user.
Reference implementation: Go + official MCP Go SDK.
Expose only:
~~~text
system.info
file.read_test
file.write_test
~~~
Restrict file access to:
~~~text
/tmp/vps-agent-poc/
~~~
Do not add root, Docker, systemd writes, SQLite, external secrets, Full, approval or generic shell.
### Gate 0B success
- MCP Inspector passes
- the chosen ChatGPT route discovers the tools when available
- read works
- write works when the client/product permits it
- forbidden paths fail
- errors are understandable
- retry/reconnect behavior is safe
## Gate 1 — One typed privileged action
Add the minimal Broker.
~~~text
vps-agent-gateway (non-root)
|
Unix socket
v
vps-agent-broker (privileged)
~~~
Expose:
~~~text
system.info
file.read_test
service.status
service.restart
~~~
service.restart is limited to one disposable or non-critical unit.
Still exclude generic admin shell, Full, approval UI, broad Docker administration and remote audit infrastructure.
### Gate 1 success
The client can inspect, restart and re-check one test service, produce an audit record and fail safely on unauthorized units.
## Gate 2 — Scoped real-stack pilot
Define one explicit Scoped policy for one real stack.
Add only capabilities demonstrated by real need, such as:
~~~text
system.info
file.read
service.status
service.restart
docker.logs
docker.action(restart)
job.status
~~~
Use it for several days and measure:
- task frequency
- success/failure rate
- operator corrections
- false denials
- missing capabilities
- recovery time
Gate 2 passes when Scoped solves useful work without routine elevation.
## Gate 3 — Durability
Add only when needed:
- SQLite owned by Broker
- durable jobs
- infrastructure-generated idempotency identity
- logical resource locks
- systemd credentials / secret references
- stronger structured audit
## Gate 4 — Broader writes
Based on demonstrated need, add:
- file.write / file.patch
- validated configuration updates
- additional typed Docker/systemd actions
- sandboxed shell.exec inside Scoped roots
A generic shell is not a prerequisite for useful operation.
## Gate 5 — Temporary elevation
Only if Scoped is demonstrably insufficient:
- elevation requests
- out-of-band operator approval
- temporary capability leases
- revoke-all
- remote audit anchoring
- Full feature flag
Only after those controls pass should shell.exec_admin be considered.
## Rule
Every new component needs evidence from the previous gate.
Optimize first for this question:
> Can the actual target client safely and reliably complete valuable work on one real server?