Skip to main content
Gorkie uses environment variables for configuration. All variables are validated using Zod schemas defined in server/env.ts.

​
Setup

Copy the .env.example file to .env in the source directory: 
cp .env.example .env
Then populate the variables with your actual values.
Never commit your .env file to version control. It contains sensitive credentials.

​
Slack Configuration

These variables configure the Slack app connection and behavior.
​
SLACK_BOT_TOKEN
string
required
Bot User OAuth Token from OAuth & Permissions section in your Slack app.
SLACK_BOT_TOKEN="xoxb-your-bot-token"
​
SLACK_SIGNING_SECRET
string
required
Signing secret used to verify requests from Slack.
  • Get it from: Basic Information section of your Slack app
  • Used to validate webhook authenticity
SLACK_SIGNING_SECRET="your-signing-secret"
​
SLACK_APP_TOKEN
string
App-level token for Socket Mode. Required if SLACK_SOCKET_MODE=true.
SLACK_APP_TOKEN="xapp-your-app-token"
​
SLACK_SOCKET_MODE
boolean
default:"false"
Enable Socket Mode for receiving events (recommended for local development).
  • true: Use WebSocket connection (requires SLACK_APP_TOKEN)
  • false: Use HTTP endpoints (requires public URL and PORT)
  • Default: false
SLACK_SOCKET_MODE=true
​
PORT
number
default:"3000"
HTTP port to listen on when Socket Mode is disabled.
PORT=3000
​
AUTO_ADD_CHANNEL
string
Channel ID to automatically add users to when they first mention the bot.
  • Format: Slack channel ID (e.g., C12345678)
  • Use case: Onboarding users to a community channel
AUTO_ADD_CHANNEL="C12345678"
​
OPT_IN_CHANNEL
string
Channel ID that users must join before they can use Gorkie beyond simple pings.
  • Format: Slack channel ID (e.g., C12345678)
  • Use case: Require opt-in for advanced features
OPT_IN_CHANNEL="C12345678"

​
AI Providers

Gorkie supports multiple AI model providers. Both are currently required.
​
HACKCLUB_API_KEY
string
required
Primary AI model provider API key from Hack Club.
HACKCLUB_API_KEY="sk-hc-your-hackclub-api-key"
​
OPENROUTER_API_KEY
string
required
Secondary AI model provider API key from OpenRouter.
OPENROUTER_API_KEY="sk-or-your-openrouter-api-key"

​
Database

​
DATABASE_URL
string
required
PostgreSQL database connection string.
  • Format: postgresql://user:password@host:5432/dbname?sslmode=require
  • Supports: Postgres, Neon, or any Postgres-compatible database
  • Used for: Storing sandbox sessions and scheduled tasks
DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"
See Database Setup for detailed instructions.

​
Redis

​
REDIS_URL
string
required
Redis connection string for caching and rate limiting.
  • Format: redis://host:port or rediss://host:port (SSL)
  • Local: redis://localhost:6379
  • Cloud: Varies by provider (Upstash, Redis Cloud, etc.)
REDIS_URL="redis://localhost:6379"
See Redis Setup for detailed instructions.

​
E2B Sandbox

​
E2B_API_KEY
string
required
API key for E2B code execution sandboxes.
  • Get it from: https://e2b.dev/
  • Used for: Secure code execution in isolated environments
  • Template: Auto-builds gorkie-sandbox:latest if missing
E2B_API_KEY="your-e2b-api-key"
​
AGENTMAIL_API_KEY
string
required
API key for AgentMail service (used by sandbox environment).
  • Format: Must start with am_
  • Used for: Email functionality in sandbox sessions
AGENTMAIL_API_KEY="am_your-agentmail-key"
​
EXA_API_KEY
string
required
API key for Exa web search functionality.
EXA_API_KEY="your-exa-api-key"

​
Observability (Langfuse)

Langfuse provides tracing and observability for AI model calls.
​
LANGFUSE_SECRET_KEY
string
Secret key for Langfuse tracing.
LANGFUSE_SECRET_KEY="sk-lf-..."
​
LANGFUSE_PUBLIC_KEY
string
Public key for Langfuse tracing.
  • Format: Starts with pk-lf-
  • Required with: LANGFUSE_SECRET_KEY
LANGFUSE_PUBLIC_KEY="pk-lf-..."
​
LANGFUSE_BASEURL
string
default:"https://cloud.langfuse.com"
Langfuse API base URL.
  • EU region: https://cloud.langfuse.com (default)
  • US region: https://us.cloud.langfuse.com
  • Self-hosted: Your instance URL
LANGFUSE_BASEURL="https://cloud.langfuse.com"

​
Logging

​
LOG_LEVEL
string
default:"info"
Logging verbosity level for Pino logger.
  • Options: debug, info, warn, error
  • Production: Use info or warn
  • Development: Use debug for detailed logs
LOG_LEVEL="info"
​
LOG_DIRECTORY
string
default:"logs"
Directory path for log file output.
  • Relative or absolute path
  • Created automatically if it doesn’t exist
LOG_DIRECTORY="logs"

​
Runtime

​
NODE_ENV
string
default:"development"
Runtime environment mode.
  • Options: development, production, test
  • Affects: Logging format, error handling, and performance optimizations
NODE_ENV="production"

​
Validation

All environment variables are validated on startup using Zod schemas in server/env.ts. If any required variable is missing or invalid, the application will fail to start with a descriptive error message. 
// Example from server/env.ts
export const env = createEnv({
  server: {
    SLACK_BOT_TOKEN: z.string().min(1),
    OPENROUTER_API_KEY: z.string().min(1).startsWith('sk-or-'),
    // ... more validations
  },
  runtimeEnv: process.env,
});
Access environment variables in code via env.VARIABLE_NAME, not process.env.VARIABLE_NAME. This ensures type safety and validation.

Build docs developers (and LLMs) love

Get started for freeTalk to us