slackhive 0.1.37 → 0.1.39

package/docs/configuration/env-vars.mdx

@@ -0,0 +1,166 @@
+---
+title: "Environment Variables"
+description: "Complete reference for every SlackHive configuration variable, grouped by category."
+---
+
+All SlackHive configuration lives in a single `.env` file in the project root. The `slackhive init` CLI generates this file for you automatically. For manual setup, copy the example file and fill in the values:
+
+```bash
+cp .env.example .env
+```
+
+<Warning>
+  Never commit your `.env` file to version control. It contains passwords and cryptographic keys. It's already listed in `.gitignore`, but double-check before pushing.
+</Warning>
+
+## Claude Authentication
+
+You need one of these two options — not both. If both are set, the API key takes precedence.
+
+### Option A: Anthropic API Key
+
+Best for teams, production deployments, and predictable billing.
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-api03-...
+```
+
+All agents share this key. You're billed per token via the [Anthropic API](https://console.anthropic.com). Set up your billing and usage limits on the Anthropic console.
+
+### Option B: Claude Max Subscription
+
+Best for individual developers on a Claude Pro or Max plan ($100–$200/month for unlimited usage).
+
+```bash
+# Leave ANTHROPIC_API_KEY unset (comment it out)
+CLAUDE_BIN=/usr/local/bin/claude
+```
+
+First, run `claude login` on the host machine to authenticate. Then mount the credentials into the runner container by adding this to `docker-compose.yml`:
+
+```yaml
+runner:
+  volumes:
+    - ~/.claude:/root/.claude
+```
+
+<Note>
+  The `CLAUDE_BIN` variable tells the runner where the `claude` binary lives on your host. Find the path with `which claude`.
+</Note>
+
+## Database (PostgreSQL)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `POSTGRES_DB` | Yes | Database name. Default: `slackhive` |
+| `POSTGRES_USER` | Yes | Database user. Default: `slackhive` |
+| `POSTGRES_PASSWORD` | Yes | Database password. Use a strong random value. |
+
+```bash
+POSTGRES_DB=slackhive
+POSTGRES_USER=slackhive
+POSTGRES_PASSWORD=change-this-to-something-strong
+```
+
+The `DATABASE_URL` used internally is constructed from these values automatically in `docker-compose.yml`. You don't set it directly.
+
+## Cache (Redis)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `REDIS_PASSWORD` | Yes | Redis authentication password. Used for the pub/sub event bus between the dashboard and the runner. |
+
+```bash
+REDIS_PASSWORD=change-this-to-something-strong
+```
+
+## Dashboard Authentication
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ADMIN_USERNAME` | Yes | Superadmin login name. Stored only in `.env`, never in the database. |
+| `ADMIN_PASSWORD` | Yes | Superadmin login password. Stored only in `.env`. |
+| `AUTH_SECRET` | Yes | Cryptographic key for signing session cookies. Changing this logs out all users. |
+| `ENV_SECRET_KEY` | Yes | Encryption key for the secret store (AES-256 via pgcrypto). Changing this breaks all stored secrets. |
+
+```bash
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-this-to-something-strong
+AUTH_SECRET=generate-with-openssl-rand-hex-32
+ENV_SECRET_KEY=generate-with-openssl-rand-hex-32
+```
+
+<Tip>
+  Generate strong values for `AUTH_SECRET` and `ENV_SECRET_KEY`:
+  ```bash
+  openssl rand -hex 32
+  ```
+  Run this command twice — once for each variable. Each should be unique.
+</Tip>
+
+<Warning>
+  **Do not rotate these keys after your initial setup without planning ahead.**
+
+  - Rotating `AUTH_SECRET` immediately invalidates all active user sessions — everyone gets logged out.
+  - Rotating `ENV_SECRET_KEY` makes all stored secrets unreadable. You must re-enter every secret manually in **Settings → Env Vars** before any MCP servers using `envRefs` will work again.
+</Warning>
+
+## Platform
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NODE_ENV` | No | `development` | Set to `production` for production deployments. Affects log verbosity and error handling. |
+| `AGENTS_TMP_DIR` | No | `/tmp/agents` | Root directory for agent workspaces inside the runner container. Each agent gets a subdirectory containing its `CLAUDE.md`, skills, and session data. |
+
+```bash
+NODE_ENV=production
+# AGENTS_TMP_DIR=/tmp/agents  # only change if you need a custom path
+```
+
+## Complete .env.example
+
+Here's the full template for reference:
+
+```bash
+# ============================================================
+# SlackHive — Environment Configuration
+# Copy to .env and fill in your values.
+# ============================================================
+
+# --- Claude Authentication (choose ONE) ---
+
+# Option A: Anthropic API key (pay-per-token)
+# ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# Option B: Claude Pro or Max subscription
+# Leave ANTHROPIC_API_KEY unset. Run `claude login` on the host first.
+# CLAUDE_BIN=/usr/local/bin/claude
+
+# --- PostgreSQL ---
+POSTGRES_DB=slackhive
+POSTGRES_USER=slackhive
+POSTGRES_PASSWORD=change-me
+
+# --- Redis ---
+REDIS_PASSWORD=change-me
+
+# --- Dashboard Auth ---
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+AUTH_SECRET=generate-with-openssl-rand-hex-32
+ENV_SECRET_KEY=generate-with-openssl-rand-hex-32
+
+# --- Platform ---
+NODE_ENV=production
+```
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Slack App Setup" icon="slack" href="/configuration/slack-app">
+    Configure the Slack app for each agent.
+  </Card>
+  <Card title="MCP Servers" icon="plug" href="/configuration/mcp-servers">
+    Use the encrypted env store to safely pass secrets to MCP tools.
+  </Card>
+</CardGroup>

package/docs/configuration/mcp-servers.mdx

@@ -0,0 +1,203 @@
+---
+title: "MCP Servers"
+description: "Connect your agents to databases, APIs, and external services using the Model Context Protocol."
+---
+
+## What is MCP?
+
+**MCP (Model Context Protocol)** is a standard that lets AI agents connect to external tools and data sources. Think of MCP servers as plugins for your agents — they give agents the ability to actually *do* things beyond just having a conversation.
+
+Without MCP, an agent can only talk. With MCP, an agent can:
+- Query your database and return real results
+- Read files from a repository
+- Create GitHub issues
+- Fetch data from any internal API
+- Run custom scripts
+
+An MCP server is a small program that exposes a set of **tools**. When an agent needs to do something — like run a SQL query — it calls the appropriate MCP tool, gets back the result, and incorporates it into its response.
+
+<Note>
+  You don't need to build MCP servers from scratch. There are [many open-source MCP servers](https://github.com/modelcontextprotocol/servers) for common tools. SlackHive also supports **inline TypeScript MCPs** — you can paste code directly into the UI without deploying anything.
+</Note>
+
+## How SlackHive manages MCP
+
+SlackHive manages MCP servers at the **platform level**. You add a server once to the global catalog, then assign it to any number of agents.
+
+When an agent starts, SlackHive launches all its assigned MCP servers and keeps them running. There's no per-message startup overhead — once the agent is live, its tools are always ready.
+
+Tool names follow the pattern `mcp__{serverName}__{toolName}`. For example, a server named `redshift` with a `query` tool is called as `mcp__redshift__query`.
+
+## Adding a server to the catalog
+
+<Steps>
+  <Step title="Open MCP Servers">
+    In the sidebar, click **MCP Servers** (under Settings).
+  </Step>
+  <Step title="Click Add Server">
+    Give it a name and description. The name becomes part of every tool name from this server (`mcp__{name}__...`).
+  </Step>
+  <Step title="Choose a transport type">
+    Select how SlackHive connects to this server (see the [Transport Types](#transport-types) section below).
+  </Step>
+  <Step title="Enter the configuration">
+    Fill in the command, URL, or script depending on your transport type.
+  </Step>
+  <Step title="Test and save">
+    Click **Test Connection** to verify the server starts and responds correctly. Then click **Save**.
+  </Step>
+</Steps>
+
+## Transport types
+
+There are four ways to run an MCP server:
+
+| Transport | Use case |
+|-----------|----------|
+| `stdio` | A local process (Node.js script, Python script, binary) — most common |
+| `sse` | A remote server accessible via HTTP server-sent events |
+| `http` | A remote server accessible via HTTP |
+| TypeScript inline | Paste TypeScript source directly — no deployment needed |
+
+## Configuration examples
+
+### Redshift / Data Warehouse
+
+Give your data analyst agent the ability to run real SQL queries:
+
+```json
+{
+  "name": "redshift",
+  "type": "stdio",
+  "description": "Read-only Redshift query access",
+  "config": {
+    "command": "node",
+    "args": ["/path/to/redshift-mcp/dist/index.js"],
+    "envRefs": {
+      "DATABASE_URL": "REDSHIFT_DATABASE_URL"
+    }
+  }
+}
+```
+
+<Tip>
+  Notice the `envRefs` instead of `env`. This references a secret from the encrypted store rather than embedding the connection string directly. See [Keeping secrets safe](#keeping-secrets-safe) below.
+</Tip>
+
+### Filesystem Access
+
+Give an agent read access to files in a directory — useful for code review or documentation agents:
+
+```json
+{
+  "name": "filesystem",
+  "type": "stdio",
+  "description": "Read files from the codebase",
+  "config": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/repo"]
+  }
+}
+```
+
+The agent can then use `mcp__filesystem__read_file`, `mcp__filesystem__list_directory`, etc.
+
+### Remote API (SSE)
+
+Connect to a remote MCP server over the network:
+
+```json
+{
+  "name": "analytics-api",
+  "type": "sse",
+  "description": "Internal analytics data API",
+  "config": {
+    "url": "https://mcp.internal.example.com/sse",
+    "headers": {
+      "Authorization": "Bearer your-token-here"
+    }
+  }
+}
+```
+
+### Inline TypeScript
+
+The most convenient option for internal tools: paste TypeScript source directly into the UI. SlackHive writes it to disk and runs it — no separate deployment needed.
+
+Select **TypeScript inline script** as the transport type, then paste your implementation:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-tool", version: "1.0.0" });
+
+server.tool(
+  "lookup_customer",
+  { customer_id: z.string() },
+  async ({ customer_id }) => ({
+    content: [{ type: "text", text: `Customer ${customer_id}: Acme Corp, Plan: Pro` }],
+  })
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+This is ideal for simple tools you want to prototype quickly, or for internal utilities you don't want to expose as file paths.
+
+## Assigning servers to agents
+
+Once a server is in the catalog, you can assign it to agents:
+- **During agent creation** — Step 4 (Tools) of the wizard
+- **After creation** — from the agent's **Tools** tab
+
+An agent can have any number of MCP servers assigned. All tools from all assigned servers become available to the agent.
+
+## Keeping secrets safe
+
+Never paste database credentials, API keys, or passwords directly into MCP config `env` fields. Use the **encrypted env store** instead.
+
+The env store encrypts secrets at rest using AES-256. Values are never returned by the API or shown in the browser — only the key names are visible.
+
+<Steps>
+  <Step title="Add your secret to the store">
+    1. Go to **Settings → Env Vars** in the sidebar
+    2. Click **Add Variable**
+    3. Enter a name (e.g. `REDSHIFT_DATABASE_URL`) and the secret value
+    4. Click **Save** — the value is encrypted immediately
+  </Step>
+  <Step title="Reference it in your MCP config">
+    In your MCP server configuration, use `envRefs` to map the store key to the environment variable name the server expects:
+
+    ```json
+    {
+      "envRefs": {
+        "DATABASE_URL": "REDSHIFT_DATABASE_URL"
+      }
+    }
+    ```
+
+    When the agent starts, the runner decrypts `REDSHIFT_DATABASE_URL` from the store and injects it as `DATABASE_URL` into the MCP process environment.
+  </Step>
+</Steps>
+
+The raw secret never appears in API responses, browser dev tools, or log files.
+
+## Testing a server
+
+From **Settings → MCP Servers**, click the **Test** button next to any server. SlackHive starts the server process and verifies it responds to initialization. Results appear inline.
+
+If a server fails to start, the agent still runs — an error is logged, but the agent continues without that server's tools. Check the agent's **Logs** tab for details.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Agent Tools & Permissions" icon="shield" href="/agents/tools">
+    Control exactly which MCP tools each agent can use.
+  </Card>
+  <Card title="Env Vars" icon="lock" href="/configuration/env-vars">
+    Configure your encryption key and other platform settings.
+  </Card>
+</CardGroup>

package/docs/configuration/slack-app.mdx

@@ -0,0 +1,175 @@
+---
+title: "Slack App Setup"
+description: "Create and configure a Slack app for each agent — the wizard generates everything, you just copy and paste."
+---
+
+Every SlackHive agent needs its own Slack app. The app is how your agent gets a Slack identity (`@handle`), connects to your workspace, and receives messages.
+
+The good news: **you don't need to configure scopes or settings manually.** The SlackHive wizard generates a complete app manifest — you just paste it into Slack and click a few buttons.
+
+This page walks through that process in detail, and covers troubleshooting if something goes wrong.
+
+## What you're creating
+
+Each Slack app gives your agent:
+- A **bot user** — the `@handle` your team @mentions in channels
+- **Socket Mode** — a persistent connection that receives messages in real time (no webhooks needed, no public URL required)
+- The right **OAuth scopes** — permissions to read messages, post replies, and add reactions
+
+## Step 1: Generate the manifest
+
+When you're on **Step 2** of the agent creation wizard, click **Generate Manifest**. SlackHive creates a JSON manifest pre-configured for your agent with the correct name, scopes, and Socket Mode settings.
+
+Keep this manifest JSON ready — you'll paste it into Slack in the next step.
+
+## Step 2: Create the Slack app
+
+<Steps>
+  <Step title="Open the Slack API console">
+    Go to [api.slack.com/apps](https://api.slack.com/apps) in a new browser tab. Sign in with the Slack account that has permission to install apps in your workspace.
+  </Step>
+  <Step title="Start creating a new app">
+    Click the **Create New App** button in the top right. A dialog will appear asking how you'd like to configure your app.
+  </Step>
+  <Step title="Choose From an app manifest">
+    Select **From an app manifest** (not "From scratch"). This lets you paste the pre-configured manifest rather than setting everything up manually.
+  </Step>
+  <Step title="Select your workspace">
+    Choose the Slack workspace where you want this agent to live. Click **Next**.
+  </Step>
+  <Step title="Paste the manifest">
+    You'll see a text editor. Delete any existing content, then paste the manifest JSON from the SlackHive wizard. Click **Next**.
+  </Step>
+  <Step title="Review and create">
+    Slack will show you a summary of the app settings. Click **Create** to finish. You'll land on the app's settings page.
+  </Step>
+</Steps>
+
+## Step 3: Install to your workspace
+
+Your app exists, but it's not yet installed in your workspace.
+
+<Steps>
+  <Step title="Go to OAuth & Permissions">
+    In the left sidebar of the Slack app settings page, click **OAuth & Permissions**.
+  </Step>
+  <Step title="Install the app">
+    Click the **Install to Workspace** button near the top of the page.
+  </Step>
+  <Step title="Approve the permissions">
+    Slack shows you a list of what the app will be allowed to do. Review it and click **Allow**.
+  </Step>
+</Steps>
+
+Your bot user (`@your-agent-name`) now exists in your workspace.
+
+## Step 4: Collect your credentials
+
+You need three values to connect the agent in SlackHive. Here's exactly where to find each one.
+
+### Bot Token (`xoxb-...`)
+
+1. Go to **OAuth & Permissions** in the left sidebar
+2. Under **OAuth Tokens for Your Workspace**, find **Bot User OAuth Token**
+3. Copy it — it starts with `xoxb-`
+
+### App Token (`xapp-...`)
+
+1. Go to **Basic Information** in the left sidebar
+2. Scroll down to **App-Level Tokens**
+3. Click **Generate Token and Scopes**
+4. Give it a name (e.g. `socket-mode`)
+5. Click **Add Scope** and select `connections:write`
+6. Click **Generate**
+7. Copy the token — it starts with `xapp-`
+
+### Signing Secret
+
+1. Still on **Basic Information**
+2. Under **App Credentials**, find **Signing Secret**
+3. Click **Show** to reveal it, then copy the hex string
+
+## Step 5: Enter credentials in SlackHive
+
+Go back to the SlackHive agent wizard (Step 3 — Credentials) and paste all three values:
+
+| Field | Value |
+|-------|-------|
+| **Bot Token** | `xoxb-...` |
+| **App Token** | `xapp-...` |
+| **Signing Secret** | The hex string from App Credentials |
+
+Click **Verify Connection**. SlackHive will test the connection before letting you proceed.
+
+## Required OAuth scopes
+
+The generated manifest includes these bot token scopes. Here's what each one is for:
+
+| Scope | Why it's needed |
+|-------|----------------|
+| `app_mentions:read` | Receive events when the bot is @mentioned in a channel |
+| `channels:history` | Read messages in public channels (needed for thread context) |
+| `channels:read` | List channels and get channel info |
+| `chat:write` | Post messages and replies |
+| `groups:history` | Read messages in private channels |
+| `groups:read` | List and access private channels |
+| `im:history` | Read direct messages |
+| `im:read` | Access DM channel info |
+| `im:write` | Send direct messages |
+| `mpim:history` | Read group DMs |
+| `reactions:write` | Add emoji reactions (used for "thinking" indicators while processing) |
+| `users:read` | Look up user display names (for memory and context) |
+
+## Troubleshooting
+
+<Accordion title="Verification failed — connection refused">
+  The most common cause is **Socket Mode not being enabled**.
+
+  1. Go to your Slack app settings
+  2. Click **Socket Mode** in the left sidebar
+  3. Make sure the toggle is **On**
+  4. Go back to SlackHive and try verifying again
+</Accordion>
+
+<Accordion title="Verification failed — invalid token">
+  - Check that you pasted the **Bot Token** (starts with `xoxb-`) in the Bot Token field, not the App Token
+  - Make sure there are no extra spaces before or after the token
+  - If you recently regenerated the token, make sure you copied the new one
+</Accordion>
+
+<Accordion title="App Token scope error">
+  The App Token must have the `connections:write` scope. If you created the token without adding this scope:
+  1. Go to **Basic Information** → **App-Level Tokens**
+  2. Click on your token name
+  3. Add the `connections:write` scope
+  4. Regenerate the token and copy the new value
+</Accordion>
+
+<Accordion title="Bot doesn't appear in workspace">
+  If you can't find `@your-agent-name` in Slack after completing the wizard:
+  1. Check that the app was installed: go to Slack app settings → **OAuth & Permissions** → the **Install to Workspace** button should show as already installed
+  2. In Slack, type `@` in a message box and start typing the agent's name
+  3. If it still doesn't appear, try reinstalling the app from **OAuth & Permissions**
+</Accordion>
+
+<Accordion title="Agent is Active but not responding">
+  If the dashboard shows the agent as Active but it doesn't respond to @mentions:
+  1. Make sure you've **invited the bot to the channel**: `/invite @your-agent-name`
+  2. Check the **Logs** tab on the agent — it will show if messages are being received
+  3. Verify the agent doesn't have channel restrictions set (Overview tab → Allowed Channels)
+</Accordion>
+
+## After setup
+
+Once credentials are verified, the runner connects the agent to Slack automatically. The agent status changes to **Active** in the dashboard.
+
+Invite the bot to a channel and start a conversation:
+
+```
+/invite @your-agent-name
+@your-agent-name hello!
+```
+
+<Note>
+  Each agent can only be installed in one Slack workspace. If you need agents in multiple workspaces, create separate Slack apps for each workspace and create separate agent entries in SlackHive.
+</Note>

package/docs/docs.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://mintlify.com/schema.json",
+  "name": "SlackHive",
+  "theme": "maple",
+  "logo": {
+    "light": "/logo/wide-light.svg",
+    "dark": "/logo/wide-dark.svg"
+  },
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#D97757"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/pelago-labs/slackhive"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Get Started",
+      "href": "https://github.com/pelago-labs/slackhive"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/pelago-labs/slackhive"
+    }
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": ["introduction", "quickstart"]
+          },
+          {
+            "group": "Configuration",
+            "pages": [
+              "configuration/env-vars",
+              "configuration/slack-app",
+              "configuration/mcp-servers"
+            ]
+          },
+          {
+            "group": "Agents",
+            "pages": [
+              "agents/creating-agents",
+              "agents/boss-agents",
+              "agents/memory",
+              "agents/tools"
+            ]
+          },
+          {
+            "group": "Features",
+            "pages": [
+              "features/scheduled-jobs",
+              "features/multi-workspace",
+              "features/import-export",
+              "features/logs",
+              "features/history",
+              "features/users"
+            ]
+          },
+          {
+            "group": "Self-Hosting",
+            "pages": [
+              "self-hosting/docker",
+              "self-hosting/production"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/docs/favicon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <style>
+      .bg { fill: #1A1918; }
+      .line { fill: none; stroke: #EBE6E0; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .prompt-accent { fill: none; stroke: #D97757; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .cursor { fill: #D97757; }
+    </style>
+  </defs>
+  <rect class="bg" width="512" height="512" rx="112" />
+  <path class="line" d="M 200 140 L 200 372" />
+  <path class="line" d="M 312 140 L 312 372" />
+  <path class="line" d="M 140 200 L 372 200" />
+  <path class="prompt-accent" d="M 100 280 L 140 312 L 100 344" />
+  <path class="line" d="M 180 312 L 280 312" />
+  <rect class="cursor" x="312" y="296" width="40" height="32" rx="6" />
+</svg>