Quick Start

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. You’ll install SlackHive, create a Slack app, and send your first message to an AI agent.

Before you begin, you’ll need:

• Docker Desktop installed and running
• A Slack workspace where you can install apps (you need to be an admin, or have permission to install apps)
• One of:
  • An Anthropic API key — pay per token, best for teams
  • A Claude Pro or Max subscription — run claude login on your machine first

Install SlackHive

CLI (Recommended)

The slackhive CLI handles everything automatically — it checks your environment, clones the repo, walks you through configuration, and starts all services.

1. Install the CLI

   Open your terminal and run:

   npm install -g slackhive
   

   Requires Node.js 20 or later. Check your version with node --version.
2. Run the setup wizard

   slackhive init
   

   The wizard will ask you 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	Choose a strong password
   Anthropic API key	Your sk-ant-api03-... key, or leave blank for Claude Max

   Everything else (database passwords, encryption keys) is generated automatically.

   Once you confirm, the wizard checks that Docker is running, builds the images, and starts all four services. This takes 2–3 minutes on the first run.

3. Open the dashboard

   When the wizard finishes, navigate to:

   http://localhost:3001
   

   Log in with the admin credentials you just set. You’ll see the SlackHive dashboard.

Manual Setup

If you prefer to set things up yourself:

1. Clone the repository

   git clone https://github.com/pelago-labs/slackhive.git
   cd slackhive
   
2. Create your environment file

   cp .env.example .env
   

   Open .env and fill in these required values:

   # Claude (choose one)
   ANTHROPIC_API_KEY=sk-ant-api03-...
   
   # Database
   POSTGRES_DB=slackhive
   POSTGRES_USER=slackhive
   POSTGRES_PASSWORD=your-strong-password
   
   # Redis
   REDIS_PASSWORD=your-strong-password
   
   # Dashboard login
   ADMIN_USERNAME=admin
   ADMIN_PASSWORD=your-strong-password
   
   # Security keys — generate with: openssl rand -hex 32
   AUTH_SECRET=...
   ENV_SECRET_KEY=...
   
   NODE_ENV=production
   

   Generate strong values for AUTH_SECRET and ENV_SECRET_KEY with:

   openssl rand -hex 32
   
3. Start all services

   docker compose up -d --build
   

   This builds and starts four containers:

   Container	Port	Description
   web	3001	Management dashboard
   runner	—	Agent process host
   postgres	5432	Database
   redis	6379	Hot-reload event bus

   First run takes 2–3 minutes while images build.

4. Open the dashboard

   Navigate to http://localhost:3001 and log in.

Never commit your .env file. It contains secrets and is already listed in .gitignore.

Create your first agent

Once you’re logged into the dashboard, click New Agent in the sidebar. This opens a 5-step wizard.

1. Name & Role

   Give your agent:

   • Name — shown in Slack (e.g. “Data Analyst” or “Ava”)
   • Description — what this agent does. Keep it short — this is used by Boss agents to know who to delegate to.
   • Persona — how the agent should behave. This becomes its identity. Example:

   You are a data analyst who specializes in SQL queries and business metrics.
   You give concise, direct answers. You always show your SQL before running it.
   When you have results, lead with the key insight, then show the numbers.
   

   • Model — claude-sonnet-4-6 is a good default for most agents

   Leave the Boss toggle off for now. You can come back to that later.

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

   Your Slack bot now exists in your workspace. You’ll grab its credentials in the next step.

   Keep the Slack app settings tab open — you’ll need it for Step 3.

3. Enter Credentials

   You need three values from your Slack app. Go back to the Slack app settings tab:

   Bot Token

   • Go to OAuth & Permissions in the left sidebar
   • Copy the Bot User OAuth Token — it starts with xoxb-

   App Token

   • Go to Basic Information
   • Scroll to App-Level Tokens
   • Click Generate Token and Scopes
   • Give it any name (e.g. “socket-mode”)
   • Add the scope connections:write
   • Click Generate, then copy the token — it starts with xapp-

   Signing Secret

   • Still on Basic Information
   • Under App Credentials, click Show next to Signing Secret and copy it

   Paste all three into the wizard and click Verify Connection. If it fails, see Slack App Setup for troubleshooting.

4. Tools (Optional)

   Choose a starter template for your agent’s skill set:

   • Blank — clean slate
   • Data Analyst — SQL patterns, data summarization
   • Writer — content drafting, editing
   • Developer — code review, PR summaries

   You can also assign MCP servers here if you’ve added any to the catalog. MCP servers give agents access to external tools like databases and APIs. Skip this for now — you can add them later.

5. Review & Create

   Review the summary and click Create Agent.

   The runner picks up the new agent within a few seconds. You’ll see the agent status change to Active in the dashboard.

Test your agent in Slack

Your agent is now live. Let’s make sure it works.

1. Invite the bot to a channel

   In Slack, go to any channel and type:

   /invite @your-agent-name
   

   Replace your-agent-name with the bot’s Slack handle (it matches the name you gave it in the wizard).

2. Send a message

   @mention your agent:

   @your-agent-name hello, what can you help me with?
   

   You should see a typing indicator, then a response in the thread.

You can also DM the bot directly without inviting it to a channel. Open a new DM in Slack, find your agent by name, and start chatting.

If you don’t get a response, check the Logs tab on the agent’s detail page in the dashboard — it shows exactly what happened and any errors.

CLI reference

Once installed, the slackhive CLI gives you quick access to common operations:

Command	What it does
slackhive init	First-time setup wizard
slackhive start	Start all services
slackhive stop	Stop all services
slackhive status	Show running containers
slackhive logs	Tail the runner logs
slackhive update	Pull latest changes and rebuild

What’s next

Create a Boss Agent

Set up an orchestrator that routes requests to the right specialist automatically.

Connect MCP Servers

Give your agent real tools — query databases, read files, call APIs.

Agent Memory

Learn how agents remember context and get smarter over time.

Environment Variables

Full reference for all configuration options.