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

# Cowork

> An agent does a team's cross-tool work from context scattered across chat, documents and spreadsheets, and makes each change only through the service's own CLI. Mirage sets up a managed virtual terminal for the task.

![mirage](https://docs.mirage.strukto.ai/logo/light.svg)
![mirage](https://docs.mirage.strukto.ai/logo/dark.svg)

A cowork agent picks up the work a team does by hand across its tools.
Something lands in chat, and someone opens three other apps to act on it.
They copy names, fill in a template, update a tracker and tell the team
where everything is. The agent does the same, from the same message.

Cowork is reads and writes over scattered context, chat, documents,
spreadsheets and a project tool, and that is the work Mirage is built for.
The agent reaches all of it from one terminal, with fewer tokens than
calling the same services as MCP tools
([VFS-Bench 1.0](https://agentvfs.org/benchmark/vfs-bench-1)). Its scope is
known up front, a few things to read and a few changes to make, which is
where a managed terminal fits. Here it runs as an
[in-process terminal](https://docs.mirage.strukto.ai/home/examples/in-process-terminal.md) on a Mirage
server, without a VM or sandbox.

## Setup

> [card] Files
>
> [Slack](https://docs.mirage.strukto.ai/python/vfs/slack.md) at `/slack` and [Google Drive](https://docs.mirage.strukto.ai/python/vfs/gdrive.md) at `/gdrive`, read-only. A Sheet or Doc is a JSON file.

> [card] CLIs
>
> [`gws`](https://docs.mirage.strukto.ai/python/cli/gws) writes Docs and Sheets, [`ntn`](https://docs.mirage.strukto.ai/python/cli/ntn) Notion and [`slack`](https://docs.mirage.strukto.ai/python/cli/slack) Slack.

> [card] Credentials
>
> Five keys the Mirage server holds. The agent never sees them.

You need the `mirage` CLI, Slack, Google and Notion accounts, two files in
Drive, and five keys.

> [accordion] Accounts and files
>
> Set up three accounts, and export five keys:
>
> | Service | Set up | Keys |
> | - | - | - |
> | Slack | A bot with `channels:read`, `channels:history`, `chat:write` and `users:read`, plus `groups:read` and `groups:history` for a private channel. Invite it to `#deals-won`. See [Slack](https://docs.mirage.strukto.ai/home/setup/slack.md). | `SLACK_BOT_TOKEN` |
> | Google | An OAuth client and a refresh token with the Drive, Docs and Sheets scopes. See [Google Workspace](https://docs.mirage.strukto.ai/home/setup/google.md). | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REFRESH_TOKEN` |
> | Notion | An internal integration. The agent creates its pages at the top level of the workspace, so nothing needs sharing. See [Notion](https://docs.mirage.strukto.ai/home/setup/notion.md). | `NOTION_API_KEY` |
>
> In Google Drive, make a folder named `Onboarding` with two files:
>
> * **`Onboarding tracker`**, a Sheet with the columns `Customer`, `Seats`,
>   `Start`, `Account manager` and `Plan`, and a row for each customer.
> * **`Onboarding plan template`**, a Doc with `{{customer}}`, `{{seats}}`,
>   `{{start}}`, `{{manager}}`, `{{goal}}`, `{{champion}}` and `{{kickoff}}`
>   where the values go:
>
>   ```text theme={null}
>   Onboarding plan: {{customer}}
>
>   Seats: {{seats}}
>   Start date: {{start}}
>   Account manager: {{manager}}
>
>   Goal
>   {{goal}}
>
>   Stakeholders
>   {{champion}}, champion
>
>   Milestones
>   Kickoff call by {{kickoff}}
>   Week 1: admin accounts and SSO
>   Week 2: import data and train the first team
>   Week 4: adoption review with {{champion}}
>   ```

> [accordion] Installation
>
> > [tab] pip
> >
> > ```bash theme={null}
> > pip install mirage-ai
> > ```
>
> > [tab] npm
> >
> > ```bash theme={null}
> > npm install -g @struktoai/mirage-cli
> > ```

> [accordion] workspace.yaml
>
> `workspace.yaml` mounts Slack and Drive read-only, keeps `/workspace` in
> memory, and installs the three CLIs. Each credential is read from the
> server's environment:
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /slack:
>     vfs: slack
>     mode: read
>     config:
>       token: {from: env, key: SLACK_BOT_TOKEN}
>   /gdrive:
>     vfs: gdrive
>     mode: read
>     config:
>       client_id: {from: env, key: GOOGLE_CLIENT_ID}
>       client_secret: {from: env, key: GOOGLE_CLIENT_SECRET}
>       refresh_token: {from: env, key: GOOGLE_REFRESH_TOKEN}
>   /workspace:
>     vfs: ram
>     mode: write
>
> clis:
>   slack:
>     cli: slack
>     machine: in_process
>     config:
>       token: {from: env, key: SLACK_BOT_TOKEN}
>   gws:
>     cli: gws
>     machine: in_process
>     config:
>       client_id: {from: env, key: GOOGLE_CLIENT_ID}
>       client_secret: {from: env, key: GOOGLE_CLIENT_SECRET}
>       refresh_token: {from: env, key: GOOGLE_REFRESH_TOKEN}
>   ntn:
>     cli: ntn
>     machine: in_process
>     config:
>       api_key: {from: env, key: NOTION_API_KEY}
> ```

Export the keys and create the workspace:

```bash theme={null}
export SLACK_BOT_TOKEN=xoxb-... NOTION_API_KEY=ntn_...
export GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_REFRESH_TOKEN=...
mirage daemon restart
mirage workspace create workspace.yaml --id onboarding
export MIRAGE_WORKSPACE=onboarding
```

The local server reads the keys when it starts, so `mirage daemon restart`
stops a server that started without them.

## Example

In this example, a deal closes and the CRM posts it to the `#deals-won`
channel in Slack. The agent starts the onboarding. It picks an account
manager from a tracker in Google Sheets, fills in a plan in Google Docs,
adds the customer to the tracker, opens a project in Notion and replies to
the team in Slack. The CRM posted this in Slack:

> **Deal won:** Northwind Health · 120 seats · start 2026-12-01 · champion Priya Shah ([priya@northwind.example](mailto:priya@northwind.example)) · goal: move clinic scheduling off spreadsheets

These are the commands the agent runs, in the terminal Setup created. Your
agent sends each one with `mirage shell`, or through [MCP](https://docs.mirage.strukto.ai/home/access/mcp.md), the
[HTTP API](https://docs.mirage.strukto.ai/home/access/http.md), [RPC](https://docs.mirage.strukto.ai/home/access/rpc.md) or [SSH](https://docs.mirage.strukto.ai/home/access/ssh.md).

**1. Read the deal from Slack**

A Slack channel is a folder under `/slack`, with a folder for each day.

```bash theme={null}
grep "Deal won" /slack/channels/deals-won__*/2026-11-16/chat.jsonl
```

It finds Northwind Health, 120 seats, starting 2026-12-01.

**2. Pick the account manager**

The tracker Sheet is a JSON file under `/gdrive`, so `jq` adds up the seats each manager has.

```bash theme={null}
jq … "/gdrive/Onboarding/Onboarding tracker.gsheet.json" | sort -n
```

Mei Chen has the fewest seats, so the deal goes to her.

**3. Write the plan**

`gws` copies the plan template Doc and fills in its placeholders.

```bash theme={null}
gws drive files copy …
gws docs documents batchUpdate …
```

The new plan sits next to the template in Drive.

**4. Add the customer to the tracker**

```bash theme={null}
gws sheets append …
```

A new row with the customer, seats, start date, manager and plan link.

**5. Open a project in Notion**

The agent writes the page to a file, puts in the plan's link, and `ntn` creates it.

```bash theme={null}
ntn api v1/pages -d "$(sed "s|PLAN_URL|…$plan|" /workspace/page.json)"
```

A project page with a link to the plan and a kickoff checklist.

**6. Tell the team**

`slack` replies in the thread of the CRM's message.

```bash theme={null}
slack send-message --thread-ts … --text "Onboarding started …"
```

The team has the owner, the plan and the project in one reply.

> [accordion] Full commands
>
> Each line runs in the agent's terminal with `mirage shell`, which keeps
> variables such as `$plan` from one call to the next.
>
> ```bash theme={null}
> mirage shell -c 'channel=$(ls /slack/channels | grep ^deals-won__ | sed "s/.*__//") && echo "$channel"'
> mirage shell -c 'deal=$(grep -h "Deal won" /slack/channels/deals-won__*/2026-11-16/chat.jsonl | jq -r .ts) && echo "$deal"'
> mirage shell -c 'grep -h "Deal won" /slack/channels/deals-won__*/2026-11-16/chat.jsonl | jq -r .text'
> mirage shell -c 'jq -r "[.sheets[0].data[0].rowData[1:][].values | {m: .[3].formattedValue, s: (.[1].formattedValue | tonumber)}]
>   | group_by(.m)[] | [(map(.s) | add), .[0].m] | @tsv" "/gdrive/Onboarding/Onboarding tracker.gsheet.json" | sort -n'
> mirage shell -c '
> template=$(jq -r .documentId "/gdrive/Onboarding/Onboarding plan template.gdoc.json")
> plan=$(gws drive files copy --params "{\"fileId\": \"$template\", \"fields\": \"id\"}" \
>   --json "{\"name\": \"Onboarding plan: Northwind Health\"}" | jq -r .id)
> echo "$plan"'
> mirage shell -c 'cat > /workspace/fill.json' <<'JSON'
> {"requests": [
>   {"replaceAllText": {"containsText": {"text": "{{customer}}", "matchCase": true}, "replaceText": "Northwind Health"}},
>   {"replaceAllText": {"containsText": {"text": "{{seats}}", "matchCase": true}, "replaceText": "120"}},
>   {"replaceAllText": {"containsText": {"text": "{{start}}", "matchCase": true}, "replaceText": "2026-12-01"}},
>   {"replaceAllText": {"containsText": {"text": "{{manager}}", "matchCase": true}, "replaceText": "Mei Chen"}},
>   {"replaceAllText": {"containsText": {"text": "{{champion}}", "matchCase": true}, "replaceText": "Priya Shah"}},
>   {"replaceAllText": {"containsText": {"text": "{{goal}}", "matchCase": true}, "replaceText": "Move clinic scheduling off spreadsheets"}},
>   {"replaceAllText": {"containsText": {"text": "{{kickoff}}", "matchCase": true}, "replaceText": "2026-12-08"}}
> ]}
> JSON
> mirage shell -c 'gws docs documents batchUpdate --params "{\"documentId\": \"$plan\"}" --json "$(cat /workspace/fill.json)" | jq -c "[.replies[].replaceAllText.occurrencesChanged]"'
> mirage shell -c 'jq -j ".tabs[0].documentTab.body.content[]?.paragraph?.elements[]?.textRun?.content // empty" "/gdrive/Onboarding/Onboarding plan: Northwind Health.gdoc.json"'
> mirage shell -c '
> tracker=$(jq -r .spreadsheetId "/gdrive/Onboarding/Onboarding tracker.gsheet.json")
> gws sheets append --spreadsheet "$tracker" \
>   --json-values "[[\"Northwind Health\", \"120\", \"2026-12-01\", \"Mei Chen\", \"https://docs.google.com/document/d/$plan\"]]" |
>   jq -r .updates.updatedRange'
> mirage shell -c 'cat > /workspace/page.json' <<'JSON'
> {
>   "parent": {"workspace": true},
>   "properties": {"title": {"title": [{"type": "text", "text": {"content": "Onboarding: Northwind Health"}}]}},
>   "children": [
>     {"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "120 seats, start 2026-12-01. Account manager: Mei Chen. Champion: Priya Shah."}}]}},
>     {"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Onboarding plan", "link": {"url": "PLAN_URL"}}}]}},
>     {"type": "heading_2", "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Kickoff checklist"}}]}},
>     {"type": "to_do", "to_do": {"rich_text": [{"type": "text", "text": {"content": "Kickoff call with Priya Shah by 2026-12-08"}}], "checked": false}},
>     {"type": "to_do", "to_do": {"rich_text": [{"type": "text", "text": {"content": "Admin accounts and SSO"}}], "checked": false}},
>     {"type": "to_do", "to_do": {"rich_text": [{"type": "text", "text": {"content": "Import data and train the first team"}}], "checked": false}},
>     {"type": "to_do", "to_do": {"rich_text": [{"type": "text", "text": {"content": "Adoption review in week 4"}}], "checked": false}}
>   ]
> }
> JSON
> mirage shell -c 'project=$(ntn api v1/pages -d "$(sed "s|PLAN_URL|https://docs.google.com/document/d/$plan|" /workspace/page.json)" | jq -r .url) && echo "$project"'
> mirage shell -c 'slack send-message --channel "$channel" --thread-ts "$deal" \
>   --text "Onboarding started. Account manager: Mei Chen. Kickoff by 2026-12-08. Plan: https://docs.google.com/document/d/$plan · Project: $project" |
>   jq -c "{ok, thread_ts: .message.thread_ts}"'
> ```

The deal now has an owner, a plan, a row in the tracker and a project. The
agent read every input as a file and made each change through the CLI for
its service.

For the commands and flags each CLI supports, see [gws](https://docs.mirage.strukto.ai/python/cli/gws.md),
[ntn](https://docs.mirage.strukto.ai/python/cli/ntn.md) and [slack](https://docs.mirage.strukto.ai/python/cli/slack.md). For the file layouts,
see the [Slack](https://docs.mirage.strukto.ai/python/vfs/slack.md) and [Google Drive](https://docs.mirage.strukto.ai/python/vfs/gdrive.md)
VFS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.