Skip to content

Quick Start Guide ​

Get GhostAI running locally in 5 minutes.

Prerequisites ​

  • Python 3.11+
  • Node.js 18+
  • An LLM API key (OpenAI, OpenRouter, or Ollama)

Step 1: Clone and Setup Backend ​

bash
# Clone the repository
git clone https://github.com/ghostai/ghostai.git
cd ghostai/securechat

# Setup backend
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Download language model for PII detection
python -m spacy download en_core_web_sm

Step 2: Configure Environment ​

bash
# Copy example environment file
cp .env.example .env

Edit .env and add your API keys. On first startup, these keys are automatically registered as platform defaults in the database, making them visible and manageable in the Platform Admin > Provider Keys UI. You can configure multiple providers simultaneously; each configured key enables a direct route to that provider:

bash
# LLM Providers (at least one required; multiple can be active)
OPENAI_API_KEY=sk-your-openai-key-here
OPENROUTER_API_KEY=sk-or-your-openrouter-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
OLLAMA_BASE_URL=http://localhost:11434

# Detection settings (optional)
PII_SCORE_THRESHOLD=0.5

Step 3: Start the Backend ​

bash
# From the backend directory
uvicorn app.main:app --reload --port 8000

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

Step 4: Setup and Start Frontend ​

Open a new terminal:

bash
# From the securechat directory
cd frontend
npm install
npm run dev

You should see:

VITE ready in XXX ms
➜  Local:   https://localhost:5173/

Step 5: First Chat ​

  1. Open https://localhost:5173 in your browser
  2. Accept the self-signed certificate warning
  3. You'll be prompted to enter your API key (if not in .env)
  4. Try sending a message with PII:
Hi, my name is John Smith and my SSN is 123-45-6789. 
Can you help me understand tax deductions?

You'll see:

  • The SSN highlighted in the input
  • A tokenized version sent to the AI
  • The AI's response with the original SSN restored

Step 6: Connect Your SaaS Tools (Optional) ​

If you want the AI to understand your organization — employees, teams, departments — connect your SaaS tools:

  1. Navigate to Settings → SaaS Integrations
  2. Click Connect on Rippling (or another available connector)
  3. Review the consent dialog and authorize via OAuth
  4. Wait for the initial sync to complete (typically under 30 seconds for small orgs)
  5. Ask the AI: "Who's on the engineering team?"

SaaS Integrations require a Personal or higher subscription and SAAS_CONNECTORS_ENABLED=true in your environment configuration.

See SaaS Integrations for full documentation.

Verify It's Working ​

Check the Audit Log ​

The sidebar shows a shield icon with the count of protected items. Click it to see:

  • Entity types detected (SSN, PERSON, etc.)
  • Confidence scores
  • Token mappings

API Health Check ​

bash
curl http://localhost:8000/health

Expected response:

json
{
  "status": "healthy",
  "version": "1.0.0",
  "detectors": {
    "presidio": true,
    "ner": true,
    "code": true
  }
}

Quick Configuration ​

Change Detection Threshold ​

Lower threshold = more sensitive (more false positives) Higher threshold = less sensitive (may miss some PII)

bash
# In .env file
PII_SCORE_THRESHOLD=0.7  # Default is 0.5

Enable Code Protection ​

By default, code detection warns before sending. Change the policy:

bash
CODE_PROTECTION_POLICY=warn   # warn, block, or redact

Select Industry Vertical ​

Configure industry-specific detection in the UI:

  1. Click Settings (gear icon)
  2. Select "Industry Vertical"
  3. Choose your industry (Healthcare, Financial, etc.)

Troubleshooting ​

"ModuleNotFoundError: No module named 'presidio_analyzer'" ​

bash
pip install presidio-analyzer presidio-anonymizer

"OPENAI_API_KEY not set" ​

Make sure your .env file is in the backend directory and contains a valid key.

"Connection refused" on frontend ​

Ensure the backend is running on port 8000:

bash
curl http://localhost:8000/health

Slow first request ​

The first request loads ML models into memory. Subsequent requests are faster.

Admin Setup (Teams) ​

If you're setting up GhostAI for a team, configure admin access:

bash
# In .env file — Used for initial admin setup
PLATFORM_ADMIN_EMAIL=admin@company.com

# Optional: Used for initial admin setup
CLOUD_ADMIN_EMAIL=ops@company.com

After logging in as a platform admin:

  1. Invite your team — Admin Dashboard → Users → Invite (or paste multiple emails)
  2. Set up domains — Admin Dashboard → Team → Domains (for auto-join)
  3. Create invite links — Admin Dashboard → Team → Invite Links (for Slack/email distribution)
  4. Configure SCIM — Admin Dashboard → Team → SCIM (for Okta/Azure AD provisioning)
  5. Check setup progress — Admin Dashboard → Setup for a detailed walkthrough, or glance at the banner at the top of the dashboard for quick progress

Next Steps ​

SOC 2 Type II Certified | BAA Available | HIPAA-Ready