---
title: "Quick Start"
description: "From zero to your first AI agent responding in Slack - in under 10 minutes."
---

This guide takes you from a fresh machine to a working SlackHive setup with a live agent in your Slack workspace.

<Note>
  **Before you begin, you'll need:**
  - **Node.js 20 or later** - `node --version` to check
  - **[Claude Code](https://claude.ai/code)** installed (the agents run on top of it)
  - A **Slack workspace** where you can install apps (admin, or permission to install apps)
  - One of:
    - An [Anthropic API key](https://console.anthropic.com) - pay per token, best for teams
    - A Claude Pro or Max subscription - already signed in via `claude login`
</Note>

## Install SlackHive

The `slackhive` CLI handles everything - checks your environment, clones the repo, walks you through configuration, and starts the services.

<Steps>
  <Step title="Install the CLI">
    ```bash
    npm install -g slackhive
    ```

    <Tip>
      **`EACCES: permission denied`?** If you installed Node from nodejs.org on macOS/Linux, `/usr/local/lib/node_modules` is root-owned. Point npm at a user-owned prefix once:

      ```bash
      mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
      echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
      source ~/.zshrc
      ```

      Then retry `npm install -g slackhive`. Full troubleshooting in [Install the CLI](/getting-started/install-cli).
    </Tip>
  </Step>
  <Step title="Run the setup wizard">
    ```bash
    slackhive init
    ```

    The wizard asks a few questions:

    | Prompt | What to enter |
    |---|---|
    | **Install directory** | Where to put SlackHive (default: `./slackhive`) |
    | **Admin username** | Your login name for the dashboard |
    | **Admin password** | A strong password |
    | **Claude auth** | Pick API key or OAuth from Claude Code |

    Everything else (encryption keys, ports) is generated automatically. First run takes 2–3 minutes while dependencies install and the apps build.
  </Step>
  <Step title="Open the dashboard">
    Navigate to:

    ```
    http://localhost:3001
    ```

    Log in with the admin credentials you set. You'll see the SlackHive dashboard.
  </Step>
</Steps>

See [Install with the CLI](/getting-started/install-cli) for more detail.

## Create your first agent

Click **New Agent** in the sidebar. This opens a 5-step wizard.

<Steps>
  <Step title="Name & Description">
    - **Name** - shown in Slack (e.g. "Data Analyst" or "Ava")
    - **Description** - what this agent does, in one sentence. Boss uses this to know who to delegate to.
    - **Model** - `claude-sonnet-4-6` is a good default

    Leave the **Boss** toggle off for now.
  </Step>
  <Step title="Pick a Persona">
    Browse the **Persona Library** - 26 research-backed starters (Data Analyst, Backend Engineer, Product Manager, Technical Writer, and more). Pick one that fits.

    The persona seeds the agent's system prompt, skills, and recommended MCPs. You can customize everything later with [Coach](/agents/coach). If none fit, pick **Blank**.
  </Step>
  <Step title="Create a Slack App">
    Each SlackHive agent needs its own Slack app. The wizard generates everything you need.

    1. Click **Generate Manifest** in the wizard
    2. Open [api.slack.com/apps](https://api.slack.com/apps) in a new tab
    3. Click **Create New App** → **From an app manifest**
    4. Select your Slack workspace
    5. Paste the manifest JSON from the wizard
    6. Click **Create**
    7. On the next screen, click **Install to Workspace** → **Allow**
  </Step>
  <Step title="Enter Credentials">
    You need three values from your Slack app:

    **Bot Token** - OAuth & Permissions → **Bot User OAuth Token** (starts with `xoxb-`)

    **App Token** - Basic Information → App-Level Tokens → **Generate Token and Scopes** → add `connections:write` → copy (starts with `xapp-`)

    **Signing Secret** - Basic Information → App Credentials → Signing Secret → **Show** → copy

    Paste all three and click **Verify Connection**. See [Slack app setup](/configuration/slack-app) if verification fails.
  </Step>
  <Step title="Tools & Review">
    Assign any **MCP servers** you've added to the catalog. You can skip this and add them later.

    Review the summary and click **Create Agent**. The runner picks up the new agent within a few seconds - status flips to **Active** on the dashboard.
  </Step>
</Steps>

## Test your agent in Slack

<Steps>
  <Step title="Invite the bot to a channel">
    ```
    /invite @your-agent-name
    ```
  </Step>
  <Step title="Send a message">
    ```
    @your-agent-name hello, what can you help me with?
    ```

    You should see a typing indicator, then a reply in the thread.
  </Step>
</Steps>

<Tip>
  You can also DM the bot directly - open a new DM in Slack, find the agent by name, start chatting.
</Tip>

Before posting in a live channel, try [Test Mode](/agents/testing) - it's a sandboxed conversation pane with real MCPs.

## What's next

<CardGroup cols={2}>
  <Card title="Tune with Coach" icon="comments" href="/agents/coach">
    Interactive prompt, skill, and knowledge tuning.
  </Card>
  <Card title="Knowledge Library" icon="book" href="/agents/knowledge-base">
    Shared wiki folders. Anyone can build one; agents are assigned the folders they need.
  </Card>
  <Card title="Boss Agents" icon="sitemap" href="/agents/boss-agents">
    Set up an orchestrator that routes to the right specialist.
  </Card>
  <Card title="Connect MCP Servers" icon="plug" href="/configuration/mcp-servers">
    Give your agent real tools - query databases, read files, call APIs.
  </Card>
</CardGroup>
