Appearance
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_smStep 2: Configure Environment
bash
# Copy example environment file
cp .env.example .envEdit .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.5Step 3: Start the Backend
bash
# From the backend directory
uvicorn app.main:app --reload --port 8000You 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 devYou should see:
VITE ready in XXX ms
➜ Local: https://localhost:5173/Step 5: First Chat
- Open https://localhost:5173 in your browser
- Accept the self-signed certificate warning
- You'll be prompted to enter your API key (if not in .env)
- 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:
- Navigate to Settings → SaaS Integrations
- Click Connect on Rippling (or another available connector)
- Review the consent dialog and authorize via OAuth
- Wait for the initial sync to complete (typically under 30 seconds for small orgs)
- 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/healthExpected 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.5Enable Code Protection
By default, code detection warns before sending. Change the policy:
bash
CODE_PROTECTION_POLICY=warn # warn, block, or redactSelect Industry Vertical
Configure industry-specific detection in the UI:
- Click Settings (gear icon)
- Select "Industry Vertical"
- 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/healthSlow 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.comAfter logging in as a platform admin:
- Invite your team — Admin Dashboard → Users → Invite (or paste multiple emails)
- Set up domains — Admin Dashboard → Team → Domains (for auto-join)
- Create invite links — Admin Dashboard → Team → Invite Links (for Slack/email distribution)
- Configure SCIM — Admin Dashboard → Team → SCIM (for Okta/Azure AD provisioning)
- 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
- Full Installation Guide - Docker, production setup
- Production Deployment - On-premise with Let's Encrypt HTTPS
- Configure Your Vertical - Industry-specific settings
- PII Detection Deep Dive - All 50+ entity types
- API Reference - Build integrations
- OpenAI-Compatible API - Use GhostAI as OpenAI proxy
- MCP Server - Integrate with Cursor IDE, Claude Desktop
- Dashboards & Analytics - Team management and activity monitoring