Manifest Reference

The instrument manifest lives in package.json under the tango.instrument key. It tells Tango how to discover, load, and configure your instrument.

Full example

{
  "tango": {
    "instrument": {
      "id": "tasks",
      "name": "Tasks",
      "group": "Core",
      "runtime": "react",
      "entrypoint": "./dist/index.js",
      "backendEntrypoint": "./dist/backend.js",
      "hostApiVersion": "2.0.0",
      "panels": {
        "sidebar": true,
        "first": false,
        "second": true,
        "right": false
      },
      "permissions": [
        "storage.files",
        "storage.db",
        "storage.properties",
        "sessions",
        "stages.read",
        "stages.observe"
      ],
      "settings": [
        {
          "key": "theme",
          "title": "Theme",
          "type": "select",
          "default": "auto",
          "options": [
            { "label": "Auto", "value": "auto" },
            { "label": "Light", "value": "light" },
            { "label": "Dark", "value": "dark" }
          ]
        }
      ],
      "launcher": {
        "sidebarShortcut": {
          "enabled": true,
          "label": "Tasks",
          "icon": "task",
          "order": 20
        }
      },
      "backgroundRefresh": {
        "enabled": true,
        "intervalSeconds": 30
      }
    }
  }
}

Required fields

id

• Type: string
• Description: Unique identifier for the instrument. Used internally for storage scoping, event routing, and registry lookups.
• Example: "tasks", "my-instrument"

name

• Type: string
• Description: Human-readable name displayed in the Tango UI.
• Example: "Tasks", "My Instrument"

entrypoint

• Type: string
• Description: Path to the built frontend JavaScript bundle, relative to the instrument root.
• Example: "./dist/index.js"

panels

• Type: InstrumentPanelConfig
• Description: Declares which panel slots the instrument uses. At least one must be true.

type InstrumentPanelConfig = {
  sidebar: boolean;
  first: boolean;
  second: boolean;
  right: boolean;
};

Slot	Location in Tango
sidebar	Left sidebar panel
first	Main content area (left)
second	Main content area (right)
right	Right sidebar panel

Optional fields

group

• Type: string
• Default: "Custom"
• Description: Category name for grouping instruments in the UI.

runtime

• Type: "react" | "vanilla"
• Default: "react"
• Description: The rendering runtime. Use "react" for React-based instruments (most common) or "vanilla" for plain DOM manipulation.

backendEntrypoint

• Type: string
• Description: Path to the built backend JavaScript bundle. Only needed if the instrument defines backend actions.
• Example: "./dist/backend.js"

hostApiVersion

• Type: string
• Default: "2.0.0"
• Description: SDK version for forward compatibility.

permissions

• Type: InstrumentPermission[]
• Default: []
• Description: List of capabilities the instrument needs. See Permissions Reference for all valid values.

settings

• Type: InstrumentSettingField[]
• Description: Schema for user-configurable settings. Each field appears in the instrument’s settings panel in Tango.

type InstrumentSettingField =
  | { type: "string"; key: string; title: string; description?: string; required?: boolean; secret?: boolean; default?: string; placeholder?: string }
  | { type: "number"; key: string; title: string; description?: string; required?: boolean; secret?: boolean; default?: number; min?: number; max?: number; step?: number }
  | { type: "boolean"; key: string; title: string; description?: string; required?: boolean; secret?: boolean; default?: boolean }
  | { type: "select"; key: string; title: string; description?: string; required?: boolean; secret?: boolean; default?: string; options: Array<{ label: string; value: string }> };

launcher

• Type: InstrumentLauncherConfig
• Description: Controls the sidebar shortcut button. Without this configuration, the instrument will not appear in the sidebar — it will only be accessible from the Instruments list.

type InstrumentLauncherConfig = {
  sidebarShortcut?: {
    enabled: boolean;    // Show shortcut button
    label?: string;      // Button label
    icon?: string;       // Icon name
    order?: number;      // Sort order (lower = higher)
  };
};

backgroundRefresh

• Type: BackgroundRefreshConfig
• Description: Enables periodic background work when the instrument is suspended (user navigated away). Requires a onBackgroundRefresh hook in the backend. See Background Refresh for full details.

type BackgroundRefreshConfig = {
  enabled: boolean;
  intervalSeconds: number; // minimum 10, default 30
};

Field	Type	Description
enabled	boolean	Enables periodic background refresh when suspended
intervalSeconds	number	How often onBackgroundRefresh is called (min 10, default 30)

Validation

Run bun run validate (or tango-sdk validate) to check your manifest. The validator checks:

• All required fields are present and correctly typed
• At least one panel slot is true
• Source entry point files exist (checks src/ versions of the entry paths)
• All permissions are valid strings
• Settings schema is well-formed (valid types, select options present)