OpenCode Embed

This package exposes the Chat, Diff, and Shell Session panels as iframe views. It is a standalone Vite application and is not mounted under the main packages/app development server.

Local smoke test

Install and start the official OpenCode server with the embed origin allowed:

npm install --global opencode-ai
opencode serve --port 4096 --cors http://localhost:4445

Start the embed application from the repository root:

bun run dev:embed

Open http://localhost:4445/host.html, enter a real Session ID, then select a panel. The host page is built with the package and exercises the same postMessage handshake as a production host.

Opening /embed/chat directly only loads the iframe application. It waits for a trusted parent to send oc:bootstrap and is not intended to work as a standalone browser tab.

Host integration

Load ${embedOrigin}/embed/chat?parent_origin=${encodeURIComponent(location.origin)} (the path segment is informational), wait for oc:ready, then send:

frame.contentWindow?.postMessage(
  {
    type: "oc:bootstrap",
    version: 1,
    server: "https://opencode.example.com",
    session: "ses_123",
    panel: "chat", // chat | diff | shell
    authToken: btoa("opencode:password"),
  },
  embedOrigin,
)

The iframe validates both the normalized parent origin and window.parent. Add the embed origin to the OpenCode server CORS allowlist; the Shell panel needs the same origin permission for its PTY WebSocket handshake. In production, use a short-lived credential and configure the embed host with a restrictive frame-ancestors policy.

After bootstrap, the host can send oc:set-session or oc:set-theme messages with version: 1. The server resolves the Session directory from its durable Session lineage, so directory is deliberately not part of the embed interface.

Deploy the build at the root of a dedicated embed origin. Assets use root-relative /assets/* URLs, and the server must rewrite /embed/* navigation to index.html so a refreshed Session route still boots the iframe application.

The published opencode-embed npm package contains only these static Web assets. It does not include an OpenCode executable, install a CLI, or start a server. Run the official opencode-ai distribution separately and pass its URL in oc:bootstrap.server.

Fork seam

@opencode-ai/app/embed is the only App interface consumed by this package. It owns App routing, Provider composition, and server connection construction. Keep protocol and host implementation in packages/embed; do not import App internals from here. This concentrates upstream adaptation in one small module when official routing or Provider structure changes.