OpenCode SDK for Workshop

This SDK provides OpenCode for AI-assisted coding within a workshop. The OpenCode binary is sandboxed in the workshop container. Configuration and application data are persisted between workshop updates.

---

Reference workshop

A minimal workshop:

# workshop.yaml
name: opencode
base: [email protected]
sdks:
  - name: opencode
    channel: latest/stable

actions:
  opencode: opencode "$@"

This creates a basic OpenCode environment with an interactive action.

Tracks

Channel	OpenCode
1/stable	1.x
2/stable	2.x
latest/stable	1.x (same revisions as 1/stable)

---

Using the SDK

Prerequisites, project layout

1. No prerequisite SDKs are required.
2. Place your project files in your project directory. No special layout is required; OpenCode works with any codebase.
3. On launch, the SDK configures PATH for the opencode binary. If VS Code is available, the SDK also installs the OpenCode VS Code extension.

Start a coding session

Once the workshop is ready:

workshop shell
opencode

This opens an interactive OpenCode session inside the workshop.

Authenticate with OpenCode

OpenCode stores its configuration in ~/.config/opencode and session data in ~/.local/share/opencode. Both directories are persisted across workshop refresh, workshop stop/start, and workshop restore via the opencode-config and opencode-data mount plugs declared below; no save-state/restore-state hooks are required or used.

To configure API credentials, set the appropriate environment variable inside the workshop. You can pass it using the --env option with workshop run or workshop exec.

MCP OAuth callbacks

Remote MCP servers that use OAuth redirect the browser to a loopback address inside the workshop. The tunnel slot below exposes that listener so a host system plug can forward the browser redirect into the workshop.

See the OpenCode MCP OAuth documentation for the callback and authentication behaviour.

---

Plugs (resources this SDK consumes)

opencode-data

• Interface: mount
• Workshop target: /home/workshop/.local/share/opencode
• Purpose: Persists OpenCode's session data and history between workshop updates.

opencode-config

• Interface: mount

• Workshop target: /home/workshop/.config/opencode

• Purpose: Preserves OpenCode's configuration and credentials between workshop updates. You can also use workshop remount to control its contents on the host. To mount your existing ~/.config/opencode settings into the workshop, stop the workshop first, remount, then start it again:

  workshop stop <workshop-name>
  workshop remount <workshop-name>/opencode:opencode-config ~/.config/opencode
  workshop start <workshop-name>

desktop

• Interface: desktop

• Purpose: Grants the workshop opt-in access to the host desktop session, including the clipboard. Together with the bundled wl-clipboard and xclip utilities, this lets OpenCode's clipboard features reach the host.

• This plug is not connected automatically. Connect it explicitly when you want clipboard access:

  workshop connect <workshop-name>/opencode:desktop

Slots (resources this SDK provides)

opencode-mcp-oauth-callback

• Interface: tunnel
• Workshop endpoint: localhost:19876
• Purpose: Exposes OpenCode's OAuth callback listener so the host can forward a browser redirect into the workshop.

A workshop definition connects it with a matching plug on the system SDK:

sdks:
  - name: opencode
  - name: system
    plugs:
      opencode-mcp-oauth-callback:
        interface: tunnel
        endpoint: localhost:19876

The system plug listens on the host loopback address and forwards the callback to the workshop slot. With matching names and loopback endpoints, Workshop connects the tunnel automatically.

---

Documentation and guidance

• OpenCode repository
• Workshop documentation

---

Community and support

• OpenCode community: OpenCode GitHub Discussions
• Workshop forum: Discourse
• Please review our Code of Conduct before participating.

---

Contributions

All contributions, including code, documentation updates, and issue reports, are welcome!

• See CONTRIBUTING.md for guidelines.
• Open issues or pull requests on the official repository.

---

License and copyright

Copyright 2026 Canonical Ltd.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 (LGPLv2.1) as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

OpenCode is licensed under the MIT License.