Self-hosting AgentLasso

AgentLasso's core is Apache-2.0: you can run it on your own infrastructure. This guide covers what you need, what works without which keys, and what doesn't work outside the hosted service yet.

Just want to look around? npm run demo runs the whole app locally on fixed mock data, with no accounts, keys or database. Everything below is for a real install.

What you need

  • Node.js ≥ 20.19 or ≥ 22.12. Older versions fail at runtime with a util.styleText error rather than at install time.
  • A Supabase project (the free tier is fine): Postgres, auth and the API layer.
  • Optional: an Anthropic API key for AI intent classification. Traces are processed as they arrive (live or imported); a scheduler is only useful at high volume (see step 4).

1. Install

sh
git clone https://github.com/agentlassohq/agentlasso.gitcd agentlassonpm install        # or: bun install (bun.lock is the canonical lockfile)cp .env.example .env

2. Create the database

  1. Create a project at supabase.com.
  2. Apply the migrations in supabase/migrations/ in filename order. With the Supabase CLI:
    sh
    npx supabase link --project-ref YOUR-PROJECT-REFnpx supabase db push
    Or paste each file into the Supabase SQL editor, oldest first.
  3. Fill in the Supabase section of .env (Settings → API in Supabase). Keep SUPABASE_SERVICE_ROLE_KEY secret: it bypasses row-level security.
  4. In Supabase → Authentication → URL Configuration, add your app's URL (e.g. http://localhost:8080, the dev server's default) to the redirect URLs, so email confirmation links come back to your install.

The migrations create a demo template project ("Acme Support Agent"). Every new account gets an empty workspace of its own plus a copy of the template as a separate Sample project, so a first-time user can explore a populated app without the example data mixing into their numbers. The template's API key is randomized by a migration, so the key that appears in the repo's history doesn't work on your install.

3. Run it

sh
npm run dev

Sign up with email and password, then open Settings for your project's API key and a ready-to-run curl command to send your first trace.

Which features need what

FeatureNeeds
Trace ingestion (simple JSON or OTLP), Production SyncSupabase only
Intent classification by tool-matching rules (free)Supabase only
AI intent classification for traces the rules can't placeANTHROPIC_API_KEY (you pay Anthropic directly)
Background classification job (uses Anthropic's Batch API, 50% cheaper)ANTHROPIC_API_KEY; runs as traces arrive. An optional scheduler needs LOVABLE_CRON_SECRET
Dataset Studio, checks, CI eval runs (/api/v1/eval-runs)Supabase only
AI judge checks (plain-English criteria graded by Claude)An Anthropic key: each project's own (Settings → AI judge), or set JUDGE_ALLOW_SERVER_KEY=true to let projects use ANTHROPIC_API_KEY. Model: JUDGE_MODEL (default claude-sonnet-5-5)
Connecting your agent (Settings → Your agent), "Run my agent" in the rubric previewSupabase only. Set AGENT_ENDPOINT_ALLOW_PRIVATE=true to allow http:// and private/local addresses (e.g. an agent on your own network)
Semantic grouping (Settings → Semantic grouping, on by default for new projects): embeds each trace's user requestVOYAGE_API_KEY (model voyage-4-lite), or an OpenAI-compatible endpoint: EMBEDDINGS_BASE_URL + EMBEDDINGS_MODEL (+ EMBEDDINGS_API_KEY), with a model that outputs 1024 dimensions. Needs the vector (pgvector) extension, which the migrations enable. Embeds up to 512 traces per run of the background job
AI test generationNot available self-hosted yet (see below)
"Continue with Google" sign-inNot available self-hosted (email sign-in works)

Without ANTHROPIC_API_KEY, traces the rules can't place wait (marked awaiting_llm), and the Semantic Agent Map shows how many. Add a key later and the next run classifies them.

4. Background processing (no scheduler needed)

Traces are classified and embedded when traffic arrives: after the telemetry endpoint responds, it processes the project's waiting traces in the background. One request per project at a time does the work (a short database lease), so parallel traffic doesn't classify the same traces twice. Small backlogs go to Claude right away; large ones (50+ waiting) go through the cheaper Batch API, and later traffic collects the results.

So there's nothing to schedule. Optionally, at high volume, or to process waiting traces when no new traffic is coming in, call POST /api/v1/sync-cluster with Authorization: Bearer <LOVABLE_CRON_SECRET>, by hand or on a schedule. If your fork is on GitHub, the included .github/workflows/sync-cluster.yml can do this; set the AGENTLASSO_APP_URL and LOVABLE_CRON_SECRET repository secrets.

Deploying

npm run build produces a Cloudflare Workers build (the build config's cloudflare-module preset). Set the variables from .env as Worker environment variables and secrets.

Other targets (a plain Node server, Docker) aren't supported out of the box yet: the build configuration only offers Cloudflare and a Lovable-internal format. Contributions welcome.

Not available self-hosted (yet)

  • AI test generation calls Lovable's AI gateway (LOVABLE_API_KEY), which only exists on Lovable-hosted deployments. Self-hosted, it shows an explanation instead.
  • "Continue with Google" goes through Lovable's OAuth broker, so it's hidden on self-hosted installs. Email sign-in works.

Security checklist

  • Never commit .env; it's in .gitignore.
  • SUPABASE_SERVICE_ROLE_KEY, ANTHROPIC_API_KEY and LOVABLE_CRON_SECRET are secrets: set them server-side only.
  • Leave AGENT_ENDPOINT_ALLOW_PRIVATE unset if untrusted users can sign up: it lets them make your server call addresses on its own network.
  • Found a vulnerability? See SECURITY.md.