Skip to main content
The slackhive CLI installs, configures, and runs SlackHive on your machine. It clones the repo, generates a .env file, installs dependencies, builds the apps, and starts the services. Data lands in a local SQLite database.

​
Prerequisites

  • Node.js 20 or later - node --version to check
  • One AI backend credential path before you run agents:
    • OpenAI Codex / ChatGPT login or an OpenAI API key
    • Claude Code login or an Anthropic API key
  • A Slack workspace where you can install apps
  • Git (for the initial clone)

​
Platform support

PlatformSupportedLogin credential source
macOS (Intel + Apple Silicon)✅~/.codex/auth.json, Keychain / ~/.claude/.credentials.json
Linux with GNOME/KDE keyring✅~/.codex/auth.json, secret-tool / ~/.claude/.credentials.json
Linux headless (server)✅~/.codex/auth.json, ~/.claude/.credentials.json, or API keys
WSL2 on Windows✅Same as Linux
Windows (native)❌Use WSL2

​
Install the CLI

npm install -g slackhive
If you installed Node from nodejs.org on macOS/Linux, /usr/local/lib/node_modules is root-owned and npm install -g fails without sudo. Point npm at a user-owned prefix - one-time setup:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
npm install -g slackhive
Installing Node via nvm or Homebrew (brew install node) avoids this entirely - both install Node in a user-writable location. Or skip global install with npx slackhive init (prefix every command with npx).

​
Run the setup wizard

slackhive init
The wizard asks a few questions:
PromptWhat to enter
Install directoryWhere to put SlackHive (default: ./slackhive)
Admin usernameYour login for the dashboard
Admin passwordA strong password
Once you confirm, the CLI:
  1. Clones the SlackHive repo into your install directory
  2. Generates a .env file with a fresh encryption key
  3. Installs dependencies and builds the web + runner apps
  4. Starts the services
First run takes 2–3 minutes while everything builds.

​
Backend credentials

SlackHive can run agents on Codex/OpenAI or Claude/Anthropic. Connect credentials after the first launch in Settings → AI Backend, or provide API keys in .env and select the active backend in the dashboard.
BackendLogin pathAPI key path
OpenAI Codexcodex login -> ~/.codex/auth.jsonOPENAI_API_KEY
Claude Codeclaude login -> ~/.claude/.credentials.jsonANTHROPIC_API_KEY

​
Codex notes

  • Settings can start a device-auth login flow and persist the resulting auth.json.
  • For servers, use OPENAI_API_KEY or paste CODEX_AUTH_JSON in Settings.
  • Set CODEX_PATH only when SlackHive should use a specific codex binary.

​
Claude notes

  • macOS Keychain and ~/.claude/.credentials.json are both supported.
  • Headless servers can use ANTHROPIC_API_KEY or paste CLAUDE_CREDENTIALS_JSON in Settings.
  • Set CLAUDE_BIN only when SlackHive should use a specific claude binary.
See AI Backends for backend selection, model migration, and auth details.

​
API key path

API keys work identically on macOS, Linux, and WSL. Use OPENAI_API_KEY for Codex/OpenAI or ANTHROPIC_API_KEY for Claude/Anthropic.

​
Open the dashboard

When the wizard finishes: 
http://localhost:3001
Log in with the admin credentials you set. You’re ready to create your first agent.

​
Where things live

PathWhat it holds
~/.slackhive/data.dbSQLite database - agents, memories, skills, history
~/.slackhive/agents/<slug>/Per-agent workspace - instructions, sessions, skills, memories, copies of assigned wiki folders
~/.slackhive/knowledge/<folderId>/wiki/Compiled wikis for the Knowledge Library (source of truth)
~/.slackhive/logs/runner.logRunner log (also streamed live in the UI)
~/.slackhive/runner.lockSingle-runner lock file

​
Next steps

Create your first agent

Walk the two-step agent flow.

CLI operations

start, stop, status, logs, update.