> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.meetstream.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.meetstream.ai/_mcp/server.

# MIA Screen Share, Bot Desktop and Your Own Agent

MIA can now do more than talk. In a Google Meet call, MIA can **share its screen**, open a web page and work with it the way a person at a keyboard would. It can **present its own desktop** with a spreadsheet, a document, a code editor or a terminal, and it can **post in the meeting chat**. You can also make **your own agent** (Claude Code, Codex, Hermes, GitHub Copilot CLI and others) the brain behind MIA. Your agent runs on your computer with your own login, and MIA handles joining the call, listening and speaking.

This guide covers:

1. [Screen tools](#1-screen-tools): MIA presents a web page and reads, clicks, types, scrolls and looks at it.
2. [Bot desktop](#2-bot-desktop): MIA presents its own desktop and works in apps.
3. [Meeting chat and quiet behaviour](#3-meeting-chat-and-quiet-behaviour): MIA reads the chat, acts without narrating, and speaks only when asked.
4. [Your agent](#4-your-agent-bring-claude-code-codex-and-more): bring Claude Code, Codex and other agent CLIs into the meeting.
5. [Complete examples](#5-complete-examples)
6. [Limits](#6-limits-and-good-to-know) · [Troubleshooting](#7-troubleshooting) · [FAQ](#8-faq)

Applies to: **Google Meet** for screen tools and the bot desktop. **Google Meet, Zoom and Microsoft Teams** for your own agent and meeting chat input.
Support: docs.meetstream.ai · API: api.meetstream.ai

> **New to MIA?** Start with the [MIA Reference](/guides/mia/what-is-mia) and the [Create Agent Guide](/guides/mia/create-an-agent). This guide assumes you already know how to create an agent and send it to a meeting with `agent_config_id`.

---

## At a glance

| Feature | How to turn it on | Platforms | Mode |
|---|---|---|---|
| Screen tools (share a web page, read, click, type, scroll, look, post to chat) | `agent.tools: ["screen"]` | Google Meet | Realtime and pipeline (vision-capable model) |
| Keyboard and mouse on the shared screen | Included with screen tools | Google Meet | Realtime and pipeline |
| Bot desktop (spreadsheet, document, code editor, terminal) | `agent.desktop: true` **and** `agent.tools: ["screen"]` | Google Meet | Realtime and pipeline |
| Read the meeting chat | `agent.chat_input: true` | Google Meet, Zoom, Microsoft Teams | Realtime and pipeline |
| Act without narrating | `agent.quiet_actions: true` | Google Meet, Zoom, Microsoft Teams | Realtime and pipeline |
| Speak only when asked | `agent.speak_only_when_asked: true` | Google Meet, Zoom, Microsoft Teams | Pipeline only |
| Your own agent (Claude Code, Codex, …) | `model.provider: "local_agent"` + the MeetStream Agent Kit | Google Meet, Zoom, Microsoft Teams | Pipeline only |

Each of these is **off** unless you turn it on, so existing agents behave exactly as before.

---

## How it fits together

```
 People in the meeting
        │  voice + chat
        ▼
 MeetStream bot  ──────────────►  Shared screen (web page or bot desktop)
        │                                   ▲
        │  live audio, chat                 │  screen tools
        ▼                                   │
     MIA  ── speech-to-text ──► brain ──────┘
        ▲                         │
        └──── voice / chat ◄──────┘

 brain = a model you configure in MIA (OpenAI, Anthropic, Google, xAI)
         or YOUR agent on your computer (Claude Code, Codex, …) via the Agent Kit
```

MIA hears the meeting, turns speech into text, and passes each turn to the brain. The brain answers, and can call **tools**: screen tools, chat, your MCP servers and your custom functions. MIA carries out each tool call in the meeting and speaks or posts the reply.

---

## 1. Screen tools

With screen tools on, MIA can present a web page into a Google Meet call and use it like a person:

- *"Mia, share the pricing page on meetstream.ai."*
- *"Scroll down. What does the Enterprise plan include?"*
- *"Click Contact sales and type my email."*
- *"Go to the next slide."*
- *"Send that table in the chat."*

### Turn it on

Add `"screen"` to `agent.tools`. The agent's model must be able to see images (see [Supported models](#supported-models)).

```json
"agent": {
  "tools": ["screen"]
}
```

In the dashboard: **Agents → your agent → Tools → Screen tools**.

> **Tip:** `agent.tools` is the same list that holds the built-in tools. To keep them, list them together, for example `["screen", "current_time"]`.

### The tools MIA gets

| Tool | What MIA can do |
|---|---|
| `screen_share` | Start presenting. MIA opens a page someone named or pasted, or a page it was asked to build (HTML). With no page, it shows a ready screen and waits to be told what to open. |
| `screen_stop` | Stop presenting. Only when someone asks. |
| `screen_open` | Open a web page in the presentation. Only a page someone named or pasted, never one MIA picks on its own. |
| `screen_read` | Read the page: title, visible text and a numbered list of clickable elements. MIA uses this to read content aloud and before clicking. |
| `screen_click` | Click an element by its number from `screen_read` or by its visible text. On the desktop, it can also click a point (x, y) or double-click. |
| `screen_type` | Type text, optionally into a specific element and optionally pressing Enter afterwards. |
| `screen_scroll` | Scroll up, down, to the top or to the bottom, by a page, half a page or a line. |
| `screen_key` | Press keys like a real keyboard: `ArrowRight` for the next slide, `PageDown`, `Space`, `Escape`, `Enter`, `Tab`, `F5`, and combinations like `ctrl+c` or `alt+Tab`. Keys can be repeated (for example five slides forward) or held. |
| `screen_mouse` | Use the mouse at a point on the 1280×720 screen: move, hover, click, double-click, right-click, middle-click, press and release, or scroll the wheel. Modifier keys like `shift` or `ctrl` can be held. |
| `screen_drag` | Drag from one point to another, for example to select text or cells. |
| `screen_look` | Take a picture of the shared screen and answer a question about how it looks (charts, images, layout). For plain text, `screen_read` is faster. |
| `meeting_share_look` | Look at the screen **a participant** is sharing and answer a question about it. Read-only. |
| `send_chat_message` | Post in the meeting chat right away: MIA's own words, the exact text of the shared page, and/or a screenshot of it. |

The desktop tools `screen_app_open` and `screen_write_file` are covered in [Bot desktop](#2-bot-desktop).

### What a session looks like

```
Priya:  Mia, can you share the MeetStream docs?
MIA:    (starts presenting docs.meetstream.ai)
Priya:  Open the Create Bot page and read me the required fields.
MIA:    (opens the page, reads it)
        "The required fields are meeting_link and ... "
Priya:  Scroll to the example and post it in the chat.
MIA:    (scrolls, posts the example text in the meeting chat)
Priya:  Thanks, you can stop sharing.
MIA:    (stops presenting)
```

### How MIA picks pages

MIA opens only pages that someone **named or pasted for it**. It never opens a page it picked up from other people's conversation, and it never chooses one on its own. This stops anyone in the meeting from making MIA present something it shouldn't.

### Posting to the chat

`send_chat_message` can post three things, together or apart:

- **Text:** MIA's own words, such as a summary, an answer or a link.
- **Page text** (`include_page_text`): the exact text of the page being shared, pasted as is.
- **Screenshot** (`attach_screenshot`): a picture of the shared page.

If the meeting's chat does not accept images (for example, a guest bot in some Google Meet calls has a text-only chat), the text is still sent. MIA posts a link to the screenshot that stays valid for one hour instead. If the chat is restricted to the host's organization, MIA is told that images are not possible.

### Supported models

Screen tools need a model that can see images. The API rejects `"screen"` on other models.

| Mode | Provider | Models that work with screen tools |
|---|---|---|
| Realtime | `openai` | The `gpt-realtime` family (for example `gpt-realtime`, `gpt-realtime-mini`) |
| Realtime | `google` | `gemini-*` |
| Pipeline | `openai` | `gpt-4o`, `gpt-4.1`, `gpt-5` and `gpt-6` families, `o3`, `o4-mini` (not audio, realtime, transcribe, TTS or search variants) |
| Pipeline | `anthropic` | `claude-*` (for example `claude-haiku-5-5`, `claude-sonnet-5-5`) |
| Pipeline | `google` | `gemini-*` (not TTS or embedding models) |
| Pipeline | `xai` | `grok-4` and vision models |
| Pipeline | `local_agent` | Your own agent. Screenshots are sent to your agent as images. |

When MIA uses `screen_look` or `meeting_share_look`, the picture is described with your own provider key (the same key the agent uses).

### Example: create an agent with screen tools

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Demo Presenter",
    "mode": "pipeline",
    "model": {
      "provider": "anthropic",
      "model": "claude-sonnet-5-5",
      "system_prompt": "You are Mia, a product demo assistant. When asked, share and walk through web pages. Keep spoken answers short.",
      "first_message": "Hi, I am Mia. Ask me to share any page."
    },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "voice": { "provider": "elevenlabs", "voice_id": "<YOUR_ELEVENLABS_VOICE_ID>" },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"]
    }
  }'
```

Then send it to a Google Meet call:

```bash
curl -X POST https://api.meetstream.ai/api/v1/bots/create_bot \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_link": "https://meet.google.com/abc-defg-hij",
    "bot_name": "Mia",
    "agent_config_id": "<YOUR_AGENT_CONFIG_ID>"
  }'
```

---

## 2. Bot desktop

The bot desktop gives MIA its own computer screen to present. MIA can open apps, write and run code, fill in a spreadsheet, and switch smoothly between a web page and the desktop in the same Meet presentation.

- *"Mia, open a spreadsheet and put in last quarter's numbers: January 120, February 135, March 150. Add a total."*
- *"Write a Python script that prints the first ten Fibonacci numbers and run it."*
- *"Open a document and draft the three action items we just agreed."*

### Turn it on

Set **both** `agent.desktop: true` and `agent.tools: ["screen"]`:

```json
"agent": {
  "tools": ["screen"],
  "desktop": true
}
```

Bots for desktop agents are started on machines with the desktop installed, so no other setting is needed when you create the bot. Agents without `desktop: true` never get the desktop tools.

### Desktop apps and tools

`screen_app_open` opens an app on the desktop (and starts presenting the desktop if needed):

| App | What it is |
|---|---|
| `calc` | Spreadsheet. A tab moves to the next cell, a new line moves to the next row, and a cell starting with `=` is a formula. |
| `writer` | Document. |
| `editor` | Code editor, with a built-in terminal tab. |
| `terminal` | A shell with `python3`. No internet access. |

`screen_write_file` writes a whole file at once into the `~/work` folder and opens it in the code editor. MIA uses this to write code instead of typing it key by key, then runs it in the terminal.

`screen_share` can also start straight on the desktop: `desktop_app` set to `calc`, `writer` or `editor`, or `desktop` for an empty desktop.

All the other screen tools (`screen_type`, `screen_key`, `screen_mouse`, `screen_drag`, `screen_click`, `screen_look`, …) work on the desktop too. Mouse positions are in pixels of the 1280×720 screen.

### What a session looks like

```
Alex:  Mia, write a Python script that checks if a number is prime, and run it on 97.
MIA:   (presents the desktop, writes ~/work/prime.py, opens it in the editor,
        opens the terminal and runs: python3 prime.py)
       "97 is prime."
Alex:  Open a spreadsheet with our three plans and their monthly prices.
MIA:   (opens the spreadsheet and types the table)
Alex:  Go back to the pricing page.
MIA:   (switches the same presentation back to the web page)
```

### Safety of the desktop

- The desktop apps have **no network access**.
- The desktop is started only when MIA first presents it, and it is removed when the bot leaves.
- Everything runs inside the bot, which is deleted after the meeting. Nothing on your own computer is touched.

---

## 3. Meeting chat and quiet behaviour

Three optional switches change how MIA uses the chat and its voice. They work well with screen tools and with your own agent.

| Field | Default | What it does |
|---|---|---|
| `agent.chat_input` | `false` | MIA reads the meeting chat. |
| `agent.quiet_actions` | `false` | MIA carries out actions without narrating them. |
| `agent.speak_only_when_asked` | `false` | MIA acts on clear requests, but talks only when someone addresses it by name and asks a question or asks it to say something. Pipeline only. |

All three must be `true` or `false` when present.

### `chat_input`: MIA reads the chat

Each chat message reaches MIA as *"[chat from NAME]: text"*.

- MIA **replies or acts** only when the message is for it: the message names MIA (the bot name or a wake word), or someone just told MIA out loud to expect something in the chat (*"Mia, I'll paste the link in the chat"*).
- Every other message, **including a bare pasted link**, is added to the conversation as context and gets no reply. A pasted link is not a request, so nobody can make MIA present a page just by pasting it.
- When a request comes from the chat, MIA answers in the chat, not out loud.

```
(chat)  Sam:  Mia, what's the link to the API reference?
(chat)  Mia:  https://docs.meetstream.ai/...
```

### `quiet_actions`: act without narrating

MIA stops saying "Okay, opening it now…" or "Done!". After a successful action it stays silent unless it was asked to read, describe or answer something. It still speaks when an action fails.

```
Without quiet_actions:              With quiet_actions:
  "Sure! Let me share that now."      (shares the page)
  (shares the page)
  "I've shared the page for you."
```

Actions covered: share, stop, open, click, type, scroll, key, mouse, drag, open app, write file, and send chat message.

### `speak_only_when_asked`: speak only when addressed

For a quiet assistant that works in the background:

- MIA hears every turn and **acts on clear requests** right away (*"share the pricing page"*).
- It **speaks only when addressed by name**: its name or a wake word in the turn, or a follow-up within 30 seconds of that. A question without its name (*"can you hear me?"*) gets no answer.
- *"Mia, stop talking"* (or *"shut up"*, *"be quiet"*) ends that window at once.
- It does not confirm actions out loud.

```
"Mia, send hi in the chat."       → posts "hi" in the chat, says nothing
"Mia, what's the heading?"        → "The heading says Pricing."
"What's the heading?" (no name)   → stays silent
```

Requirements and cost:

- **Pipeline mode only.** The API rejects it in realtime mode.
- The wake-word gate is not used in this mode, so the model runs **on every turn** instead of only after the wake word. Expect more model usage.
- With this option on, screen and chat actions are refused unless MIA was addressed by name.

### Example

```json
"agent": {
  "response_modality": "audio",
  "tools": ["screen"],
  "chat_input": true,
  "quiet_actions": true,
  "speak_only_when_asked": true
}
```

---

## 4. Your agent: bring Claude Code, Codex and more

Make **your own agent CLI** the brain of MIA. Your agent keeps its model, its prompts, its tools and access to your files. MIA keeps the meeting side: joining the call, speech-to-text and voice.

- Your agent runs **on your computer**, signed in with **your own subscription**.
- MeetStream **never sees your agent's login** and charges **no model tokens** for its replies.
- Everyone in the meeting can hear your agent answer, and it can use the meeting through MIA's tools: post in the chat, share its screen and more.

Good uses:

- *"Claude, what does the `create_bot` handler do when the meeting link is invalid?"* with your agent reading your own repository during a design review.
- A standup where your agent answers questions about open branches and recent changes.
- A demo where your agent shares a page and walks through it while you talk.

### Supported agents

| Agent | `--agent` | Fast warm session | Meeting tools (chat, screen, …) | Sign in again with |
|---|---|---|---|---|
| Claude Code | `claude` | Yes | Yes | `claude auth login` |
| Codex CLI | `codex` | Yes | Yes | `codex login` |
| Hermes Agent | `hermes` | Yes | Yes | `hermes setup` |
| GitHub Copilot CLI | `copilot` | Yes | Yes | `copilot login` |
| Muse Code | `muse` | Yes | Yes | sign in when `muse` asks |
| OpenClaw | `openclaw` | Yes | Text only | `openclaw models auth login` |
| Antigravity CLI | `agy` | Yes | Text only | `agy acp --login` |
| Any other CLI | `--command '...'` | One run per turn | Text only | — |

A warm session keeps one agent process running for the whole meeting, so answers start in about a second instead of waiting for the agent to start on every turn.

### How a turn works

```
Meeting audio ─► MIA speech-to-text ─► your tunnel (HTTPS) ─► Agent Kit bridge ─► your agent
                                                              (127.0.0.1 on your computer)
Meeting ◄─ MIA voice (starts on the first sentence) ◄──────── answer streams back as it is written
```

1. **When the bot starts joining**, the bridge starts one session of your agent for that meeting and warms it up with a short test turn, so no one waits later.
2. **When someone talks to MIA**, the words go to your agent as text. The answer streams back, and MIA starts speaking the first sentence while your agent is still writing the rest.
3. **When someone interrupts**, the bridge stops your agent at once and keeps the conversation, so the next question still has the context.
4. **When your agent calls a meeting tool** (for example `send_chat_message` or `screen_share`), MIA runs it in the meeting and sends the result back, and your agent continues the same turn. Wake words, quiet actions, speak only when asked, and interruptions all still apply.

### What you need

- macOS or Linux, with Python 3.10 or newer.
- One supported agent, installed and signed in.
- A MeetStream account with a speech-to-text provider and a voice provider set up for MIA.

### Step 1: Install and run the Agent Kit

The bridge is the open-source **MeetStream Agent Kit** ([github.com/meetstream-ai/agent-kit](https://github.com/meetstream-ai/agent-kit)). It uses only the Python standard library.

```bash
uv tool install meetstream-agent-kit
meetstream-agent-kit
```

Or with pipx: `pipx install meetstream-agent-kit`. Or download the single file `meetstream-agent-kit.pyz` from the [latest release](https://github.com/meetstream-ai/agent-kit/releases/latest) and check it against `SHA256SUMS`:

```bash
curl -fsSLO https://github.com/meetstream-ai/agent-kit/releases/latest/download/meetstream-agent-kit.pyz
curl -fsSLO https://github.com/meetstream-ai/agent-kit/releases/latest/download/SHA256SUMS
shasum -a 256 --check --ignore-missing SHA256SUMS
python3 meetstream-agent-kit.pyz --help
```

The guided setup asks a few questions:

1. **Which agent should answer.** It lists the agents it finds on your computer and checks that each is signed in.
2. **The folder your agent works in**, for example your project's repository.
3. **The most access this computer allows** (see [Access levels](#access-levels)).
4. **How MeetStream reaches your computer:**
   - **Cloudflare quick tunnel:** no account needed. The address changes each time it starts.
   - **ngrok:** needs a free ngrok account. A free static domain keeps one address.
   - **An address you already have**, for example a named Cloudflare tunnel.

It runs one short test turn with your agent and asks **Start now?** On yes, it starts the bridge and the tunnel and prints the two values to paste into MeetStream:

```text
Paste these in the MeetStream dashboard:
  Pairing token  (Integrations > Models > Local agent, shown once):  msak_…
  Bridge URL     (Agents > your agent > Model > Your agent):          https://….trycloudflare.com
```

Next time, run `meetstream-agent-kit` and press Enter to start with the same answers. Leave the window open while you want your agent available in meetings.

> **Prefer to run each piece yourself?**
> ```bash
> meetstream-agent-kit pair --agent claude --label "my laptop"
> meetstream-agent-kit serve --agent claude --workdir ~/code/my-project --tunnel cloudflare
> ```
> Use `--tunnel ngrok`, or leave out `--tunnel` and run your own, for example `cloudflared tunnel --url http://127.0.0.1:8787`.

### Step 2: Save the pairing token in MeetStream

In the dashboard, open **Integrations → Models → Local agent**, paste the pairing token and save. The token is shown only once on your computer and is stored encrypted by MeetStream, like any other provider key. It is never stored in the agent configuration.

### Step 3: Point your MIA agent at your bridge

**In the dashboard:** open the agent, go to **Model**, choose **Your agent** as the provider, and paste the Bridge URL. Set the access level, the display label and the activation code, then click **Test connection**. Save the agent first: the test uses the saved settings.

**With the API:** use pipeline mode with `model.provider: "local_agent"`:

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Claude in the meeting",
    "mode": "pipeline",
    "model": {
      "provider": "local_agent",
      "model": "haiku",
      "local_agent": {
        "url": "https://<your-tunnel-host>",
        "label": "Claude Code",
        "access": "readonly",
        "require_code": true,
        "timeout_s": 120
      }
    },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "voice": { "provider": "elevenlabs", "voice_id": "<YOUR_ELEVENLABS_VOICE_ID>" },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"],
      "chat_input": true,
      "quiet_actions": true
    }
  }'
```

- `model.model` is optional. It is passed to your agent's own model setting (for example `haiku` for Claude Code). Leave it out, or use `default`, to keep your agent's default.
- `model.system_prompt` is optional. Your agent has its own instructions, and MIA adds its meeting rules.
- `transcriber` and `voice` are required: MIA still does the listening and speaking.

### Step 4: Send the bot to a meeting

```bash
curl -X POST https://api.meetstream.ai/api/v1/bots/create_bot \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_link": "https://meet.google.com/abc-defg-hij",
    "bot_name": "Claude",
    "agent_config_id": "<YOUR_AGENT_CONFIG_ID>"
  }'
```

There is nothing else to do per meeting. Keep the bridge and the tunnel running.

### Activation code

The activation code is **on by default** (`require_code: true`). Your agent answers nobody until you prove you are at your computer:

1. When the bot joins, MIA posts in the meeting chat: *"I'm off until activated. To use Claude Code, paste the 6-digit code it shows on your computer here in the chat."* (The name comes from your `label`.)
2. The bridge shows a 6-digit code in its terminal and as a desktop notification. MeetStream never sees the code before it is pasted.
3. Whoever pastes the code in the chat becomes the **owner for that call**. The owner is tied to their participant id, not their display name. Only the owner can start a turn. What others say still reaches your agent, as context with the owner's next turn.
4. If the owner leaves, MIA locks again and the bridge shows a new code.

Limits:

- Each code works once and is valid for 5 minutes.
- After 3 wrong codes a new code is shown. After 12 wrong codes MIA stays off for the rest of the call.
- Only chat messages that contain a 6-digit number are checked as codes.

To turn it off, set `"require_code": false` and list `owner_names` (or `owner_ids`) instead. Only those people can then start a turn.

> **Note:** Display names can be copied by guests. Use the activation code for anything beyond reading.

### Access levels

What your agent may do on your computer during a meeting. The levels mean the same for every agent; the bridge maps each one to that agent's own controls.

| Level | `access` | Your agent may | Claude Code | Codex | ACP agents (Hermes, Copilot, Muse, OpenClaw) |
|---|---|---|---|---|---|
| **Read-only** (default) | `readonly` | Read and search the work folder | Read, Grep, Glob only | Read-only sandbox | Permission requests denied |
| **Ask me first** | `confirm` | Act after you answer `y` in the bridge terminal. No answer in 20 seconds means no. | Asks per tool | On-request approvals | Permission requests asked |
| **Full** | `full` | Act without asking | Edits and shell | Workspace-write sandbox (the work folder) | Permission requests allowed |

**Your computer has the final say.** `serve --max-access` sets the highest level your computer allows. The setting in MeetStream can only **lower** it for an agent, never raise it. A leaked API key or a dashboard change can never give anyone more access than you allowed on your computer.

- **Full** needs an id-based owner: the activation code (default), or `owner_only: true` with `owner_ids`. Display names never count. Without that, the bridge drops the meeting to **Ask me first**, and the API rejects `access: "full"`.
- Antigravity and custom commands cannot ask before acting, so **Ask me first** runs them read-only. A custom `--command` always runs with your own permissions.

```bash
# Allow at most "ask me first" on this computer, whatever the agent config asks for
meetstream-agent-kit serve --agent claude --max-access confirm --workdir ~/code/my-project
```

### `model.local_agent` reference

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | Yes | — | Your bridge's public address (the tunnel). Must be `https://`, with no username or password in it. Up to 300 characters. |
| `label` | string | No | — | Your agent's name in the meeting chat, for example `"Claude Code"`. Up to 40 characters. |
| `access` | string | No | `"readonly"` | `"readonly"`, `"confirm"` or `"full"`. Can only lower the level your computer allows. `"full"` needs `require_code`, or `owner_only` with `owner_ids`. |
| `require_code` | boolean | No | `true` | The activation code. See [Activation code](#activation-code). |
| `owner_only` | boolean | No | `true` | Only the owner can start a turn. Others are still heard, as context. |
| `owner_names` | array of strings | When `require_code` is `false` (or `owner_ids`) | `[]` | Display names allowed to talk to your agent. Up to 10, each up to 100 characters. |
| `owner_ids` | array of strings | When `require_code` is `false` (or `owner_names`) | `[]` | Meeting participant ids allowed to talk to your agent. Up to 10. |
| `timeout_s` | number | No | `120` | The longest one answer may take before MIA gives up on it. 10–600 seconds. |

Rules for the rest of the config:

- `mode` must be `"pipeline"`.
- `transcriber` and `voice` are required.
- `model.model` and `model.system_prompt` are optional.
- `agent.tools: ["screen"]` is allowed: screenshots from `screen_look` and `meeting_share_look` go to your agent as images.

### Test the connection

The dashboard's **Test connection** button calls:

```bash
curl "https://api.meetstream.ai/api/v1/mia?agent_config_id=<YOUR_AGENT_CONFIG_ID>&check=local_agent" \
  -H "Authorization: Token <YOUR_API_KEY>"
```

```json
{
  "local_agent": {
    "status": "ok",
    "latency_ms": 251,
    "agent": "claude",
    "label": "my laptop",
    "login": "ok",
    "max_access": "readonly",
    "warm": true
  }
}
```

| `status` | Meaning | Fix |
|---|---|---|
| `ok` | The bridge answered and your agent is signed in. | — |
| `login_expired` | Your agent's login has expired. | Run your agent's sign-in command (see [Supported agents](#supported-agents)). |
| `not_installed` | The bridge cannot find your agent CLI. | Install it, or start the bridge with `--binary <path>`. |
| `no_token` | No pairing token is saved. | Save it under Integrations → Models → Local agent. |
| `token_rejected` | The bridge rejected the saved token. | Pair again and save the new token. |
| `unreachable` | The bridge or its tunnel is not running, or the URL is not a MeetStream bridge. | Start `serve` and the tunnel, and check the URL matches the tunnel's current address. |
| `bad_url` | The URL is not a public `https://` address. | Use your tunnel's public HTTPS address. |
| `not_local_agent` | The agent does not use `local_agent`. | — |

### When your agent's login expires

- The login is checked when you pair, when the bridge starts, and each time a meeting starts.
- If it is missing or expired, the bridge shows a desktop notification with the one-line fix (for example `claude auth login`). MIA sends an `agent_error` with code `local_agent_login_required` to your webhooks and the dashboard, and posts **one** chat line with the same fix once the meeting is live. Then it stays silent.
- MIA checks again every 30 seconds and carries on by itself once you have signed in again.
- There is no fallback model. MeetStream never answers in your agent's place.

### Security

- The bridge listens on **127.0.0.1 only**. Your tunnel is the only way in.
- Every request from MIA needs your **pairing token**. The token is shown once, and only its SHA-256 hash is kept on your computer (in `~/.config/meetstream-agent-kit`, readable only by you). `meetstream-agent-kit revoke <id>` makes it stop working at once.
- Meeting tools reach your agent on a **separate secret for each meeting**, never on a command line.
- Everything said or typed in the meeting reaches your agent as **untrusted text**, labelled by speaker, with standing rules: never reveal secrets, never run destructive commands, never act for anyone but the owner.
- Tokens, secrets and request headers are never logged.
- Your agent's login never leaves your computer.

### Agent Kit commands

| Command | What it does |
|---|---|
| *(no command)* or `setup` | Guided setup: a few questions, a test turn, then start the bridge and tunnel and print the token and Bridge URL. |
| `pair [--agent NAME] [--label TEXT]` | Create a pairing token (shown once) and check your agent's login. |
| `list` | List pairings. |
| `revoke ID` | Revoke a pairing. Its token stops working at once. |
| `serve [options]` | Run the bridge for MIA. |
| `doctor [options]` | Check this computer and explain each fix. |
| `bench [options]` | Time cold and warm turns for your agent. |

`serve`, `doctor` and `bench` take `--agent`, `--command`, `--binary`, `--workdir`, `--owner`, `--model`, `--effort` and `--timeout`. `serve` also takes `--port`, `--max-access` (`readonly`, `confirm` or `full`), `--no-prime` (skip the warm-up turn) and `--tunnel` (`cloudflare`, `ngrok`, `url` or `none`) with `--tunnel-url` for an ngrok static domain or your own address. Every command has `--help`.

> **Tip for fast replies:** a small model at low effort answers fastest, for example Claude Code with `--model haiku --effort low`. Run `meetstream-agent-kit bench --agent claude --model haiku --effort low` to time your own setup.

---

## 5. Complete examples

### Example A: Product demo presenter (screen tools, quiet)

A realtime agent that presents pages and walks through them, without narrating each click.

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Demo Presenter",
    "mode": "realtime",
    "model": {
      "provider": "openai",
      "model": "gpt-realtime-mini",
      "voice": "coral",
      "system_prompt": "You are Mia. You present web pages during product demos. Open only pages people name or paste. Keep answers under two sentences."
    },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"],
      "chat_input": true,
      "quiet_actions": true
    }
  }'
```

In the meeting:

```
"Mia, share meetstream.ai."
"Click Pricing."
"Scroll to the FAQ and read the first question."
"Post a screenshot of this in the chat."
```

### Example B: Live coding on the bot desktop

A pipeline agent that writes and runs code on its own desktop.

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Coding Buddy",
    "mode": "pipeline",
    "model": {
      "provider": "anthropic",
      "model": "claude-sonnet-5-5",
      "system_prompt": "You are Mia, a pair programmer in a meeting. When asked to write code, use screen_write_file and run it in the terminal. Explain results in one or two sentences."
    },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "voice": { "provider": "openai", "voice_id": "nova" },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"],
      "desktop": true,
      "quiet_actions": true
    }
  }'
```

In the meeting:

```
"Mia, write a script that reads numbers 1 to 20 and prints the even ones, then run it."
"Now open a spreadsheet and make a column of those numbers with a sum at the bottom."
```

### Example C: Quiet meeting helper that lives in the chat

Listens all meeting, acts on clear requests, speaks only when addressed.

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Quiet Helper",
    "mode": "pipeline",
    "model": {
      "provider": "openai",
      "model": "gpt-4.1-mini",
      "system_prompt": "You are Mia, a quiet meeting helper. Share pages and post links when asked. Answer only questions addressed to you."
    },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "voice": { "provider": "openai", "voice_id": "alloy" },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"],
      "chat_input": true,
      "quiet_actions": true,
      "speak_only_when_asked": true
    }
  }'
```

### Example D: Claude Code in your design review

Your own Claude Code, reading your repository, with the activation code and read-only access.

On your computer:

```bash
uv tool install meetstream-agent-kit
meetstream-agent-kit          # choose Claude Code, your repo folder, Read-only, Cloudflare
```

Save the printed pairing token under **Integrations → Models → Local agent**, then create the agent:

```bash
curl -X POST https://api.meetstream.ai/api/v1/mia \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Claude Code (my repo)",
    "mode": "pipeline",
    "model": {
      "provider": "local_agent",
      "model": "haiku",
      "local_agent": {
        "url": "https://<your-tunnel-host>",
        "label": "Claude Code",
        "access": "readonly"
      }
    },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "voice": { "provider": "elevenlabs", "voice_id": "<YOUR_ELEVENLABS_VOICE_ID>" },
    "agent": {
      "response_modality": "audio",
      "tools": ["screen"],
      "chat_input": true,
      "quiet_actions": true
    }
  }'
```

In the meeting:

```
(chat)  Claude:  I'm off until activated. To use Claude Code, paste the 6-digit code
                 it shows on your computer here in the chat.
(chat)  You:     482913
You:    Claude, where do we validate the meeting link, and what happens if it's a Zoom link?
Claude: "It's validated in the create bot handler. Zoom links go through ... "
You:    Share the README on GitHub and scroll to the setup section.
Claude: (shares the page and scrolls)
```

---

## 6. Limits and good to know

**Screen tools and desktop**

- Screen tools and the bot desktop work in **Google Meet** today. On Zoom and Microsoft Teams, they are not offered to the agent.
- The shared screen is 1280×720. Mouse positions and screenshots use that frame.
- Starting a share or opening a page takes a few seconds. A click takes one to two seconds.
- The browser MIA presents runs separately from the meeting browser and can reach only public websites.
- `screen_type` takes up to 2,000 characters per call. `send_chat_message` takes up to 2,000 characters. `screen_write_file` takes up to 200,000 characters.
- If MIA's presenting browser or desktop crashes, it restarts by itself, up to 3 times in 10 minutes.
- Meet decides what appears to the audience. If Meet ends the bot's presentation, MIA stops sharing.

**Your agent**

- Pipeline mode only.
- Your computer, the bridge and the tunnel must stay on and online for the whole meeting. If they stop, MIA posts one chat line, sends an `agent_error`, and checks again every 30 seconds.
- The activation code works in **Google Meet**. In Zoom and Microsoft Teams, set `require_code: false` and use `owner_names`.
- A Cloudflare quick tunnel gets a new address each time it starts. Update the Bridge URL in MeetStream when it changes, or use a named tunnel or an ngrok static domain for a fixed address.
- How fast your agent answers depends on your agent, its model and your computer. With a warm session, small models start answering in about one second.

**Updating agents with the API**

- `PUT /api/v1/mia` replaces the whole `agent` block. When you update an agent, send `tools`, `desktop`, `chat_input`, `quiet_actions` and `speak_only_when_asked` again, or they are cleared.

---

## 7. Troubleshooting

| Problem | Likely cause | Fix |
|---|---|---|
| API rejects `"screen"` in `agent.tools` | The model cannot see images. | Pick a model from [Supported models](#supported-models). |
| API rejects `speak_only_when_asked` | The agent is in realtime mode. | Use pipeline mode. |
| MIA says it can't share or control the screen | The meeting is on Zoom or Teams, or `"screen"` is missing from `agent.tools`. | Use Google Meet, and check `agent.tools`. |
| MIA never opens apps or writes files | `agent.desktop` is not `true`. | Set `desktop: true` together with `tools: ["screen"]`. |
| Screen or chat actions are refused | `speak_only_when_asked` is on and MIA was not addressed by name. | Say MIA's name in the request: *"Mia, share the page."* |
| MIA ignores a pasted link | A bare link is context, not a request. | Ask by name (*"Mia, open the link I pasted"*), or tell MIA out loud first: *"Mia, I'll paste a link."* |
| Screenshot came as a link, not an image | The meeting chat takes text only for the bot. | Expected. The link is valid for one hour. |
| Your agent never answers | The activation code was not pasted, or someone else is the owner. | Paste the code from the bridge terminal in the meeting chat. |
| MIA says your agent is not reachable | The bridge or tunnel stopped, or the tunnel address changed. | Restart `meetstream-agent-kit`, and update the Bridge URL if it changed. |
| `local_agent_login_required` error | Your agent's login expired. | Run its sign-in command. MIA resumes within 30 seconds. |
| `port 8787 is used by another program` | Something else uses the port. | `serve --port 8788`, and point your tunnel at that port. |
| `Claude Code not found` | The CLI is not on your PATH. | Install it (`npm install -g @anthropic-ai/claude-code`) or pass `--binary`. |
| Your agent can only read files | Access is read-only (the default), or your computer's `--max-access` is lower than the agent asks for. | Raise `--max-access` on your computer and `access` in the agent config. **Full** also needs the activation code. |

`meetstream-agent-kit doctor` checks your computer and prints a fix for every problem it finds:

```text
$ meetstream-agent-kit doctor --agent claude
  ✓ python: Python 3.12.8
  ✓ config: /Users/you/.config/meetstream-agent-kit
  ✓ workdir: /Users/you/code/my-project
  ✓ agent: Claude Code: /Users/you/.local/bin/claude
  ✓ login: Claude Code ok
  ✓ pairing: 1 pairing(s)
  ✗ port: port 8787 is used by another program
      fix: Start the bridge with another --port (and point your tunnel at it), or free port 8787.
```

---

## 8. FAQ

**Does MeetStream see my agent's login, code or files?**
No. Your agent runs on your computer with your login, and the login never leaves your computer. Your agent sends MIA only the text of its answers and its tool calls.

**Who pays for my agent's model?**
You do, through your own agent subscription. MeetStream charges no model tokens for your agent's replies. MIA's speech-to-text and voice work as for any other agent.

**Can someone in the meeting make my agent change files on my computer?**
Not by default. Your agent starts read-only. **Ask me first** needs you to approve every action in the bridge terminal. **Full** needs your computer to allow it with `--max-access full` and the activation code, so only you can talk to your agent. Meeting speech and chat are treated as untrusted text.

**Can MIA open any website someone mentions?**
MIA opens only pages someone names or pastes for it, never pages it picks itself or overhears from other people's conversation. With `chat_input`, a bare pasted link is context, not a request.

**Does the bot desktop touch my computer?**
No. The desktop runs inside the bot, has no network access, and is removed when the bot leaves.

**Can I use MCP servers and custom functions together with screen tools or my own agent?**
Yes. Screen tools are added next to your MCP servers and custom functions. Your own agent also gets them, through the bridge, along with the meeting tools.

**Does my agent work in Zoom and Microsoft Teams?**
Yes, your agent can answer in Google Meet, Zoom and Microsoft Teams. Screen tools and the activation code are Google Meet only for now.

---

## Related guides

- [MIA Reference](/guides/mia/what-is-mia)
- [Create Agent Guide](/guides/mia/create-an-agent)
- [MIA API Reference](/guides/mia/mia-api-guide)
- [Custom Functions Guide](/guides/mia/mia-custom-configurations)
- [Send Message Guide](../MeetStream_Send_Message_Guide.md)
- [MeetStream Agent Kit on GitHub](https://github.com/meetstream-ai/agent-kit)