> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build for VoiceOS

> Add tools to the VoiceOS agent and answer with native cards in the Mac notch.

VoiceOS is a voice assistant that lives in the Mac notch. Users talk, the agent
acts, and answers arrive as **cards in the notch**.

A **custom integration** puts your thing on that surface. You declare tools; the
agent calls them when the user asks; your results render as native cards — or as
[fully custom UI](/integrations/widgets) when you want every pixel. If it has an
API, you can build it: internal dashboards, home automation, your CRM, a coffee
tracker.

<Frame caption="First-party integrations answering in the notch. A custom integration renders on this exact surface.">
  <img src="https://mintcdn.com/voiceos/KVsJZgZq4ypscj2j/images/integrations/gallery-official.png?fit=max&auto=format&n=KVsJZgZq4ypscj2j&q=85&s=4d472003dfdf108cc1f40833ec780c93" alt="Two VoiceOS notch cards side by side: a Gmail inbox card listing three emails with a green New badge, and a Google Calendar card listing the day's three events with times." width="3808" height="1278" data-path="images/integrations/gallery-official.png" />
</Frame>

Think of it like the App Store: **VoiceOS is iOS, your integration is an app.**
One manifest declares what it does (tools), where it runs (runtime), what it
needs (auth and permissions), and how it confirms actions (declarative UI).
VoiceOS wires up the rest. You never touch VoiceOS internals — which is also why
your code can never reach VoiceOS's backend or secrets.

## Pick a path

<CardGroup cols={2}>
  <Card title="Build with AI — no code" icon="sparkles" href="/integrations/quickstart">
    Describe your integration in a sentence. The Integration Studio plans it,
    builds it, designs its cards, and lets you test-drive it live. \~3 minutes.
  </Card>

  <Card title="Build with code" icon="code" href="/integrations/build-with-code">
    A standalone folder with a manifest and a small MCP server. Full control
    over logic, cards, and widgets. \~10 minutes.
  </Card>
</CardGroup>

Both produce the same thing: an integration folder VoiceOS can install.
Studio-built integrations are real folders too — open one in your editor, or
hand it to a coding agent, and keep building.

## What it feels like

Say you built an **ElevenLabs** integration.

<Steps>
  <Step title="The user speaks, and the agent confirms">
    *"Read this in Rachel's voice"* — the agent picks your `generate_speech` tool.
    Because it **acts** (it spends API credits and writes a file), VoiceOS first
    renders the confirmation card you declared in the manifest, before any of your
    code runs.

    <Frame caption="The user edits the arguments; the edited values are what your handler receives.">
      <img src="https://mintcdn.com/voiceos/KVsJZgZq4ypscj2j/images/integrations/elevenlabs-confirm.png?fit=max&auto=format&n=KVsJZgZq4ypscj2j&q=85&s=77db66a04aa42d377007f7a78b2b667e" alt="A 'Generate speech' confirmation card in the notch with an editable Text field reading 'VoiceOS turns your voice into action.', a Voice picker set to Rachel, and Cancel / Generate buttons." width="1952" height="1312" data-path="images/integrations/elevenlabs-confirm.png" />
    </Frame>
  </Step>

  <Step title="Your server runs, your card appears">
    The handler calls the ElevenLabs API and returns JSON. The agent narrates the
    data; the notch shows your card.

    <Frame caption="A glance card — rendered by VoiceOS's own components from three lines of JSON.">
      <img src="https://mintcdn.com/voiceos/KVsJZgZq4ypscj2j/images/integrations/elevenlabs-hero.png?fit=max&auto=format&n=KVsJZgZq4ypscj2j&q=85&s=f003b7bec7ff21f0ca8f1d506e4659d5" alt="The VoiceOS notch showing the prompt 'Read this in Rachel's voice' and an ElevenLabs result card: Voice Rachel, Length 0:07, Saved to narration.mp3, with a green 'Opened in Music' badge." width="1952" height="1162" data-path="images/integrations/elevenlabs-hero.png" />
    </Frame>
  </Step>
</Steps>

Read-only tools skip the confirmation entirely — *"what voices do I have?"* just
answers, instantly, with a card.

## What you can build

|                       |                                                                 |
| --------------------- | --------------------------------------------------------------- |
| **Lookups**           | Dashboards, prices, statuses, schedules — anything with an API. |
| **Actions**           | Send, create, post, open — always behind a confirmation card.   |
| **Trackers**          | "Log my coffee", with stats and charts in the notch.            |
| **Long-running work** | Background tasks that chime and show a card when done.          |
| **Fully custom UI**   | Sandboxed HTML widgets when the built-in blocks aren't enough.  |

## The path through these docs

Read top to bottom and you'll go from nothing to a polished, branded
integration.

1. **[Quickstart](/integrations/quickstart)** — build one with AI, in the app,
   in three minutes.
2. **[How it works](/integrations/how-it-works)** — the architecture in one page.
3. **[Build with code](/integrations/build-with-code)** and
   **[defining tools](/integrations/tools)** — schemas, handlers, background
   execution.
4. **[Result cards](/integrations/result-cards)**,
   **[confirmations](/integrations/confirmations)**,
   **[setup fields](/integrations/setup-fields)** — native UI, the easy way.
5. **[Custom widgets](/integrations/widgets)** and the
   **[Widget Kit](/integrations/widget-kit)** — pixel-level control.
6. **[Branding](/integrations/branding)**, **[testing](/integrations/testing)**,
   **[sharing](/integrations/distribution)** — ship it.
7. **[Reference](/integrations/reference/manifest)** — every field, block, cap,
   and bridge message.

<Note>
  The Integration SDK is in developer preview. The folder contract — manifest,
  MCP server, cards — is stable and versioned (`schemaVersion: 1`). See
  [Limits & stability](/integrations/reference/limits).
</Note>