> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install SlackHive

> Install and run SlackHive with the slackhive CLI.

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

| Platform                      | Supported | Login 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

```bash theme={null}
npm install -g slackhive
```

<Accordion title="Hit EACCES: permission denied?">
  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:

  ```bash theme={null}
  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](https://github.com/nvm-sh/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`).
</Accordion>

## Run the setup wizard

```bash theme={null}
slackhive init
```

The wizard asks a few questions:

| Prompt                | What to enter                                   |
| --------------------- | ----------------------------------------------- |
| **Install directory** | Where to put SlackHive (default: `./slackhive`) |
| **Admin username**    | Your login for the dashboard                    |
| **Admin password**    | A 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.

| Backend          | Login path                                      | API key path        |
| ---------------- | ----------------------------------------------- | ------------------- |
| **OpenAI Codex** | `codex login` -> `~/.codex/auth.json`           | `OPENAI_API_KEY`    |
| **Claude Code**  | `claude login` -> `~/.claude/.credentials.json` | `ANTHROPIC_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.

<Note>
  See [AI Backends](/configuration/ai-backends) for backend selection, model migration, and auth details.
</Note>

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

| Path                                      | What it holds                                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `~/.slackhive/data.db`                    | SQLite 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.log`            | Runner log (also streamed live in the UI)                                                       |
| `~/.slackhive/runner.lock`                | Single-runner lock file                                                                         |

## Next steps

<CardGroup cols={2}>
  <Card title="Create your first agent" icon="robot" href="/agents/creating-agents">
    Walk the two-step agent flow.
  </Card>

  <Card title="CLI operations" icon="terminal" href="/operations/cli">
    `start`, `stop`, `status`, `logs`, `update`.
  </Card>
</CardGroup>