Skip to Foreman tool architecture
ForemanMCP and sandbox-host coordination
Specimen only

Issue #50 · Static architecture specimen

Foreman owns the work.
The Fabric grants the route.
The host runs the sandbox.

One product surface spans ChatGPT, the browser companion, the Greenways Fabric, and an enrolled execution host without passing credentials through or turning Foreman into a shell.

ClientRead-only MCPObserved read/fetch capability
AuthorityApproval requiredExact lease scope is visible
HostMac Studio ready45-minute isolated lease

01 · Client capability

Observed tools, not assumed authority.

A subscription label or successful login never determines what the client can do. Foreman shows the actual advertised tool class and then applies Greenways authority independently.

MCP clientChatGPT Pro custom MCP
Observed
read/fetch
Tool classes
observe
Action state
unavailable

The client may inspect Foreman but cannot be presented as having durable action authority.

MCP clientFull-action MCP workspace
Observed
read and action
Tool classes
observe · act · external-effect
Action state
gated

Client support does not bypass Greenways grants, human approval, or external read-back.

Application hostForeman Desktop, CLI, or browser companion
Observed
application operations
Tool classes
observe · act · external-effect
Action state
gated

The directly enrolled surface uses the same Foreman operations through the selected Fabric authority.

Current reference specimen: ChatGPT Pro custom MCP is presented as an Observe-only connection. The design does not disguise a durable action as fetch.

02 · Foreman tool surface

One application catalogue across every delivery surface.

The installed Foreman package owns these names and schemas. Desktop, CLI, browser companion, and MCP clients consume the same application operations through different capability profiles.

read

Observe

Read current Foreman projections and exact evidence without creating durable work or an external effect.

  • List projectsforeman.projects.list
    projection freshness and project identity
  • Inspect projectforeman.project.get
    project revision and canonical external references
  • List buildoutsforeman.buildouts.list
    projection freshness and evidence summary
  • Inspect buildoutforeman.buildout.get
    buildout revision and causal evidence
  • Inspect work itemforeman.work.get
    work revision and run references
  • List sessionsforeman.sessions.list
    last observation and native reference
  • Inspect sessionforeman.session.get
    last heartbeat and provider evidence
  • List approvalsforeman.approvals.list
    scope, expiry, decision, and authority evidence
  • Inspect approvalforeman.approval.get
    decision record and affected transition
  • List execution choicesforeman.execution.hosts.list
    host generation and advertised capability manifest
  • Inspect execution runforeman.execution.run.get
    run generation, checkpoint chain, and cleanup evidence
  • Read activityforeman.activity.list
    event identity, actor, source, and observation time
  • Read artifactforeman.artifact.get
    digest, producer run, availability, and retention state
Required evidencefreshness, provenance, requested-versus-observed state, bounds, and canonical references
application-transition

Act

Request one bounded Foreman transition through the current Fabric authority.

  • Create buildoutforeman.buildout.create
    created buildout identity and accepted revision
  • Submit workforeman.work.submit
    accepted request, run identity, and durable activity
  • Cancel workforeman.work.cancel
    cancellation owner, time, and downstream state
  • Attach sessionforeman.session.attach
    session/run binding and lease expiry
  • Request sandbox leaseforeman.execution.lease.request
    lease identity, grant intersection, host generation, and expiry
  • Revoke sandbox leaseforeman.execution.lease.revoke
    revocation actor, time, and affected run state
  • Cancel execution runforeman.execution.run.cancel
    cancel result, retained checkpoints, and cleanup status
  • Decide approvalforeman.approval.decide
    decision record, actor, exact scope, and expiry
  • Capture selected outputforeman.output.capture
    artifact identity, digest, and source completeness
Required evidencerequest identity, grant or approval, idempotency, transition result, and retained activity
external-mutation

External effect

Request one separately authorised mutation in GitHub or another external authority.

  • Request external effectforeman.external-effect.request
    submitted or uncertain state plus eventual canonical read-back
  • Inspect external effectforeman.external-effect.get
    external identity, last read-back, and verification state
Required evidenceexact arguments, permission, uncertain outcome, returned identity, and authoritative read-back

03 · Ownership path

Control and data planes meet at the Fabric authority.

Credentials terminate at their own boundary. The browser companion can approve and revoke; large logs and artifacts can travel directly between the Fabric and host after a bounded lease is granted.

  1. 01
    ChatGPT or MCP client

    Owns: prompt context and its own observed tool capability

    Does not own: Foreman state, Fabric authority, browser credentials, or host credentials

  2. 02
    mcp.greenways.ai

    Owns: MCP discovery, OAuth termination, connection selection, versioned tool advertisement, bounded relay, and revocation

    Does not own: projects, buildouts, durable Work, application migrations, sandbox execution, or independent external-effect authority

  3. 03
    Foreman application

    Owns: product operations, projects, buildouts, work, sessions, approvals, artifacts, activity, and truthful state laws

    Does not own: root keys, provider credentials, database handles, a generic shell, or a second Work runtime

  4. 04
    Greenways Fabric

    Owns: identity, authority, application dispatch, host selection, leases, durable Work, connections, evidence, and recovery

    Does not own: provider-specific product meaning or another Foreman schema

  5. 05
    Browser companion · control plane

    Owns: visible-tab binding, human consent, host choice, lease inspection/revocation, selected-output capture, and compact progress

    Does not own: primary durable state, unrestricted page authority, sandbox execution, or bulk log relay

  6. 06
    Execution host · data plane

    Owns: isolated workspace materialisation, bounded execution, progress, artifacts, cancellation, and cleanup

    Does not own: Foreman semantics, MCP credentials, browser cookies, ambient host secrets, or independent GitHub mutation authority

Control planeBrowser companion

Visible tab · consent · host choice · lease inspection · revocation

AuthorityGreenways Fabric

Actor/app/client grant · host generation · Work identity · durable evidence

Data planeExecution host

Exact checkout · isolated run · progress · artifacts · cleanup

04 · Browser consent

Approve the exact sandbox, not a machine.

Scope, shared data, host, network, expiry, and excluded authority remain adjacent to the human decision.

Sandbox lease

Cross-runtime conformance

Approval required
Origin context
Attached ChatGPT Pro session
Requested by
Chris through Foreman companion
Project / buildout
Hara · #838 · direct callable catalogue
Host
Mac Studio
Capabilities
exact checkout · apply candidate patch in sandbox · run bounded tests · return logs and artifacts · clean workspace
Network
GitHub and locked package mirrors
Expiry
45 minutes
Not included
host home directory · browser cookies · provider credentials · SSH agent · GitHub push · merge · deployment · publication

Static review controls. No lease or authority request is sent.

05 · Execution choices and run

The host is selected; the Work run remains canonical.

Foreman presents user choices and evidence. Provider implementation stays expanded or diagnostic, and no host receives independent GitHub authority.

Enrolled personal host

Mac Studio

Isolated project sandbox

ready
Capabilities
exact repository checkout · bounded candidate evaluation · Hara/Rust/JVM/Node tests · artifact return · cleanup
Bounds
8 vCPU · 12 GiB memory · 45 minute lease
Network
GitHub and locked package mirrors
Observed
Expanded implementation

container provider. This is not the normal product label.

Project-approved remote host

Cloud worker

Ephemeral clean-room runner

approval required
Capabilities
exact repository checkout · bounded candidate evaluation · test execution · artifact return
Bounds
4 vCPU · 8 GiB memory · 30 minute lease
Network
No network after setup
Observed
Expanded implementation

remote sandbox provider. This is not the normal product label.

Enrolled personal host

MacBook

Local development host

degraded
Capabilities
repository inspection · bounded test execution
Bounds
battery policy active · no new long runs
Network
GitHub only
Observed
Expanded implementation

local process provider. This is not the normal product label.

Run specimen

Exact revision → tests → artifact → cleanup

  1. Requested

    Foreman recorded the exact work, host profile, inputs, limits, and idempotency key.

  2. Approval required

    The browser companion shows shared data, capability scope, network policy, exclusions, and expiry.

  3. Lease granted

    The Fabric recorded the authority intersection and one request-bound host generation.

  4. Allocating

    The host is materialising an exact repository revision into an isolated workspace.

  5. Running

    Canonical Work is executing through the selected host/store/executor path.

  6. Checkpointed

    Bounded progress, logs, and artifact references are durable without claiming completion.

  7. Completed

    The declared sandbox outcome has exact result evidence; no external GitHub effect is implied.

  8. Cleaned

    The host returned attributable cleanup evidence for the leased workspace.

Recovery states

Difficult outcomes remain first-class.

  • Host unavailable

    Keep the selected host and last observation visible; do not silently reroute.

  • Partial result

    Retain completed checkpoints and name missing output.

  • Run failed

    Show failure stage, retained evidence, and whether cleanup is complete.

  • Cancelled

    Show actor, cancellation time, retained output, and cleanup state.

  • Cleanup uncertain

    The host disappeared before cleanup evidence; keep recovery action explicit.

06 · Product laws

The interface makes the architecture enforceable.

  1. 01

    The installed Foreman package owns tool names and schemas; MCP only transports and advertises them.

  2. 02

    Tool availability comes from actual client and Fabric grants, never a subscription label, provider login, or online route.

  3. 03

    MCP, browser, provider, and execution-host credentials terminate at their own boundaries and are never passed through.

  4. 04

    Foreman requests semantic work operations and never exposes an unrestricted shell, Docker API, filesystem root, database, or native handle.

  5. 05

    The browser companion is the consent and revocation control plane; the Fabric may establish a direct bounded data plane to the host.

  6. 06

    A sandbox lease is bound to one actor, app, project, buildout, work item, run, capability set, host generation, and expiry.

  7. 07

    Sandboxes start without unrelated host files, browser cookies, provider credentials, keychains, SSH agents, or ambient cloud credentials.

  8. 08

    A completed sandbox run or local commit does not prove a GitHub or deployment effect; authoritative read-back remains required.

  9. 09

    Desktop, CLI, browser, and local sandbox operation remain useful when hosted MCP is unavailable.