Running locally

If you don’t want to use the Superagent Cloud you can optionally run Superagent localy. In order to make Superagent more modular we have decoupled the Superagent API from the Superagent UI. You can run the API directly by just leveraging the SDKs. Follow the guides below to get started.

Setup Superagent API

Getting started

  1. Clone the Superagent repository and open the superagent folder.

    $git clone
    >cd superagent
  2. Navigate to libs/superagent and copy the .env.example to a new file named .env.

    $cd libs/superagent
    >cp .env.example .env

Set .env variables

In order to get Superagent running we need to set some mandatory environment variables. Here is an example:

># We use Supabase but you can use any provider.
># You can setup Supabase locally or via Supabase Cloud
># Use a password-like string
># Depending on which vector db you want to use you need to setup the corresponding auth variables.
># Learn more about which vector databases are avaialable here:
># You can use the Superagent hosted memory or setup memory yourself.
># We recommend using Motorhead by Metal:
># AgentOps
># Automatically track costs, session replays, and agent benchmarks. Sign up for a key at []( # Using the default org key in .env.example will include added premium features.
># Langfuse observability
># LangSmith observability
># E2B Code Interpreter
># Run Replicate models as tools

Create a virtual env

In the console, create a virtual environment to install and run the python api.

$# cd libs/superagent
>virtualenv venv

Then activate the new virtual environment to work in it.

$# Linux/Mac
>source venv/bin/activate
$# Windows (bash)
>source venv/Scripts/activate

Install dependencies

Use poetry to install the project dependencies in the virtual environment

$# cd libs/superagent
>poetry install

Start Supabase

$supabase start

Get Supabase Info

Get the hostname and port of your Supabase instance and replace them in the DATABASE_URL and DATABASE_MIGRATION_URL variable in your .env file.

$supabase status

Run database migrations

$prisma generate
>prisma migrate dev

Start the server

$uvicorn app.main:app --reload
># Uvicorn running on (Press CTRL+C to quit)
># API available at

Use local API with the Superagent SDK

1import os
2from superagent.client import Superagent
4client = Superagent(
5 token=os.environ["SUPERAGENT_API_KEY"], # replace with your Superagent API
6 base_url="" # or your local environment

And that’s it! You now have an instance of the Superagent API running on your local machine. Make sure to checkout the REST API reference for more details on each API endpoint or visit to view the Swagger docs.

Setup Superagent UI

Setup Supabase

The Superagent UI is setup using Supabase. It leverages the Supabase’s Auth and Storage modules. Configure your Supabase setup as per the instructions below:

  1. Clone the Superagent repository
$git clone
  1. Navigate to /libs/ui

  2. Install Supabase CLI and create project:

  3. Start the local Supabase project

$supabase start
  1. Run the database migrations
$# Local supabase project
>supabase migration up
># Supabase Cloud project
>supabase db push
  1. Create a Supabase storage with the following storage.objects permissions:
Screenshot 2023-09-14 at 23 27 35

Setup authentication

Superagent supports password-less authentication and GitHub OAuth. You may add which ever Authentication provider supported by Supabase.

  1. Create a new GitHub OAuth app in your GitHub account

  2. Copy the CLIENT_ID and CLIENT_SECRET and paste them into the /libs/ui/.env variables in your local Superagent project.

  3. Set the following callback URL

  1. Navigate to your Supabase project you have created for Superagent UI and paste the CLIENT_ID and CLIENT_SECRET
Screenshot 2023-09-15 at 09 08 52

NOTE: You can enable any provider using the steps above.

Set .env variables

  1. Change the name of .env.example to .env in /libs/ui.

  2. Set the required environment variables.

># Supabase variables found inside of the Supabase dashboard (local or remote)
># Tracing
># GitHub OAuth
># Superagent API URL
># Optional for connecting to Google Drive, Dropbox, Box and OneDrive.
># Optional for adding billing
># Optional for recording human feedback with Langfuse

Run app

  1. From inside /libs/ui run:
$npm i
  1. Start the app
npm run dev

You should now be able to visit http://localhost:3000 and see the Superagent login page