This guide covers local development and production. Slackzilla contains a Slack bot, a dashboard/webhook server, and a React client built with Vite.
xoxb-...) as SLACK_BOT_TOKEN.connections:write and set it as SLACK_APP_TOKEN.SLACK_SIGNING_SECRET.manifest.json (or just copy whatever is in manifest.json into App Manifest > replace all existing content with it > Save Changes > Install App).The bot uses Socket Mode, so it does not require a public inbound Slack HTTP endpoint.
Copy bot/.env.example to bot/.env and set:
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
AI_API_KEY=... # optional
AI_MODEL=openai/gpt-6-luna
AI_URL=https://ai.hackclub.com/proxy/v1/chat/completions
Copy server/.env.example to server/.env and set:
WEBHOOK_SECRET=...
PORT=9000
PROJECT_DIR=/absolute/path/to/slackzilla
BRANCH=main
REPO_URL=https://github.com/your-user/slackzilla.git
ADMIN_PASSWORD_HASH=pbkdf2$sha512$600000$salt$derived-key
ADMIN_SESSION_SECRET=...
COOKIE_SECURE=false
The dashboard reads bot/.env for the bot token during local development. Keep secrets out of version control. PROJECT_DIR must exist; it is used for the webhook (CI/CD deployment)
Use the bot command, ask the ai assistant or use the dashboard to generate a hash for you:
/sz-hash pbkdf2 sha512 600000 your-password
Copy the returned pbkdf2$... value into ADMIN_PASSWORD_HASH. PBKDF2 is explained in security.md.
Install dependencies:
npm ci
For React hot reload:
npm run dev
This serves the client at http://localhost:5173, but does not start the API, telemetry, logs, or bot.
For the complete local runtime:
npm start
This builds and lints the client, then starts the bot, the api, the RAG and dashboard server. The dashboard is available at http://localhost:9000. On Windows, Linux-only actions such as systemctl and Bash deployment are expected not to work.
/ public dashboard./status host, process, disk, network, and bot telemetry./commands command reference and trusted command runner./ai repository-aware question answering and related visual assets./api HTTP endpoint reference./docs in-app developer documentation./logs bounded log viewer./admin/login admin session flow./admin authenticated controls and feedback management.Set AI_API_KEY and restart the server to enable model answers. The assistant retrieves text outside priv/, ignores environment files and dependencies, and can return relevant images from assets/attachments/. It does not parse binary image contents.
The public API accepts:
{
"question": "How does the feedback API work?"
}
Command execution is explicit and should be treated as trusted functionality because commands may generate secrets, call external services, or mutate data.
The AI endpoint exposes a controlled tool set to the model. The model may request these tools while processing POST /api/ask:
getStatus current status without telemetryHistory
getCommands available command metadata (with filters)
getReleaseInfo current version and release-history changes
runCommand allowlisted read-only utility command output
getLogs latest 10 log entries
getErrors latest 10 structured errors (stacks opt-in)
getMetrics current runtime metrics
getRoutes routes discovered by the RAG index
Start the dashboard server first, then send a normal AI request. The response is SSE, so use an SSE-capable client or curl:
For release questions, getReleaseInfo reads package.json, release-history.json, and the /sz-release implementation at bot/cmds/release.js. It is also available directly as GET /api/release, with an optional ?version=v0.9.5-beta query parameter.
To test the repository pipeline without contacting an AI provider:
npm run rag -- "How does the /api/ask request flow work?" # this returns what the ai recieves
add --ai to see the AI’s response.
To call tools directly, use npm run rag:use-tool with the tool name: e.g.
npm run rag:use-tool -- --getStatus
npm run rag:use-tool -- --getCommands
npm run rag:use-tool -- --getReleaseInfo
npm run rag:use-tool -- --getLogs
npm run rag:use-tool -- --getErrors
npm run rag:use-tool -- --getMetrics
npm run rag:use-tool -- --getRoutes
This direct adapter call still enforces the read-only allowlist, timeout, output-size limit, sanitisation, and activity events. See RAG.md for the complete data flow and security boundaries.
On Linux:
cp bot/.env.example bot/.env
cp server/.env.example server/.env
npm ci and configure both .env files.npm run build.server/slackzilla.service and server/slackzilla-webhook.service to /etc/systemd/system/.cp server/slackzilla.service /etc/systemd/system/
cp server/slackzilla-webhook.service /etc/systemd/system/
sudo apt update
sudo systemctl daemon-reload
sudo systemctl enable --now slackzilla.service slackzilla-webhook.service
Restart after code or environment changes:
sudo systemctl restart slackzilla
sudo systemctl restart slackzilla-webhook
Use a reverse proxy for HTTPS and set COOKIE_SECURE=true when HTTPS is active.
npm run build
npm run lint
npm run validate-manifest
npm run validate-commands
Then test:
curl -i http://localhost:9000/api/status
curl -i http://localhost:9000/api/commands
curl -i http://localhost:9000/api/ask
Use an API client for JSON POST requests, authenticated APIs, CSRF headers, and webhook signatures.
| Symptom | Check |
|---|---|
| Bot will not connect | Slack tokens, signing secret, app scopes, and Socket Mode. |
| AI returns configuration text | AI_API_KEY, AI_URL, and AI_MODEL; restart after changes. |
| Admin login loops | Password hash, session secret, cookie settings, and HTTPS/COOKIE_SECURE. |
| Feedback reply fails | Bot token must be available to the dashboard process and the user ID must be valid. |
| Disk is unavailable | Confirm PROJECT_DIR exists and is readable. |
| Webhook returns 401 | Compare WEBHOOK_SECRET and raw-body signature; see webhook.md. |
| Service action fails locally | Control actions target Linux systemd hosts. |
| Dashboard changes are missing | Rebuild and restart the dashboard service. |
For implementation details read api.md, architecture.md, and security.md.