Environment Setup

ExploreSelf-hostDocumentationBlogSign In
Documentation
Overview
Getting Started
Getting StartedPlatform IntegrationsAgentPlaybooks in ClaudePortable Bot TeamsHermes Memory ProviderHermes for OrganisationsAgentPlaybooks Tools in HermesCLI & Editor PluginsPython SecretsCross-platform Agent BackupsRelease DistributionTeam CollaborationFederated MCP & OpenAPI ToolsMCP Registry PublishingRoadmap
Core Concepts
PlaybooksSkillsMemoryMCP Integration
Reference
ArchitectureAPI ReferenceManagement APIDeveloper GuideSelf-HostingEnvironment Setup
View on GitHub
DocsEnvironment Setup

Environment Setup Guide

Required Environment Variables

Create a .env.local file in the project root with these variables:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
# Server-only key for Secrets Vault encryption (64-char hex, 32 bytes)
SECRETS_ENCRYPTION_KEY=your-64-char-hex-key
# Application URL (for production)
NEXT_PUBLIC_APP_URL=https://apbks.com

OAuth Configuration (CRITICAL)

OAuth redirect URLs must be configured in the Supabase Dashboard, not in code.

Supabase Dashboard Settings

  • Go to Supabase Dashboard → Authentication → URL Configuration

  • Set Site URL to your production domain:
https://apbks.com

  • Add Redirect URLs for both production and development:
https://apbks.com/**
   http://localhost:3000/**

GitHub OAuth Setup

  • Go to GitHub Developer Settings → OAuth Apps

  • Create new OAuth App or edit existing:
- Application name: AgentPlaybooks - Homepage URL: https://apbks.com - Authorization callback URL: https://.supabase.co/auth/v1/callback

  • Copy the Client ID and Client Secret to Supabase:
- Supabase Dashboard → Authentication → Providers → GitHub

Google OAuth Setup

  • Go to Google Cloud Console → Credentials

  • Create OAuth 2.0 Client ID:
- Application type: Web application - Authorized JavaScript origins: - https://apbks.com - http://localhost:3000 - Authorized redirect URIs: - https://.supabase.co/auth/v1/callback

  • Copy credentials to Supabase:
- Supabase Dashboard → Authentication → Providers → Google

LinkedIn OAuth Setup

  • Go to LinkedIn Developer Portal

  • Create new app and configure:
- Authorized redirect URLs: https://.supabase.co/auth/v1/callback

  • Copy credentials to Supabase:
- Supabase Dashboard → Authentication → Providers → LinkedIn (OIDC)

Cloudflare Pages Deployment

When deploying to Cloudflare Pages, set these environment variables:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SECRETS_ENCRYPTION_KEY=your-64-char-hex-key
NEXT_PUBLIC_APP_URL=https://apbks.com

Common Issues

OAuth redirects to localhost in production

Cause: Supabase "Site URL" is set to localhost or missing.

Fix: Set Site URL to https://apbks.com in Supabase Dashboard → Authentication → URL Configuration.

404 on OAuth callback

Cause: GitHub/Google OAuth callback URL is incorrect.

Fix: Ensure callback URL is https://.supabase.co/auth/v1/callback (NOT your app domain).

Secrets creation fails with "Internal Server Error"

Cause: SECRETS_ENCRYPTION_KEY is missing or invalid in your runtime environment.

Fix:

  • Generate a key:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  • Set it as SECRETS_ENCRYPTION_KEY in your deployment environment.
  • Redeploy/restart the app.

Edit this page on GitHub
On this page
Required Environment VariablesOAuth Configuration (CRITICAL)Supabase Dashboard SettingsGitHub OAuth SetupGoogle OAuth SetupLinkedIn OAuth SetupCloudflare Pages DeploymentCommon IssuesOAuth redirects to localhost in production404 on OAuth callbackSecrets creation fails with "Internal Server Error"