Manifest reference

The manifest is the root of an integration: one JSON file, voiceos.integration.json, validated on install and on every reload. Validation errors are flat path: message strings; anything not listed here is rejected or ignored.

The smallest valid manifest

Everything else on this page is optional or a variation of these eight fields:

{
  "schemaVersion": 1,
  "id": "com.you.coffee-tracker",
  "version": "1.0.0",
  "name": "Coffee Tracker",
  "summary": "Log every coffee by voice and glance your habits in the notch.",
  "publisher": { "id": "pub_you", "name": "You" },
  "runtime": { "kind": "local-mcp", "command": "bun", "args": ["server.ts"] },
  "tools": [
    {
      "name": "coffee_stats",
      "description": "Show how much coffee the user has been drinking. Use when the user asks about their coffee habits, count, or stats.",
      "inputSchema": { "type": "object", "properties": {} }
    }
  ]
}

Top level

Field	Type	Required	Rules
`schemaVersion`	`1`	✅	Literal `1`.
`id`	`string`	✅	Reverse-DNS: `/^[a-z0-9]+(\.[a-z0-9-]+)+$/` (e.g. `com.you.coffee-tracker`). Immutable — settings, secrets, and installs hang off it.
`version`	`string`	✅	Semver, `major.minor.patch`. Versions your integration, not the schema.
`name`	`string`	✅	Non-empty display name.
`summary`	`string`	✅	1–140 chars, one line.
`description`	`string`	—	Markdown for the detail page.
`icon`	`string`	—	Folder-relative path (`icon.png`, `icon.svg`).
`homepage`	`string`	—	Must be a valid URL.
`repository`	`string`	—	Must be a valid URL. Shown as a trust signal; never cloned or executed.
`categories`	`string[]`	—	Free-form discovery tags.
`publisher`	`Publisher`	✅	See below.
`runtime`	`IntegrationRuntime`	✅	See below.
`auth`	`IntegrationAuth`	—	Defaults to `{ "kind": "none" }`.
`permissions`	`Permission[]`	—	See below.
`preferences`	`Preference[]`	—	See below.
`tools`	`ToolDefinition[]`	✅	At least one tool.
`intents`	`IntentDefinition[]`	—	Up to 30 optional shortcuts to declared tools. See Fast intents.
`asr`	`{ vocabulary: string[] }`	—	Optional Agent voice recognition hints. See `asr.vocabulary`.

`publisher`

Field	Type	Required	Notes
`id`	`string`	✅	Stable publisher identity — immutable.
`name`	`string`	✅	Display name.
`url`	`string`	—	Must be a valid URL.
`verified`	`boolean`	—	Set by VoiceOS, never by the author.

`runtime`

One of three shapes:

{ "kind": "local-mcp", "command": "bun", "args": ["server.ts"] }
{ "kind": "remote-mcp", "url": "https://mcp.example.com" }
{ "kind": "hosted", "entry": "server.ts" }

Kind	Meaning
`local-mcp`	VoiceOS runs the folder’s command on the user’s machine over stdio. The default; zero infra.
`remote-mcp`	VoiceOS connects to your Streamable-HTTP MCP server and brokers auth.
`hosted`	Reserved — a VoiceOS-operated sandbox, coming with the App Store backend. Declared now so manifests won’t change later.

`auth`

{ "kind": "none" }

{ "kind": "apiKey", "fields": [
  { "key": "API_KEY", "label": "API key", "secret": true,
    "placeholder": "sk-…", "required": true }
] }

{ "kind": "oauth2", "provider": "notion",
  "authorizationUrl": "…", "tokenUrl": "…",
  "scopes": ["read", "write"], "pkce": true }

apiKey fields default to required: true; values are collected via setup fields, stored encrypted, and injected as process.env.<key>. Never persisted in plaintext, never shown to the agent.
oauth2 is in the contract today; the VoiceOS-brokered login flow ships with the managed broker. pkce defaults to true.

`permissions`

All opt-in, all shown to the user at install time:

Permission	Shape	Grants
`network`	`{ "kind": "network", "domains": ["api.example.com"] }`	Egress to the listed domains only. Least privilege — list exactly what you call.
`background`	`{ "kind": "background" }`	Tools with `execution.mode: "background"`. Required for them — see cross-field rules.
`notify`	`{ "kind": "notify" }`	Completion notifications + opening the side notch.
`store`	`{ "kind": "store", "quotaKb": 128 }`	Reserved — per-user encrypted key-value store (no SDK API yet).
`webhook`	`{ "kind": "webhook" }`	Reserved — inbound webhook URL.

`preferences`

Field	Type	Required	Notes
`name`	`string`	✅	`/^[a-zA-Z][a-zA-Z0-9_]*$/`. Convention: `SCREAMING_SNAKE_CASE` — the value is injected as `process.env.<name>`.
`title`	`string`	✅	Label on the setup form.
`description`	`string`	—	User-facing help — say where to get the value.
`type`	`"text" \| "password" \| "boolean" \| "select" \| "number"`	✅	`select` renders a picker, `password` a secure field, `boolean` a toggle.
`required`	`boolean`	—	Preferences default to optional.
`default`	`string \| number \| boolean`	—	A field with a default is never “missing”.
`placeholder`	`string`	—	—
`options`	`{ label, value }[]`	select only	Required and non-empty when `type` is `"select"`.

`tools[]`

Field	Type	Required	Notes
`name`	`string`	✅	`snake_case` starting with a letter, unique within the integration. VoiceOS namespaces it as `<integrationId>.<name>`.
`title`	`string`	—	Short human title for UI.
`description`	`string`	✅	The agent’s routing rule — what it does + when to use it.
`inputSchema`	JSON Schema object	✅	Draft 2020-12. Describe every property.
`execution`	`{ mode, estimatedDurationMs? }`	—	`mode`: `"sync"` (default; return within the turn) or `"background"` (returns a handle; tracked in the side notch, glance card on completion).
`disabled`	`boolean`	—	Default `false`. Keeps the row visible but read-only, removes permission controls, and blocks execution from every caller.
`disabledReason`	`string`	—	Optional explanation for a disabled action; trimmed, 1–200 characters.
`visibility`	`"user" \| "agent"`	—	Default `"user"`. `"agent"` omits the action from human catalogs while retaining agent access under the normal permission policy.
`uiCallable`	`boolean`	—	Default `false`. Allows this app’s result widgets to request the tool; does not bypass `disabled` or confirmation.
`confirmation`	`UiView`	—	Rendered before the handler runs. Required in spirit for anything that acts; must be omitted for pure reads. See UI blocks.

`intents[]`

Intents make short Agent voice or typed requests eligible for a dedicated selector running alongside the normal agent. They reuse declared tools and do not change schemaVersion: 1. See Fast intents for a complete authoring walkthrough and rollout requirements.

Field	Type	Required	Rules
`name`	`string`	✅	Unique within the app; `/^[a-z][a-z0-9_]{0,63}$/`.
`tool`	`string`	✅	Original name of a tool in the manifest’s `tools` array. Background tools are excluded from fast selection.
`description`	`string`	✅	1–1,000 characters describing the action and when it applies.
`utterances`	`Record<string, string[]>`	✅	1–20 BCP-47 language keys (for example `en`, `es`, `ja`); 1–20 nonempty examples per language, at most 500 characters each.
`slots`	`Record<string, IntentSlot>`	—	Inputs extracted from the request; names must refer to tool input properties.
`fixedArgs`	`Record<string, unknown>`	—	Fixed tool input values. The selector cannot override them; final arguments must satisfy the tool schema.
`response`	`Record<string, string>`	✅	1–20 BCP-47 language keys; one nonempty acknowledgement of at most 500 characters per language. Shown after successful execution.
`minConfidence`	`number`	—	Legacy value in `[0, 1]`. Accepted for compatibility and ignored by the selector.

Utterances and responses use single-brace placeholders ({bot}) referring to slots or fixed arguments. Every required slot that is not fixed must appear in every utterance. Each required tool input must be fixed or declared as a required slot. Slot/fixed-argument keys must match /^[A-Za-z_][A-Za-z0-9_]{0,63}$/; __proto__, prototype, and constructor are forbidden.

`IntentSlot`

Field	Type	Required	Rules
`type`	`"string" \| "number" \| "enum"`	✅	Matches the tool input type; `enum` is for strings, and `number` also supports an integer tool input.
`required`	`boolean`	—	Set `true` for a required extracted input.
`values`	`string[]`	For a static enum	1–30 nonempty choices, at most 200 characters each.
`valuesFrom`	`"tool"`	For a dynamic enum	Use with `type: "enum"` and omit `values`. Resolve choices from live tool metadata, falling back to its input-schema enum when metadata for the slot is absent.
`examples`	`string[]`	—	Up to 30 nonempty examples, at most 200 characters each.

Live choices are published under MCP tool metadata _meta["voiceos/intent-slot-values"][slotName]. The SDK exports the key as INTENT_SLOT_VALUES_META_KEY. Resolved lists need 1–30 strings of at most 200 characters each. Invalid or empty lists omit the entire intent. A string enum in the live tool schema also restricts the allowed values; where both sources restrict values, VoiceOS uses their intersection. Publish changed tool metadata with notifications/tools/list_changed. VoiceOS’s optional read-only refresh hint is notifications/voiceos/refresh_intent_values, exported as INTENT_REFRESH_NOTIFICATION_METHOD. See Keeping choices current for the MCP update example and refresh behavior.

`asr.vocabulary`

An optional array of up to 50 nonempty terms, each 1–80 characters after trimming, with no commas or control characters. These are recognition hints for Agent voice commands, not intent slots or tool arguments. They do not affect Dictate mode or typed input, grant transcript access, or modify the user’s dictionary. The host budgets up to 10 unique terms / 1 KiB across enabled apps; provider limits also apply. Put useful terms first and reload after changing the list. See App vocabulary.

Cross-field validation

These fire even when every field parses:

A tool with execution.mode: "background" requires the background permission.
A select preference must declare non-empty options.
An auth field and a preference cannot share a name — they share one config namespace and one env var.
Every {{binding}} in a tool’s confirmation must name a property of that tool’s inputSchema.
A confirmation view may contain at most one widget block, and a widget view may not also contain button/actions blocks.
canvas blocks are rejected in schemaVersion: 1 (reserved for a future sandboxed renderer), and would additionally require a network permission.
role: "custom" buttons/actions are rejected (reserved for a future server round-trip).
Each intent references a declared tool; slots and fixed arguments name its input properties. Every required tool input is fixed or supplied by a required slot, and utterance placeholders cover required extracted slots.

Validating

bunx @voiceos/integration-sdk validate voiceos.integration.json

or in code: validateManifest(json) / validateView(view) from @voiceos/integration-sdk — both return { ok: true, value } | { ok: false, errors: string[] }.

Get started

Building blocks

Custom widgets

Ship it

Reference

The smallest valid manifest

Top level

`publisher`

`runtime`

`auth`

`permissions`

`preferences`

`tools[]`

`intents[]`

`IntentSlot`

`asr.vocabulary`

Cross-field validation

Validating

​The smallest valid manifest

​Top level

​publisher

​runtime

​auth

​permissions

​preferences

​tools[]

​intents[]

​IntentSlot

​asr.vocabulary

​Cross-field validation

​Validating

The smallest valid manifest

Top level

`publisher`

`runtime`

`auth`

`permissions`

`preferences`

`tools[]`

`intents[]`

`IntentSlot`

`asr.vocabulary`

Cross-field validation

Validating