Getting Started

# Prerequisites

• • Docker & Docker Compose. OASIS runs as five containers. Install Docker Desktop (includes Compose v2) on macOS/Windows, or Docker Engine + Compose plugin on Linux.
• • At least one LLM API key. An OpenAI key is the easiest starting point. You can also use Google AI Studio, Anthropic, Mistral, Scaleway, or self-hosted endpoints.
• • (For voice agents) STT & TTS keys. Deepgram for speech-to-text, ElevenLabs for text-to-speech. Not needed for voice-to-voice models (OpenAI Realtime, Gemini Live) or text chat agents.

# Installation

Clone the repository and copy the environment template:

$ git clone https://github.com/oasis-surveys/oasis-platform.git
$ cd oasis-platform
$ cp .env.example .env

Then start everything:

$ docker compose up -d

This pulls and builds five containers: Caddy (reverse proxy + auto-SSL), React frontend, FastAPI backend, PostgreSQL (with pgvector), and Redis. The dashboard will be available at http://localhost.

# Configuration

All configuration lives in a single .env file. Here's the essential structure:

# ── Application ──
APP_NAME=OASIS
SECRET_KEY=change-me-to-a-random-secret-key

# ── Database ──
POSTGRES_USER=oasis
POSTGRES_PASSWORD=change-me
POSTGRES_DB=oasis

# ── AI Providers (add what you need) ──
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=...
ELEVENLABS_API_KEY=...

# ── Optional Providers ──
GOOGLE_API_KEY=...            # For Gemini Live
SCALEWAY_SECRET_KEY=...      # For Scaleway LLMs
ANTHROPIC_API_KEY=...        # For Claude

# ── Telephony (Optional) ──
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1...

# ── Domain (use localhost for dev) ──
DOMAIN=localhost

# Your First Agent

1. 1 Open the dashboard at http://localhost and click New Study.
2. 2 Give your study a name and description. Click Create.
3. 3 Inside the study, click New Agent. Choose Voice or Text modality.
4. 4 Write your system prompt. This is the instruction that shapes the agent's behaviour. Tell it what to ask, how to probe, and when to wrap up.
5. 5 Select your LLM model and pipeline type (voice-to-voice or modular STT→LLM→TTS).
6. 6 Set the agent status to Active and save. Copy the interview link or embed code.

# Structured Interviews

For semi-structured protocols, set the Interview Mode to Structured when creating an agent. You can then define an interview guide with ordered questions, follow-up probes, and transition messages.

You can build the guide directly in the dashboard, or upload a CSV or JSON file. Download the template from the dashboard to see the expected format:

// interview-guide.json
{
  "questions": [
    {
      "text": "Can you tell me about your experience with...?",
      "probes": [
        "What specific aspects stood out?",
        "How did that compare to your expectations?"
      ],
      "max_follow_ups": 3,
      "transition": "Thank you, now I'd like to ask about..."
    }
  ],
  "closing_message": "Thank you for your time."
}

The agent will follow the guide as a backbone but can adapt naturally. It probes when appropriate, moves on after the configured number of follow-ups, and uses transition messages between questions.

# Text Chat Agents

When you select Text as the modality, the agent conducts interviews via a chat interface instead of voice. No STT or TTS keys are needed.

• • Choose from several avatar styles: Robot, Neutral, Male, Female, or None.
• • The transcript output format is identical to voice agents, same export, same analytics.
• • Works with any chat-compatible LLM (GPT-4.1, Claude, Gemini, etc.).

# Model Selection

OASIS uses LiteLLM under the hood, which means you can use virtually any LLM provider with a unified API format.

# Deployment Options

# Authentication

Authentication is off by default. To enable basic login protection for the dashboard:

# In .env:
AUTH_ENABLED=true
AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password

Then recreate the backend container: docker compose up -d --force-recreate backend. Interview links remain publicly accessible. Authentication only protects the admin dashboard.

# Telephony (Twilio)

OASIS supports telephone-based interviews via Twilio Media Streams. Add your Twilio credentials to .env, assign a phone number to an agent in the dashboard, and participants can call in for voice interviews.

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1234567890

The backend exposes a TwiML webhook that Twilio calls when someone dials your number. Audio is streamed over WebSockets using Pipecat's TwilioFrameSerializer.

# Knowledge Base (RAG)

Upload documents to a study's knowledge base to give your agent context about the research topic. Documents are chunked, embedded using OpenAI's text-embedding-3-small, and stored in PostgreSQL via pgvector for similarity search.

During an interview, the agent can query the knowledge base to retrieve relevant context before generating a response. This is especially useful for topic-specific interviews where the agent needs factual grounding.

# API Reference

The FastAPI backend serves auto-generated OpenAPI documentation. Once your instance is running:

• • Swagger UI: http://localhost/api/docs
• • ReDoc: http://localhost/api/redoc

Key endpoints include: