Skip to main content

Setup Guide

This guide covers the complete setup process for Agility, including environment configuration, service integrations, and credential management.
If you’re deploying your own instance of Agility, follow this guide. If you’re using a hosted version, skip to Service Integrations.

Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ or Bun runtime
  • Supabase account (free tier available)
  • API keys for services you plan to use:
    • OpenAI API key for GPT models
    • Anthropic API key for Claude models
    • GitHub Personal Access Token for repository monitoring
    • Discord Webhook URL for notifications
    • Gmail OAuth credentials for email automation

Installation

1

Clone the Repository

git clone https://github.com/yourusername/agility.git
cd agility
2

Install Dependencies

Choose your preferred package manager:
npm install
3

Configure Environment Variables

Create a .env.local file in the root directory:
.env.local
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
Never commit your .env.local file to version control. It contains sensitive credentials.
4

Start the Development Server

npm run dev
# or
yarn dev
# or
bun dev
The application will be available at http://localhost:3000.

Supabase Setup

Create Your Supabase Project

1

Create a New Project

  1. Go to supabase.com
  2. Click “New Project”
  3. Enter project details and select a region
  4. Wait for the database to initialize (2-3 minutes)
2

Get Your Project Credentials

Navigate to SettingsAPI and copy:
  • Project URL: NEXT_PUBLIC_SUPABASE_URL
  • Anon/Public Key: NEXT_PUBLIC_SUPABASE_ANON_KEY
Paste these into your .env.local file.
3

Enable Email Authentication

Go to AuthenticationProviders and ensure Email is enabled. This allows users to sign up and sign in.

Deploy Edge Functions

Agility uses Supabase Edge Functions for serverless workflow execution. Deploy them using the Supabase CLI:
1

Install Supabase CLI

npm install -g supabase
2

Link Your Project

supabase link --project-ref your-project-ref
Find your project ref in the Supabase dashboard under SettingsGeneral.
3

Deploy All Functions

supabase functions deploy
This deploys all Edge Functions in the supabase/functions directory:
  • generate-workflow - AI workflow generation
  • generate-text - Text generation with GPT/Claude
  • manage-workflows - Save and load workflows
  • manage-api-keys - Secure credential storage
  • read-gmail - Gmail integration
  • send-gmail - Gmail sending
  • send-discord - Discord messaging
  • read-github - GitHub repository monitoring
  • run-workflow - Workflow execution engine

Create Database Tables

Run these SQL commands in the Supabase SQL Editor (DatabaseSQL Editor):
-- Workflows table
CREATE TABLE workflows (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  name TEXT,
  data JSONB NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Agent configurations table
CREATE TABLE agent_configs (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  element_id TEXT NOT NULL,
  agent_id TEXT NOT NULL,
  config JSONB NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  UNIQUE(user_id, element_id)
);

-- API keys table (encrypted)
CREATE TABLE api_keys (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  element_id TEXT NOT NULL,
  encrypted_key TEXT NOT NULL,
  model TEXT,
  prompt TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  UNIQUE(user_id, element_id)
);

-- Agent connections table
CREATE TABLE agent_connections (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  workflow_id UUID REFERENCES workflows(id) ON DELETE CASCADE,
  source_element_id TEXT NOT NULL,
  target_element_id TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE workflows ENABLE ROW LEVEL SECURITY;
ALTER TABLE agent_configs ENABLE ROW LEVEL SECURITY;
ALTER TABLE api_keys ENABLE ROW LEVEL SECURITY;
ALTER TABLE agent_connections ENABLE ROW LEVEL SECURITY;

-- Create policies
CREATE POLICY "Users can manage their own workflows"
  ON workflows FOR ALL
  USING (auth.uid() = user_id);

CREATE POLICY "Users can manage their own configs"
  ON agent_configs FOR ALL
  USING (auth.uid() = user_id);

CREATE POLICY "Users can manage their own API keys"
  ON api_keys FOR ALL
  USING (auth.uid() = user_id);

CREATE POLICY "Users can manage their own connections"
  ON agent_connections FOR ALL
  USING (workflow_id IN (
    SELECT id FROM workflows WHERE user_id = auth.uid()
  ));
Row Level Security (RLS) ensures users can only access their own data, providing built-in multi-tenancy.

Service Integrations

OpenAI (GPT Models)

1

Get Your API Key

  1. Visit platform.openai.com/api-keys
  2. Click “Create new secret key”
  3. Copy the key (it won’t be shown again)
2

Add to Agility

In the workflow builder, click a Text Generator agent and paste your API key. Select a GPT model:
  • GPT-3.5 Turbo: Fast and cost-effective
  • GPT-4: More capable, higher quality
  • GPT-4 Turbo: Faster GPT-4 with lower cost
3

Test the Integration

Click “Test Agent” to verify your API key works. You should see generated text in the response.

Anthropic (Claude Models)

1

Get Your API Key

  1. Visit console.anthropic.com
  2. Navigate to API Keys
  3. Click “Create Key” and copy it
2

Configure in Agility

In the Text Generator configuration, select a Claude model:
  • Claude 3 Haiku: Fastest, most affordable
  • Claude 3 Sonnet: Balanced performance
  • Claude 3 Opus: Most capable Claude model
Paste your Anthropic API key and test.

Gmail Integration

Gmail requires OAuth authentication for secure access:
1

Create Google Cloud Project

  1. Go to console.cloud.google.com
  2. Create a new project
  3. Enable the Gmail API
2

Configure OAuth Consent Screen

  1. Navigate to APIs & ServicesOAuth consent screen
  2. Select External and fill in required details
  3. Add scopes: gmail.readonly and gmail.send
3

Create OAuth Credentials

  1. Go to CredentialsCreate CredentialsOAuth client ID
  2. Select Web application
  3. Add authorized redirect URI:
http://localhost:3000/gmail-oauth-callback
  1. Copy the Client ID and Client Secret
4

Authenticate in Agility

In the Gmail Reader or Gmail Sender agent configuration:
  1. Click “Connect Gmail”
  2. Sign in with Google
  3. Grant permissions
  4. You’ll be redirected back to Agility with credentials saved
// The gmail-oauth Edge Function handles the OAuth flow
const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code&scope=https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send`;

Discord Webhooks

1

Create a Webhook

  1. Open your Discord server
  2. Go to Server SettingsIntegrationsWebhooks
  3. Click “New Webhook”
  4. Select a channel and copy the webhook URL
2

Configure in Agility

In the Discord Messenger agent configuration:
{
  "webhookUrl": "https://discord.com/api/webhooks/123456789/abcdefgh",
  "message": "Your automated message here"
}
You can use dynamic fields from previous agents:
New email from {{gmail-reader.sender}}: {{text-generator.summary}}
3

Test the Webhook

Click “Test Agent” - you should see a message appear in your Discord channel.

GitHub Integration

1

Create Personal Access Token

  1. Go to github.com/settings/tokens
  2. Click “Generate new token (classic)”
  3. Select scopes: repo (for private repos) or public_repo (for public only)
  4. Copy the token
2

Configure GitHub Reader

In the GitHub Reader agent:
{
  "token": "ghp_your_github_token",
  "owner": "username",
  "repo": "repository-name"
}
3

Set Up Webhook (Optional)

For real-time push notifications:
  1. Go to your repository SettingsWebhooks
  2. Add webhook URL: {SUPABASE_URL}/functions/v1/github-webhook
  3. Select “Push events”
  4. Agility will automatically trigger workflows when code is pushed

Security Best Practices

Follow these security guidelines to protect your credentials and workflows.

API Key Storage

All API keys are encrypted before storage:
// Keys are encrypted using Supabase's built-in encryption
await fetch(`${supabaseUrl}/functions/v1/manage-api-keys`, {
  method: 'POST',
  body: JSON.stringify({
    action: 'save',
    elementId,
    apiKey // Encrypted server-side
  })
});

Row Level Security

All database tables use RLS policies to ensure users only access their own data:
CREATE POLICY "Users can manage their own workflows"
  ON workflows FOR ALL
  USING (auth.uid() = user_id);

Environment Variables

  • Never commit .env.local to version control
  • Use different credentials for development and production
  • Rotate API keys regularly
  • Use Supabase’s built-in secrets for Edge Functions

Deployment

Deploy to Vercel

1

Connect Repository

  1. Go to vercel.com
  2. Click “Import Project”
  3. Connect your GitHub repository
2

Configure Environment

Add your environment variables in Vercel:
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
3

Deploy

Click “Deploy” - Vercel will build and deploy your application. Your workflow builder will be live at your-app.vercel.app.

Update OAuth Redirects

After deployment, update your OAuth redirect URIs:
https://your-app.vercel.app/gmail-oauth-callback
Add this to your Google Cloud Console OAuth credentials.

Troubleshooting

Edge Function Errors

Issue: Edge function returns 500 error Solution: Check logs in Supabase dashboard under Edge FunctionsLogs

Authentication Issues

Issue: Unable to sign in or sign up Solution: Verify email auth is enabled in Supabase under AuthenticationProviders

API Key Not Persisting

Issue: API key disappears after page refresh Solution: Ensure you clicked “Save Configuration” and the success message appeared

Gmail OAuth Fails

Issue: OAuth redirect shows error Solution:
  • Verify redirect URI matches exactly (including http/https)
  • Check OAuth consent screen is configured
  • Ensure Gmail API is enabled in Google Cloud Console

Next Steps

Build Workflows

Start creating automated workflows

Agent Reference

Detailed documentation for each agent type

API Documentation

Integrate workflows via REST API

Best Practices

Learn workflow optimization techniques

Build docs developers (and LLMs) love