Documentation Sync

This page is auto-generated from plugins/adapters/sandbox/README.md. Please edit the in-package README and then run pnpm sync:adapter-docs.

@zhin.js/adapter-sandbox

Zhin.js Sandbox adapter — a WebSocket-based local testing adapter. The browser-side chat UI opens a Sandbox window for debugging in the Remote Console (Host exposes only the Console API).

Features

• Node Host: WebSocket /sandbox
• Browser-side React chat UI
• Supports multiple simultaneous client connections
• No third-party platform account required — works out of the box
• Ideal for local development and plugin debugging

Installation

pnpm add @zhin.js/adapter-sandbox

Dependencies

Plugin Runtime (new, zhin runtime start)

• @zhin.js/adapter — convention-based adapters/sandbox.ts
• @zhin.js/host-http — httpHostToken provided by Root (WebSocket /sandbox + Console HTTP)
• @zhin.js/core — messageGatewayToken / ImRuntime inbound-outbound
• @zhin.js/page + pages/index.tsx — ADR 0046 convention page (definePage; route /sandbox)

Root loads @zhin.js/host-http, ConsoleRuntime, and ClientBuildModuleRuntime at zhin runtime start. Open http://<host>:<port>/console to browse pages. The Sandbox page (route /sandbox, sharing the same path as WebSocket /sandbox: GET opens the page, Upgrade goes to WS) has a built-in chat shell.

The old client/ (register(api) / pageManager.addEntry) is kept only as a reference for the legacy Host stack and is not the Plugin Runtime production entry point.

Legacy Host Stack (removed)

The original legacy plugin packages @zhin.js/host-router (HTTP service) and @zhin.js/host-api (Host-side Console API, addEntry to register Sandbox extensions) have been removed. zhin dev now auto-assembles the Console/HTTP Host via @zhin.js/cli (@zhin.js/host-http + @zhin.js/pagemanager), so no Host plugins need to be installed.

• @zhin.js/client — Remote Console client SDK (UI lives in the zhin-console repo)

The outbound wire only does JSON wrapping; the old segment-mapper (canonical segments) normalization has been lifted to the gateway/core render chain.

Configuration

Recommended (consistent with minimal-bot): plugins.sandbox.endpoints: [] — when the "Sandbox" page is opened in the Remote Console, a bot (e.g., sandbox-xxxx) is auto-created via the /sandbox WebSocket. No need to write context: sandbox in the YAML.

# zhin.config.yml (Plugin Runtime)
plugins:
  sandbox:
    endpoints: []

Optional: if you want a fixed-name offline placeholder bot to appear in the bot list on startup, configure it explicitly:

plugins:
  sandbox:
    endpoints:
      - name: sandbox-bot
        context: sandbox
        owner: sandbox-user

Usage

1. Start the Zhin instance: pnpm dev (the terminal will print the Host address, typically http://127.0.0.1:8086)
2. Open the Remote Console, set the API Base to match the Host address, and set the Token to match http.token / HTTP_TOKEN
3. Send messages for testing on the Console Sandbox page after connecting

Each browser client creates a Sandbox Bot upon connection (named sandbox-xxxx when no fixed name is configured in YAML).

The connection is established via Router.ws("/sandbox") (auto-mounted by the plugin's useContext("router")).

Message Format

Sandbox uses a JSON message format:

{
  "type": "message",
  "id": "msg-001",
  "content": "Hello",
  "timestamp": 1700000000000
}

Use Cases

• Local development and debugging of plugin logic
• Testing commands and AI tool invocations
• Feature verification without depending on external platforms

AI Tools

See agent/skills/sandbox.md for skill documentation (local sandbox debugging constraints).

License

MIT License