Skip to content

Operations and support ​

Use this page when something is wrong, or when you need the policy that decides what happens next. It links the self-service symptom guides, the support channels, the recovery procedures, and the security and privacy boundaries.

Before you start ​

  • Record the exact Ensemble, OpenCode, and Node versions, the install method, and the last known-good version.
  • Stop creating new work before a destructive action. Do not delete state, storage, logs, or workspace files to reset a symptom.
  • Decide whether the problem is security-related. A suspected vulnerability goes through the private process in SECURITY.md, never a public issue.
  • Keep evidence local until you have read and redacted it. Never post credentials, conversation content, private paths, or raw logs.

Start with the symptom ​

SymptomStart here
Install fails, the plugin is missing, or /ensemble does not openTroubleshooting
Two Ensemble entries or a duplicate plugin IDTroubleshooting
The header says no workspaceTroubleshooting
Work is stuck, NEEDS YOU, STALLED, or FAILEDTroubleshooting
A native turn produces no reply and then reads NEEDS YOUTroubleshooting
The agent wizard or a turn reports no usable modelTroubleshooting
An upgrade broke the install, or data may be lostIncident runbook
A vulnerability or credential exposure is suspectedSECURITY.md privately

The FAQ covers npm tags, Git installs, Windows, macOS with Herdr, copy-on-select, and no-telemetry diagnostics.

Support ​

Support is best effort through GitHub Issues. There is no paid support, private inbox, or contractual SLA.

  • Support policy: channels, response targets, evidence to include, and redaction rules.
  • Support matrix: supported platforms, OpenCode and Node versions, terminal sizes, and known limitations.
  • Incident runbook: severity, first response, symptom guide, diagnostics, rollback, data recovery, and escalation.
  • Troubleshooting: six common failures and their smallest safe fix.
  • FAQ: install tags, platform boundaries, and diagnostics questions.

Before filing, reproduce on a supported configuration where possible and attach only redacted evidence. An unsupported host or platform may be closed as out of scope with a pointer to the matrix.

Recovery and rollback ​

Roll back the package first. Restore data only when the package rollback is not enough, because a restore can discard newer state.

TaskPage
Export or restore durable state and workspace configBackup and restore
Move a pre-ledger workspace to the native-first releaseUpgrade
Reverse a package upgrade, with state rollback only when requiredPackage rollback
Plan the full operator sequenceOperations

A recovery backup contains conversation content. Keep it private, store it with owner-only permissions, and never attach it to an issue. A package downgrade does not delete state; if the older package cannot read newer rows, stop and use the documented restore path rather than editing storage.

Security and privacy ​

  • Security: threat model, permission-model review, accepted risks, and the private reporting route.
  • Privacy: data classes, the 24-hour Work and 7-day log retention, the ensemble.data-export format, delete, and the AGENTS.md roster disclosure.
  • SECURITY.md: the authoritative vulnerability process. Never open a public issue for a vulnerability.

Ensemble does not replace OpenCode's tool permissions. An Ensemble approval is a workflow decision, not a permanent host grant. Diagnostics are local and user-initiated; there is no telemetry or automatic upload.

Expected result ​

You know which page owns the symptom, whether the configuration is supported, and which recovery action is reversible. You can file a support issue with redacted evidence or report a vulnerability privately without exposing sensitive data.

Next ​

Released under the MIT License.