HalosHalosDocs

External Services

Halos integrates with a range of external services for AI, storage, communication, and data access. This page documents each integration and its role.

Core Infrastructure

Supabase

Role: Database, authentication, realtime subscriptions

  • PostgreSQL with Row Level Security
  • Auth (email/password + OAuth)
  • Realtime for live feed updates
  • RPC functions for atomic operations

Pinecone

Role: Vector database for semantic search (RAG)

  • Index: agents (configurable via PINECONE_INDEX)
  • Namespace: user:{userId} (per-user isolation)
  • Dimensions: 1536 (OpenAI text-embedding-3-small)
  • Used by: knowledge_search tool, memory extraction, onboarding context

Vercel

Role: Hosting and serverless compute

  • Next.js app deployed on Vercel
  • API routes run as serverless functions (60s max duration)
  • Streaming responses via streamText()

AI Providers

Anthropic

Role: Primary LLM provider

  • Models: Claude Sonnet 4, Haiku 4.5, Opus 4.6
  • Used for: Agent chat, greetings, knowledge extraction, onboarding
  • Env: ANTHROPIC_API_KEY

OpenAI

Role: Embeddings + alternative LLM

  • Embeddings: text-embedding-3-small (1536 dimensions)
  • Models: GPT-4o, GPT-4o-mini, GPT-4.1
  • Used for: Vector embeddings, optional agent model
  • Env: OPENAI_API_KEY

Google

Role: Alternative LLM provider

  • Models: Gemini 2.0 Flash, 2.5 Pro, 2.5 Flash
  • Env: GOOGLE_GENERATIVE_AI_API_KEY

Communication

Resend

Role: Email delivery and inbound processing for agent inboxes

  • Each agent gets a unique email address (e.g. travel-ad67cd@mail.halos.sh)
  • Agents can send and receive emails
  • Inbound emails stored in agent_emails table with image analysis
  • Env: RESEND_API_KEY

ElevenLabs

Role: Text-to-speech for agent voice calls

  • Model: eleven_flash_v2_5
  • Each agent can have a unique voice (voice_id in agents table)
  • Used by: Voice call feature, Telegram voice messages
  • Env: ELEVENLABS_API_KEY

Data Extraction

Firecrawl

Role: Web page content extraction

  • Endpoint: https://api.firecrawl.dev/v1/scrape
  • Extracts page content as markdown
  • Used by: web_scrape tool, onboarding link scraping (LinkedIn, GitHub, any URL)
  • Env: FIRECRAWL_API_KEY

Apify

Role: Social media profile scraping

  • Twitter/X scraper: apidojo~twitter-user-scraper
  • Instagram scraper: instagram-scraper~instagram-profile-scraper
  • Used during: Onboarding (auto-scrape shared social links)
  • Env: APIFY_API_TOKEN

Brave Search

Role: Web search

  • Endpoint: https://api.search.brave.com/res/v1/web/search
  • Returns top results with titles, URLs, descriptions
  • Used by: web_search tool
  • Env: BRAVE_API_KEY

OAuth Integrations

These are connected per-user via OAuth flows. Tokens are encrypted at rest in the user_integrations table.

Google (Gmail + Calendar)

Scopes:

  • gmail.readonly — Read inbox
  • calendar.readonly — Read events
  • calendar.events — Create/modify events
  • userinfo.email — Get user email

Tools powered: read_emails, read_calendar, create_event

Env: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

Notion

Scopes: read_content, update_content, insert_content

Tools powered: notion_read, notion_write

Features:

  • Auto-creates "Agents" folder on connection
  • Stores workspace_id and agents_folder_id in metadata

Slack

Scopes: channels:read, chat:write, users:read, groups:read

Status: Connected but not yet exposed as agent tools (planned)

GitHub

Scopes: repo, read:user, user:email

Status: Connected but not yet exposed as agent tools (planned)

Environment Variables Summary

| Variable | Required | Service | |----------|----------|---------| | ANTHROPIC_API_KEY | Yes | Claude models | | OPENAI_API_KEY | Yes | Embeddings + GPT models | | PINECONE_API_KEY | Yes | Vector database | | PINECONE_INDEX | No | Index name (default: agents) | | MAILGUN_API_KEY | Yes | Agent email | | MAILGUN_DOMAIN | Yes | Email domain | | AGENT_EMAIL_DOMAIN | Yes | Agent email domain | | FIRECRAWL_API_KEY | Recommended | URL scraping + web_scrape tool | | BRAVE_API_KEY | Recommended | web_search tool | | APIFY_API_TOKEN | Optional | Social scraping during onboarding | | ELEVENLABS_API_KEY | Optional | Agent voice | | GOOGLE_CLIENT_ID | Optional | Gmail/Calendar OAuth | | GOOGLE_CLIENT_SECRET | Optional | Gmail/Calendar OAuth | | GOOGLE_GENERATIVE_AI_API_KEY | Optional | Gemini models | | CRON_SECRET | Yes | Cron endpoint auth | | ENCRYPTION_KEY | Yes | Token encryption |