io.github.simonmak-ascent/opencode-workbench

Official10 toolsLive

by simonmak-ascent · TypeScript

Provision an OpenCode workbench and MCP stack on any Linux box, local or over SSH.

io.github.simonmak-ascent/opencode-workbench MCP Server

This server provisions an OpenCode workbench and an MCP stack on Linux systems, either locally or over SSH. It is designed to set up a working environment and connect it to MCP functionality for use from development tooling.

🛠️ Key Features

Provision an OpenCode workbench
Set up an MCP stack
Target environment: any Linux box
Supports local or SSH-based access

🚀 Use Cases

Running an OpenCode + MCP setup on a local Linux machine
Deploying the same stack to a remote Linux host via SSH

⚡ Developer Benefits

Consistent provisioning of an OpenCode workbench alongside an MCP stack across Linux environments

⚠️ Limitations

Scope described only for Linux boxes (local or over SSH); other environments are not indicated

Topics

codespacesdevcontaineragent-skillsai-agentsdevelopment-environmentmcpmcp-servermodel-context-protocolopencoderecoverytypescriptworkstationascent-toolchain

Captured live from the server via tools/list.

describe_workbench

Describe this MCP server from its bundled profile without contacting any target or making a network call: repository URL, the default component set, components grouped by tier (required/core/optional), and optional MCP add-ons. It takes no parameters, is always safe, and returns instantly. Use it first to resolve a component id for install_component/remove_component/update_component or to see available add-ons; use inspect_target for a machine's live state.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

inspect_target

Probe one Linux machine — this host (`local`) or a remote host over SSH (`ssh`) — and report its OS, kernel, architecture, package manager, Node/npm, OpenCode, Docker, and per-tool detection flags, plus the names (never values) of credentials present. Read-only: it runs one shell probe as the target user (over SSH when `mode:ssh`), installs nothing, writes nothing, contacts no external service, and can take a few seconds per hop. Parameter semantics: `target.mode` selects local vs ssh (default `local`); `target.host` is required only for ssh; `target.user` defaults to the ssh config/current user; `target.cwd` sets the directory for relative checks; `target.port`/`identityFile` pass straight to ssh. Use it to see what a clone would touch, then plan_clone to turn that into an ordered plan and apply_clone to perform it.

Parameters1

target

object

required

The machine to operate on: this host (local) or a remote host over SSH (ssh).

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    }
  },
  "required": [
    "target"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

plan_clone

Return a read-only plan for a target: compare it against the Workbench profile and list each component as `install`, `present`, or `manual`, with the commands that would run. It still runs a detection probe on the target (same access as inspect_target) but clones nothing and writes nothing. Parameter semantics: `components` restricts the diff to those ids (default: required+core); `workspace` sets the expected profile path on the target (default `~/opencode-workbench`); `profileUrl` overrides the git remote. Use it to preview before apply_clone, which performs the changes.

Parameters6

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
components	array	optional	Component ids to include; defaults to required+core.
workspace	string	optional	Target directory for the profile repo.
profileUrl	string	optional	Override profile git URL.
skipRepo	boolean	optional	Do not clone/update the profile repo on the target.
dryRun	boolean	optional	Report only; make no changes.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "components": {
      "description": "Component ids to include; defaults to required+core.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "workspace": {
      "description": "Target directory for the profile repo.",
      "type": "string"
    },
    "profileUrl": {
      "description": "Override profile git URL.",
      "type": "string"
    },
    "skipRepo": {
      "description": "Do not clone/update the profile repo on the target.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "Report only; make no changes.",
      "type": "boolean"
    }
  },
  "required": [
    "target"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

apply_clone

Apply the Workbench profile to a target: clone the repo and install missing components (OpenCode CLI, Node/pnpm, MCP servers, skills, plugins, optional Docker). It OVERWRITES `<home>/.config/opencode/opencode.json`, copies `AGENTS.md`, resets an existing profile repo to `origin/main`, and runs global installs that need write permission (plus SSH for `mode:ssh`) and can take minutes. Writes a names-only `~/.env.workbench` (mode 600); never secret values. Consent-gated and idempotent: without `confirm:true` it returns the plan and changes nothing. Parameter semantics: `components` defaults to required+core; `workspace` defaults to `~/opencode-workbench`; `skipRepo` skips the clone/update; `profileUrl` overrides the git remote; `dryRun` returns the plan. To preview only, use plan_clone.

Parameters7

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
confirm	boolean	optional	Set true to actually install. When absent, the call returns a plan and makes no changes.
components	array	optional	Component ids to include; defaults to required+core.
workspace	string	optional	Target directory for the profile repo.
profileUrl	string	optional	Override profile git URL.
skipRepo	boolean	optional	Do not clone/update the profile repo on the target.
dryRun	boolean	optional	Report only; make no changes.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "confirm": {
      "description": "Set true to actually install. When absent, the call returns a plan and makes no changes.",
      "type": "boolean"
    },
    "components": {
      "description": "Component ids to include; defaults to required+core.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "workspace": {
      "description": "Target directory for the profile repo.",
      "type": "string"
    },
    "profileUrl": {
      "description": "Override profile git URL.",
      "type": "string"
    },
    "skipRepo": {
      "description": "Do not clone/update the profile repo on the target.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "Report only; make no changes.",
      "type": "boolean"
    }
  },
  "required": [
    "target"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_clone

Re-check a target after a clone: return a per-component `present`/`missing` list plus whether `opencode.json` and `~/.env.workbench` exist. Read-only and idempotent: it runs a detection probe (SSH or local) and checks files, writing nothing. `target` selects the machine (`local` or SSH) and its `home` is where the `opencode.json` and `~/.env.workbench` checks run; `components` restricts the check to those ids (omit it to check every component, the default); `workspace` sets the profile path used by component checks. Use it after apply_clone and after component changes; for a pre-clone preview use plan_clone.

Parameters6

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
components	array	optional	Component ids to include; defaults to required+core.
workspace	string	optional	Target directory for the profile repo.
profileUrl	string	optional	Override profile git URL.
skipRepo	boolean	optional	Do not clone/update the profile repo on the target.
dryRun	boolean	optional	Report only; make no changes.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "components": {
      "description": "Component ids to include; defaults to required+core.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "workspace": {
      "description": "Target directory for the profile repo.",
      "type": "string"
    },
    "profileUrl": {
      "description": "Override profile git URL.",
      "type": "string"
    },
    "skipRepo": {
      "description": "Do not clone/update the profile repo on the target.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "Report only; make no changes.",
      "type": "boolean"
    }
  },
  "required": [
    "target"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

install_component

Install a single Workbench component by id (e.g. `node`, `opencode`, `npm-mcps`, `skills`) on a target; `component` must be an id from describe_workbench. Overwrites that component's files when present (e.g. `skills`/`plugins` replace the copies under `<home>/.config/opencode`); global installs need write permission and can take minutes. Idempotent and consent-gated: without `confirm:true` it returns the plan. Parameter semantics: `component` is required; `workspace` defaults to `~/opencode-workbench`; `confirm` defaults to false (plan only). Use it for one targeted component; use apply_clone to install the full default set.

Parameters4

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
component	string	required	Component id from describe_workbench.
workspace	string	optional	Target directory for the profile repo.
confirm	boolean	optional	Set true to actually install. When absent, the call returns a plan and makes no changes.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "component": {
      "type": "string",
      "description": "Component id from describe_workbench."
    },
    "workspace": {
      "description": "Target directory for the profile repo.",
      "type": "string"
    },
    "confirm": {
      "description": "Set true to actually install. When absent, the call returns a plan and makes no changes.",
      "type": "boolean"
    }
  },
  "required": [
    "target",
    "component"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_component

Uninstall one Workbench component by id from a target — the inverse of install_component — for a bounded, documented subset with an automated uninstall (e.g. `opencode`, `pnpm`, `npm-mcps`, `skills`, `docker-containers`); `component` must be an id from describe_workbench. Idempotent: an already-absent component reports `absent`; a component with no automated uninstall (system packages such as git/curl/node) reports `manual`. Destructive and consent-gated: without `confirm:true` it returns a preview and changes nothing, and it deletes only that component's files — never `opencode.json` or the profile repo. Parameter semantics: `workspace` sets the profile path some removals need; `dryRun` reports without changing. Use it to tear down one component; for several, call it per id.

Parameters5

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
component	string	required	Component id from describe_workbench.
workspace	string	optional	Profile repo directory (used by components whose removal needs it).
confirm	boolean	optional	Set true to actually remove. When absent, the call returns a preview and makes no changes.
dryRun	boolean	optional	Report the action without changing anything.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "component": {
      "type": "string",
      "description": "Component id from describe_workbench."
    },
    "workspace": {
      "description": "Profile repo directory (used by components whose removal needs it).",
      "type": "string"
    },
    "confirm": {
      "description": "Set true to actually remove. When absent, the call returns a preview and makes no changes.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "Report the action without changing anything.",
      "type": "boolean"
    }
  },
  "required": [
    "target",
    "component"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_component

Update one Workbench component in place by id: re-run its install script to fetch the current version (e.g. `opencode` re-runs the official installer; `npm-mcps` reinstalls the latest globals). It OVERWRITES the component's files, needs write permission, and can take minutes for global installs; the resolved version may change. Parameter semantics: `component` must be an id from describe_workbench; `workspace` defaults to `~/opencode-workbench`; `dryRun` previews; `confirm` defaults to false — set `confirm:true` to apply. For the whole profile use apply_clone.

Parameters5

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
component	string	required	Component id from describe_workbench.
workspace	string	optional	Profile repo directory (used by components whose update needs it).
confirm	boolean	optional	Set true to actually update. When absent, the call returns a preview and makes no changes.
dryRun	boolean	optional	Report the action without changing anything.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "component": {
      "type": "string",
      "description": "Component id from describe_workbench."
    },
    "workspace": {
      "description": "Profile repo directory (used by components whose update needs it).",
      "type": "string"
    },
    "confirm": {
      "description": "Set true to actually update. When absent, the call returns a preview and makes no changes.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "Report the action without changing anything.",
      "type": "boolean"
    }
  },
  "required": [
    "target",
    "component"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_required_credentials

List the credentials the profile references, which the target already provides, and how to acquire each missing one. Value-blind: it reads only whether each env var is set — no values, no network, no writes — via one read-only probe. Parameter semantics: `target` selects the machine (`local` or SSH) and its `home` sets the returned `template` path and the env file the presence check reads; there are no other parameters. Returns `present`/`missing` var-name arrays plus one guidance record per credential (`var`, `purpose`, `url`, `method`, `command`). Use it after plan_clone to see what would degrade; act on one credential with run_auth_flow.

Parameters1

target

object

required

The machine to operate on: this host (local) or a remote host over SSH (ssh).

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    }
  },
  "required": [
    "target"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

run_auth_flow

Return the acquisition plan for one credential on a target: the provider URL, the exact non-interactive command when one exists (e.g. `opencode auth login`, `opencode mcp auth vercel`, `gh auth login`), and whether it is already present. Read-only and value-blind: it emits guidance and re-checks presence with one read-only probe; it does not run the commands or handle secret values. Parameter semantics: `var` must be an env var name returned by list_required_credentials (unknown names error); `target` selects the machine and its `home` is where the value should be written. Use it for a single credential; it does not replace that listing.

Parameters2

target	object	required	The machine to operate on: this host (local) or a remote host over SSH (ssh).
var	string	required	Credential env var name from list_required_credentials (e.g. OPENCODE_API_KEY).

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "local",
            "ssh"
          ],
          "description": "Run on this machine (local) or a remote host (ssh)."
        },
        "host": {
          "description": "SSH host (required when mode=ssh).",
          "type": "string"
        },
        "user": {
          "description": "SSH user (defaults to ssh config / current user).",
          "type": "string"
        },
        "port": {
          "description": "SSH port.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "identityFile": {
          "description": "SSH private key path.",
          "type": "string"
        },
        "cwd": {
          "description": "Working directory on the target.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "description": "The machine to operate on: this host (local) or a remote host over SSH (ssh)."
    },
    "var": {
      "type": "string",
      "description": "Credential env var name from list_required_credentials (e.g. OPENCODE_API_KEY)."
    }
  },
  "required": [
    "target",
    "var"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md13 KBView on GitHub

OpenCode Workbench

A reproducible, self-documenting, and recoverable OpenCode development workstation — configuration, agent skills, MCP stack, and an MCP server that clones the entire setup onto any Linux machine (locally or over SSH).

Homepage & remote MCP: https://opencode-workbench.simonmak.com · POST https://opencode-workbench.simonmak.com/mcp

Overview

This repository is the single source of truth for a complete cloud development workstation. Everything needed to rebuild from scratch is versioned here:

Workstation configuration and automation
OpenCode configuration (model, providers, MCP servers)
Agent skills (45 reusable AI instructions across research, dev, data, science and ops)
Operational prompts (disaster recovery, backup, security)
Recovery procedures (playbook, checklist, gap analysis)
Security governance (secret management, threat model)
OpenCode sandbox (bubblewrap) — run the agent with a read-only system and no secret mounts
opencode-workbench — an MCP server that installs this profile on any Linux box

No important knowledge exists only in human memory.

Clone This Workbench to Another Linux Machine

json

{
  "mcp": {
    "opencode-workbench": {
      "type": "local",
      "command": ["npx", "-y", "@simonmak-ascent/opencode-workbench"],
      "enabled": true,
      "timeout": 600000
    }
  }
}

Then ask the agent to run inspect_target → plan_clone → apply_clone { confirm: true } → verify_clone, for { "mode": "local" } or { "mode": "ssh", "host": "<your-box>", "user": "<your-user>" }. apply_clone is consent-gated: without confirm:true it returns a plan (components + privileged-command preview) and changes nothing. Run list_required_credentials to see which keys the box still needs and how to acquire them, and bash scripts/selftest/run-selftest.sh to verify it works. See mcp-server/README.md and docs/architecture/clone-mcp.md.

The clone is key-resilient: with no model key it still boots on the OpenCode Zen free floor, and MCP servers whose credentials are absent are disabled and reported (not left to fail at runtime).

The connector never reads or transmits secret values; it writes an empty ~/.env.workbench template for you to fill in.

Quick Start (≤ 5 minutes)

Fastest path: no box required — register the MCP server with npx -y @simonmak-ascent/opencode-workbench (config in Clone This Workbench); or provision a fresh box:

bash

# Create a new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# Wait for postCreate (3-5 min) — installs everything automatically
# Then start coding:
opencode

Architecture

flowchart TB
  AGENT["OpenCode agent"] -->|"npx @simonmak-ascent/opencode-workbench"| MCP["opencode-workbench MCP<br/>inspect · plan · apply · verify"]
  REPO[("Git repo — single source of truth")] --> MCP
  MCP -->|"local or SSH"| BOX["Target Linux box"]
  BOX --> PROF["Workstation profile<br/>OpenCode CLI · 35 MCP servers · 45 skills · Docker infra"]

Clone lifecycle

apply_clone is consent-gated: without confirm: true it returns a plan and changes nothing.

sequenceDiagram
    autonumber
    participant A as OpenCode agent
    participant M as opencode-workbench MCP
    participant B as Target box (local or SSH)
    A->>M: inspect_target
    M-->>A: OS, toolchain, Docker, existing config
    A->>M: plan_clone
    M-->>A: components + privileged-command preview
    A->>M: apply_clone { confirm: true }
    M->>B: install components · write ~/.env.workbench template
    B-->>M: result
    A->>M: verify_clone
    M-->>A: pass/fail + missing credentials

MCP tool surface

flowchart LR
    A["OpenCode agent"] --> D["Discovery<br/>describe_workbench · inspect_target"]
    A --> C["Clone<br/>plan_clone · apply_clone · verify_clone"]
    A --> K["Components<br/>install · remove · update_component"]
    A --> S["Credentials<br/>list_required_credentials · run_auth_flow"]

code

opencode-workbench/
├── mcp-server/                     # opencode-workbench: clone this profile onto Linux
│   ├── src/                        # inspect / plan / apply / verify, local + SSH
│   ├── test/                       # unit tests (vitest)
│   └── README.md
├── connector.json                  # MCP connector manifest / registration snippet
├── plugins/                        # memory.ts + doc-tools.ts OpenCode plugins
├── package.json                    # thin launcher for opencode-workbench (bin + prepare)
├── .devcontainer/                  # build box definition & bootstrap
│   ├── devcontainer.json           # Container image, features, ports, remoteEnv
│   ├── setup.sh                    # Post-create: installs opencode, MCPs, Docker infra
│   └── aliases.sh                  # Shell aliases sourced at runtime
├── .opencode/
│   └── skills/                     # 28 custom agent skills (10 research, 10 dev, 8 publishing)
├── vendor/                         # Vendored MCP source code
│   ├── perplexity-agent-mcp/
│   └── browserless-mcp/
├── configs/                        # Reference configurations
│   ├── mcp/                        # MCP server inventory & architecture
│   ├── opencode/                   # OpenCode settings documentation
│   ├── shell/                      # Shell configuration
│   ├── git/                        # Git configuration & hooks
│   └── providers/                  # AI provider configuration
├── docs/                           # Complete documentation system
│   ├── WORKBENCH_CHARTER.md        # Governance: mission, principles, requirements
│   ├── security-model.md           # Security architecture & threat model
│   ├── IMPROVEMENT_BACKLOG.md      # Tracked improvements and fixes
│   ├── CHANGELOG_WORKBENCH.md      # Append-only change history
│   ├── architecture/               # System documentation (incl. clone-mcp.md)
│   ├── recovery/                   # Recovery procedures (4 docs)
│   ├── prompts/                    # Operational prompt library (9 prompts)
│   └── backup-reports/             # Dated backup snapshots
├── scripts/                        # Automation scripts
│   ├── backup/                     # Master backup script
│   ├── inventory/                  # Auto-generate inventories (software, env, MCP, OpenCode)
│   ├── security/                   # Secret pattern scanner
│   ├── recovery/                   # Recovery validation
│   └── maintenance/                # Config sync, routine tasks
├── .github/workflows/              # CI (docs, inventory, gitleaks, mcp-server)
├── opencode.json                   # OpenCode configuration (MCP servers)
├── AGENTS.md                       # OpenCode agent instructions
└── README.md                       # This file

What's Inside

Category	Details
OpenCode	Latest stable CLI, DeepSeek V4 Pro model, LSP enabled
MCP Servers	35 configured (33 enabled, 2 disabled), 9 remote + 26 local
Agent Skills	45 reusable skills in `.opencode/skills/`
Infrastructure	PostgreSQL 16 (Docker), Browserless Chromium (Docker)
Tools	pandoc, jq, miller, sqlite3, GitHub CLI, Playwright Chromium
Prompts	9 operational prompts in `docs/prompts/`

Workstation Governance

This workstation operates under a formal charter. Key principles:

Single Source of Truth: Runtime must match repository. Drift is a bug.
Secrets Never Touch Disk: All secrets flow through the build box Secrets.
Immutable History: Changelog is append-only. Every change is traceable.
Documentation Lives With Code: Docs describe the system as it is, not as imagined.

Read the full charter: docs/WORKBENCH_CHARTER.md

Backup Workflow

bash

# Master backup — full inventory, security scan, commit prep
bash scripts/backup/run-master-backup.sh

# Quick backup — save state before risky operations
bash scripts/maintenance/sync-runtime-config.sh && \
  git diff > /tmp/quick-backup-$(date +%Y%m%d).diff

Or use OpenCode prompts:

docs/prompts/RUN_MASTER_BACKUP.md — execute backup via AI
docs/prompts/QUICK_BACKUP.md — rapid state preservation

Recovery Workflow

Assume the build box is deleted. Only Git repo + build box Secrets survive.

bash

# 1. Create new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# 2. Wait for automation (3-5 min)

# 3. If needed (usually done by setup.sh):
npx playwright install chromium
# Vercel MCP uses VERCEL_ACCESS_TOKEN (token auth — no OAuth step)

# 4. Validate recovery
bash scripts/recovery/validate-recovery.sh

Full details: docs/recovery/RECOVERY_PLAYBOOK.md

MCP Architecture

Type	Count	Notes
Remote	9	context7, gh_grep, vdd, exa, cloudflare, clerk, vercel (token auth), sentry, stripe
Local	26	npm / vendored / binary stdio servers

Totals: 35 configured (33 enabled, 2 disabled: google-search, google-workspace).

See: docs/architecture/mcp-inventory.md

Secrets Management

All secrets stored in the build box Secrets. Never in repository files.

#	Secret	Used By
1	`DEEPSEEK_API_KEY`	OpenCode (primary model)
2	`OPENCODE_API_KEY`	OpenCode Zen / Console Go providers
3	`SIMONMAK_ASCENT_PAT`	GitHub MCP, shadcn MCP, `gh`
4	`PERPLEXITY_API_KEY`	Perplexity MCP
5	`BRAVE_API_KEY`	Brave Search MCP
6	`BROWSERLESS_TOKEN`	Browserless MCP + container
7	`SENTRY_AUTH_TOKEN`	Sentry MCP
8	`VERCEL_ACCESS_TOKEN`	Vercel MCP (token auth)

Additional keys for opt-in servers (EXA_API_KEY, CLOUDFLARE_API_TOKEN, STRIPE_SECRET_KEY, SURREAL_*, ALIBABA_CLOUD_*, AZURE_*, FIRECRAWL_API_KEY, FRED_API_KEY, COMPANIES_HOUSE_API_KEY) are catalogued in docs/architecture/secrets.md — never by value.

See: docs/architecture/secrets.md

Documentation Index

Document	Purpose
`docs/WORKBENCH_CHARTER.md`	Mission, principles, governance
`docs/security-model.md`	Security architecture, threat model, incident response
`docs/IMPROVEMENT_BACKLOG.md`	Tracked improvements and technical debt
`docs/CHANGELOG_WORKBENCH.md`	Complete change history
`docs/architecture/`	System documentation (10 inventory docs)
`docs/recovery/`	Recovery playbook, disaster recovery, checklist, gap analysis
`docs/prompts/`	9 operational prompts with index
`docs/backup-reports/`	Dated backup snapshots

Adding to the Workbench

MCP Server: Add npm package to .devcontainer/setup.sh, add to opencode.json, document in docs/architecture/mcp-inventory.md
Agent Skill: Create .opencode/skills/<name>/SKILL.md, follow naming convention
Tool: Add to scripts/bootstrap-tools.sh
Prompt: Create in docs/prompts/, update prompt-index.md
After any change: Update CHANGELOG_WORKBENCH.md, run master backup

Recovery Score: 94/100

Validated disaster recovery within < 10 minutes using repository + build box Secrets alone.

Use with Context7

Up-to-date OpenCode Workbench documentation is indexed on Context7, so coding agents can pull it into context on demand. With the Context7 MCP server or ctx7 CLI installed, name the library in your prompt:

text

use library /simonmak-ascent/opencode-workbench for API and docs

License

MIT — see LICENSE.

A tool by Simon Mak.

If this saves you time, a ⭐ on GitHub helps others find it.

Install

Tools (10)

describe_workbenchinspect_targetplan_cloneapply_cloneverify_cloneinstall_componentremove_componentupdate_component

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "opencode-workbench": {
      "command": "npx",
      "args": [
        "-y",
        "@simonmak-ascent/opencode-workbench@4.0.1"
      ]
    }
  }
}

io.github.simonmak-ascent/opencode-workbench MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

describe_workbench

inspect_target

plan_clone

apply_clone

verify_clone

install_component

remove_component

update_component

list_required_credentials

run_auth_flow

OpenCode Workbench

Overview

Clone This Workbench to Another Linux Machine

Quick Start (≤ 5 minutes)

Architecture

Clone lifecycle

MCP tool surface

What's Inside

Workstation Governance

Backup Workflow

Recovery Workflow

MCP Architecture

Secrets Management

Documentation Index

Adding to the Workbench

Recovery Score: 94/100

Use with Context7

License

Install

Related servers