> ## 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.

# Slack

> Virtualize a Slack workspace from Node or the browser.

`SlackVFS` mounts a Slack workspace as read-only files: channels and DMs as
one folder per day of messages and attachments, plus user profiles. Set up the tokens as in [Slack setup](https://docs.mirage.strukto.ai/home/setup/slack.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, SlackVFS, Workspace } from '@struktoai/mirage-node'

const slack = new SlackVFS({
  token: process.env.SLACK_BOT_TOKEN!,
  searchToken: process.env.SLACK_USER_TOKEN!,
})
const ws = new Workspace({ '/slack': slack }, { mode: MountMode.READ })

const result = await ws.shell('ls /slack/channels && grep -rlw refund /slack/channels')
console.log(result.stdoutText)
await ws.close()
```

`searchToken` is optional: without it, `grep` reads the files. `startTime` and
`endTime` bound the mount to a time range.

### Fields

**startTime** `string`

Start of the mount's time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.

**endTime** `string`

End of the mount's time scope, exclusive, in the same format as `startTime`, which it must follow. Unset leaves the end open.

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**token** `string` *required*

Slack token every API call sends: a bot token (`xoxb-`) or a user token (`xoxp-`).

**searchToken** `string`

User token (`xoxp-`) with `search:read`, used only for Slack's `search.*` methods, which refuse a bot token. Unset searches with `token`.

**baseUrl** `string` (default: '[https://slack.com/api](https://slack.com/api)')

Slack Web API root; override to point at a fake or proxy.

Fields marked secret are redacted in snapshots.

## Authentication

`token` is a bot token (`xoxb-...`) with these bot scopes:

* `channels:read`, `channels:history`: public channels.
* `groups:read`, `groups:history`: private channels (optional).
* `im:read`, `im:history`: direct messages (optional).
* `mpim:read`, `mpim:history`: group DMs (optional).
* `users:read`: the `users/` folder.
* `files:read`: attachments under `files/`.

Invite the bot to each channel it should read with `/invite @Mirage`; a
channel it is not in answers `Permission denied`. The mount never posts.

Slack's search refuses bot tokens (`not_allowed_token_type`). The optional
`searchToken` is a user token (`xoxp-...`) with `search:read`, used only for
Slack's search methods; the bot token still does every read. For `grep` and
`rg`, that user token also needs `channels:read`, `groups:read`, `im:read` and
`mpim:read`, so Mirage can tell which channels and DMs its search covers.

## Layout

```text theme={null}
/slack/
  channels/
    general__C04KEPWF6V7/
      2026-11-16/
        chat.jsonl
        files/
          roadmap__F07AB12CD.pdf
  dms/
    alice__D0AQDJ5FP9V/
      2026-11-16/
        chat.jsonl
  users/
    alice__U12345678.json
```

* **Names:** a channel, DM or user is `<display-name>__<id>`, so the CLI's
  channel and user flags take the id from the path. Only `/` in a name
  becomes `∕` (U+2215); `ls` the parent for exact names and quote names with
  spaces.
* **Days:** each channel and DM lists one folder per day for the 90 days up
  to its newest message; a date glob finds earlier days.
* **`chat.jsonl`:** one message per line as Slack's API returns it (`.text`,
  `.user`, `.ts`, `.files`). `.user` is a user id, matched against
  `users/<name>__<user-id>.json`.
* **`files/`:** the attachments shared that day.
* **`users/`:** one file per user that is not deleted or a bot, holding the
  full profile from Slack.

## Behavior

* **Read only:** the mount cannot send or change messages. Use the
  [`slack`](https://docs.mirage.strukto.ai/typescript/cli/slack) CLI to send messages, react, pin, look up
  members, search and upload files.
* **Time scope:** `startTime` and `endTime` (RFC 3339 with a timezone) limit
  the mount to that period; start inclusive, end exclusive, an unset bound
  open.
  * Day folders use UTC, and messages are picked by creation time. Direct
    paths, `stat`, date globs, `grep` and `rg` stay inside the scope. Users and
    channel metadata stay visible.
  * The scope does not apply to the `slack` CLI. Rebuild the mount to change
    it.
* **Upstream changes:** a `read` mount refuses writes through Mirage; it does
  not freeze edits or deletions made in Slack.
* **Rate limits:** many reads of `chat.jsonl` can hit Slack's per-method rate
  limits, and history limits depend on how the app is distributed; see
  Slack's
  [`conversations.history` limits](https://docs.slack.dev/reference/methods/conversations.history/).

## Browser

The browser `SlackVFS` from `@struktoai/mirage-browser` never sees a token: a
proxy on the backend holds it and forwards `/api/slack/*` to
`https://slack.com/api/*`.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { MountMode, SlackVFS, Workspace } from '@struktoai/mirage-browser'

const slack = new SlackVFS({ proxyUrl: '/api/slack' })
const ws = new Workspace({ '/slack': slack }, { mode: MountMode.READ })
```

* The proxy is required: Slack sets no permissive CORS headers, so a call to
  `https://slack.com/api/*` from the page fails.
* `getHeaders` returns extra headers for each request to the proxy, such as a
  per-user session credential.

> [accordion] Proxy server
>
> ```ts theme={null}
> import { createServer } from 'node:http'
>
> const TOKEN = process.env.SLACK_BOT_TOKEN!
> const PREFIX = '/api/slack/'
>
> createServer(async (req, res) => {
>   const url = new URL(req.url ?? '/', 'http://localhost')
>   if (!url.pathname.startsWith(PREFIX)) {
>     res.statusCode = 404
>     res.end()
>     return
>   }
>   const upstream = new URL(`https://slack.com/api/${url.pathname.slice(PREFIX.length)}`)
>   upstream.search = url.search
>
>   const method = (req.method ?? 'GET').toUpperCase()
>   const chunks: Buffer[] = []
>   if (method !== 'GET' && method !== 'HEAD') {
>     for await (const chunk of req) chunks.push(chunk as Buffer)
>   }
>   const body = chunks.length > 0 ? Buffer.concat(chunks).toString('utf-8') : undefined
>
>   const headers: Record<string, string> = { Authorization: `Bearer ${TOKEN}` }
>   const ct = req.headers['content-type']
>   if (typeof ct === 'string') headers['content-type'] = ct
>
>   const upstreamRes = await fetch(upstream, { method, headers, ...(body !== undefined ? { body } : {}) })
>   const text = await upstreamRes.text()
>   res.statusCode = upstreamRes.status
>   const upstreamCt = upstreamRes.headers.get('content-type')
>   if (upstreamCt !== null) res.setHeader('content-type', upstreamCt)
>   res.end(text)
> }).listen(8901, '127.0.0.1')
> ```

> [accordion] Browser fields
>
> **startTime** `string`
>
> Start of the mount's time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.
>
> **endTime** `string`
>
> End of the mount's time scope, exclusive, in the same format as `startTime`, which it must follow. Unset leaves the end open.
>
> **timeout** `number` (default: DEFAULT\_TIMEOUT)
>
> Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
>
> **proxyUrl** `string` *required*
>
> URL of your backend proxy, which forwards to `https://slack.com/api` and attaches the token. A path resolves against the page's origin; no query string or fragment.
>
> **getHeaders** `function`
>
> Function returning extra headers sent with every request to the proxy, such as your own session credential.
>
> Fields marked secret are redacted in snapshots.

## Integration

Slack answers these commands through its own API, so fewer files are read.
See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: with a user token, only the channel and DM days
  Slack search names are read, and the output matches reading every day.
  Search covers message text, file names and titles, and reactions
  (`has::name:`); a file hit names each day the file was shared. Users, file
  blobs and a day searched on its own are always read. Every day is read when
  the word is a key or fixed value of the message JSON, a file-type or URL
  word, a join or leave message word, or part of a user's name or of the
  workspace's domain, and when a search fails, returns more than 1,000
  messages or finds nothing. With a separate `searchToken`, every day is also
  read when the scope holds a private channel or DM that token's user is not
  in (a bot's own DMs). Slack indexes a message some time after it is posted,
  and a word held only in another field (a bot's username, an unfurled link)
  is not searched; `walk_limit: -1` in the mount's `"@all"`
  [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file instead.
* `tail -f`: each new message as it is posted.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Slack mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `slack`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   channels/
>     <channel-name>__<channel-id>/
>       <yyyy-mm-dd>/
>         chat.jsonl              # messages for that date
>         files/                  # attachments shared that day
>           <name>__<F-id>.<ext>  # cat downloads the bytes
>   dms/
>     <user-name>__<dm-id>/
>       <yyyy-mm-dd>/
>         chat.jsonl
>         files/
>           <name>__<F-id>.<ext>
>   users/
>     <username>__<user-id>.json  # user profile
> ```
>
> * A channel, DM or user name is `<display-name>__<id>`; only `/` becomes
>   `∕` (U+2215). `ls` the parent for exact names and quote names with
>   spaces.
> * `chat.jsonl` holds one message per line (`.text`, `.user`, `.ts`,
>   `.files`). `.user` is a user id (`U…`); match it against
>   `users/<username>__<user-id>.json`.
> * Without `start_time`/`end_time`, a channel lists the 90 days up to its
>   newest message; a date glob finds earlier days.
> * Unless `walk_limit` is -1, `grep -rw` and `rg -w` read only the days
>   Slack search names; `files/` is always read.
>
> Time scope: `start_time=unbounded` (inclusive), `end_time=unbounded` (exclusive); explicit paths and globs cannot escape it.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `slack` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `slack` answers only for `channels/*/*/chat.jsonl` and `dms/*/*/chat.jsonl`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `slack`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   channels/
>     <channel-name>__<channel-id>/
>       <yyyy-mm-dd>/
>         chat.jsonl              # messages for that date
>         files/                  # attachments shared that day
>           <name>__<F-id>.<ext>  # cat downloads the bytes
>   dms/
>     <user-name>__<dm-id>/
>       <yyyy-mm-dd>/
>         chat.jsonl
>         files/
>           <name>__<F-id>.<ext>
>   users/
>     <username>__<user-id>.json  # user profile
> ```
>
> - A channel, DM or user name is `<display-name>__<id>`; only `/` becomes
>   `∕` (U+2215). `ls` the parent for exact names and quote names with
>   spaces.
> - `chat.jsonl` holds one message per line (`.text`, `.user`, `.ts`,
>   `.files`). `.user` is a user id (`U…`); match it against
>   `users/<username>__<user-id>.json`.
> - Without `start_time`/`end_time`, a channel lists the 90 days up to its
>   newest message; a date glob finds earlier days.
> - Unless `walk_limit` is -1, `grep -rw` and `rg -w` read only the days
>   Slack search names; `files/` is always read.
>
> Time scope: `start_time=unbounded` (inclusive), `end_time=unbounded` (exclusive); explicit paths and globs cannot escape it.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `slack` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `slack` answers only for `channels/*/*/chat.jsonl` and `dms/*/*/chat.jsonl`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


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