Skip to main content

​
Quick Start Guide

This guide will help you set up Gorkie locally and connect it to your Slack workspace.

​
Prerequisites

Before you begin, make sure you have:
  • Bun installed on your machine
  • Git for cloning the repository
  • Slack workspace admin access to create and install apps
  • Redis instance (local or cloud)
  • PostgreSQL database (recommend Neon for serverless)

​
Step 1: Clone the Repository

Clone the Gorkie repository and install dependencies: 
git clone https://github.com/imdevarsh/gorkie-slack.git
cd gorkie-slack
bun install

​
Step 2: Create a Slack App

Gorkie includes a pre-configured manifest file that sets up all required permissions and features.
1

Navigate to Slack Apps

Go to https://api.slack.com/apps and click Create New App
2

Create from Manifest

Select From an app manifest and choose your workspace
3

Use the Manifest

Copy the contents of slack-manifest.json from the repository root and paste it into the manifest editor
4

Review and Create

Review the configuration and click Create. Slack will set up all the necessary features automatically
The manifest configures OAuth scopes, event subscriptions, Socket Mode, and the assistant view. See the Slack Setup guide for detailed explanations of each permission.

​
Step 3: Configure Environment Variables

Copy the example environment file and configure your credentials: 
cp .env.example .env
Edit .env with your configuration:

​
Required: Slack Credentials

.env
# Socket Mode token (from App-Level Tokens in Slack settings)
SLACK_APP_TOKEN="xapp-your-app-token"

# Bot User OAuth Token (from OAuth & Permissions)
SLACK_BOT_TOKEN="xoxb-your-bot-token"

# Signing Secret (from Basic Information)
SLACK_SIGNING_SECRET="your-signing-secret"

# Enable Socket Mode for local development
SLACK_SOCKET_MODE=true
For Socket Mode to work, you need to generate an App-Level Token with the connections:write scope in your Slack app settings under Basic Information > App-Level Tokens.

​
Required: Redis and Database

.env
# Redis for rate limiting and caching
REDIS_URL="redis://localhost:6379"

# PostgreSQL database (Neon recommended)
DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"

​
Required: AI Provider

You need at least one AI provider. Gorkie supports:
.env
# Hack Club AI (primary provider)
HACKCLUB_API_KEY="sk-hc-your-hackclub-api-key"

# OpenRouter (secondary provider)
OPENROUTER_API_KEY="sk-or-your-openrouter-api-key"

​
Required: E2B for Code Execution

.env
# E2B API key from https://e2b.dev/
E2B_API_KEY="your-e2b-api-key"

​
Optional: Additional Services

.env
# Exa for web search
EXA_API_KEY="your-exa-api-key"

# Langfuse for observability
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_BASEURL="https://cloud.langfuse.com"

# Logging configuration
LOG_LEVEL="info"
LOG_DIRECTORY="logs"

​
Step 4: Initialize the Database

Push the database schema to your PostgreSQL instance: 
bun run db:push
This creates the necessary tables for scheduled tasks and other persistence features.

​
Step 5: Build the E2B Sandbox Template

Gorkie uses a custom E2B template with preinstalled tools. Build it with: 
bun run sandbox:build
This creates a template called gorkie-sandbox:latest with fd, ripgrep, imagemagick, ffmpeg, pip, and pillow preinstalled.
The sandbox template only needs to be built once. It’s automatically used when the bot starts up.

​
Step 6: Start the Development Server

Start Gorkie in watch mode for development: 
bun run dev
For production, use: 
bun run start

bun run dev
You should see log output indicating the bot has connected to Slack via Socket Mode.

​
Step 7: Install to Your Workspace

In your Slack app settings:
1

Navigate to OAuth & Permissions

Go to OAuth & Permissions in the sidebar
2

Install to Workspace

Click Install to Workspace and authorize the bot
3

Copy Bot Token

Copy the Bot User OAuth Token (starts with xoxb-) to your .env file if you haven’t already

​
Step 8: Test Gorkie in Slack

Gorkie responds to:
  • @mentions in channels
  • Direct messages
  • Thread replies when Gorkie is already in the conversation
Try these commands: 
@gorkie Hi there! Can you help me?

​
Development Commands

Useful commands for development: 
# Start dev server with hot reload
bun run dev

# Start production server
bun run start

# Database management
bun run db:studio      # Open Drizzle Studio
bun run db:push        # Push schema changes
bun run db:generate    # Generate migrations
bun run db:migrate     # Run migrations

# Code quality
bun run check          # Check code formatting
bun run check:write    # Fix formatting issues
bun run typecheck      # Type check with TypeScript

​
Next Steps

Slack Setup Details

Learn about OAuth scopes, event subscriptions, and Socket Mode

Configuration

Explore advanced configuration options and rate limiting

​
Troubleshooting

  • Verify SLACK_APP_TOKEN is set and has connections:write scope
  • Check that Socket Mode is enabled in your Slack app settings
  • Ensure the bot is invited to the channel (use /invite @gorkie)
  • Check logs for connection errors
  • Verify DATABASE_URL format is correct
  • For Neon, ensure ?sslmode=require is appended
  • Run bun run db:push to create tables
  • Check that your database accepts connections from your IP
  • Verify E2B_API_KEY is set correctly
  • Run bun run sandbox:build to create the template
  • Check E2B dashboard for quota limits
  • Review logs for specific sandbox errors
  • Verify Redis connection with REDIS_URL
  • Check Redis is running (redis-cli ping)
  • Review rate limit configuration in code

Build docs developers (and LLMs) love

Get started for freeTalk to us