How can we help you?

WorkSpace is a fully self-hosted enterprise workspace - a single platform covering 15 business modules: email, messaging, incidents, projects, knowledge base, CRM, calendar, HR, analytics, and more. Every byte of your data stays on your server.

The stack is a Go binary (backend) + MongoDB (data) + nginx (reverse proxy), all orchestrated via Docker Compose. There are no external databases, no SaaS dependencies - just your server.

Architecture overview

• Go backend - single binary serving all APIs, auth, email SMTP/IMAP, and AI
• MongoDB - single database holding all org data (email, incidents, projects…)
• Ollama (optional) - local LLM inference container, runs on-device
• nginx - TLS termination, reverse proxy to port 8080

WorkSpace is licensed under EL2 (Elastic License 2.0) - you can self-host freely for any use, including commercial. You may not offer WorkSpace as a managed service to third parties.

WorkSpace runs on any Linux server with Docker installed. Recommended specs:

• OS: Ubuntu 22.04 LTS, Debian 12, Rocky Linux 9, or any ARM64/AMD64 Linux
• CPU: 2 vCPU minimum; 4 vCPU for AI features; 4+ for Ollama local inference
• RAM: 2 GB minimum; 4 GB recommended; 8 GB for running Ollama
• Disk: 20 GB minimum SSD; grows with email data
• Docker: 20.10+ with Docker Compose v2
• Ports: 80, 443, 8080 (app); 25, 587, 993 (email - optional)

Run this single command on your Linux server. It launches an interactive wizard that checks prerequisites, collects configuration, generates secrets, and starts all services.

curl -fsSL https://karyospace.com/install.sh | bash

The wizard asks for: organisation name, domain, admin email, Okta SSO credentials (optional), and AI provider choice. All secrets are auto-generated. After ~5 minutes, WorkSpace is running and the installer confirms with a health check.

See the full Getting Started guide for a step-by-step walkthrough.

Updates pull the latest Docker image and recreate the app container. Your data (MongoDB volumes, .env file) is never touched during an update.

cd ~/workspace
docker compose pull
docker compose up -d

Typical downtime: under 60 seconds. The old container keeps serving requests until the new one is healthy.

All data lives in MongoDB. Use mongodump to create a point-in-time backup:

# Backup
docker compose exec mongodb mongodump \
  --db workspace \
  --out /data/backup/$(date +%Y-%m-%d)

# Restore
docker compose exec mongodb mongorestore \
  --db workspace \
  /data/backup/2026-05-24/workspace

Also back up your .env file - it contains the encryption keys needed to decode DKIM private keys stored in MongoDB. Without the DKIM_ENCRYPTION_KEY, backed-up DKIM data cannot be recovered.

WorkSpace runs a complete email stack - no Gmail or Microsoft 365 required. Your organisation owns all mail data. The stack includes:

• SMTP inbound (port 25/2525) - receives email from the internet for your domain
• SMTP submission (port 587/2587) - sends outbound email, requires authentication
• IMAP (port 993/1993) - allows mail clients (Outlook, Apple Mail, Thunderbird) to connect

Supported folders: INBOX, Sent, Drafts, Trash, Spam. The spam scorer evaluates keywords, SPF result, all-caps ratio, and bulk headers - spam above threshold 5 lands in Spam automatically.

Outbound email includes DKIM signing with a per-domain key stored encrypted in MongoDB. Brevo relay is supported for bootstrapping IP reputation.

Add all four record types for reliable delivery. Propagation takes 5–30 minutes (up to 48h in rare cases).

• A record: mail → your-server-ip - the mail server hostname
• MX record: @ → mail.yourdomain.com (priority 10) - routes inbound email to your server
• TXT (SPF): @ → v=spf1 ip4:your-ip ~all - authorises your server to send for your domain
• TXT (DKIM): karyo._domainkey → (from Admin → Email → DKIM) - cryptographic signature verification
• TXT (DMARC): _dmarc → v=DMARC1; p=none; adkim=r; aspf=r - alignment policy

New server IPs have no reputation. Email providers (Gmail, Outlook) may reject or spam-folder your messages for the first week. Using Brevo as a relay avoids this during warm-up.

Add to your .env:

SMTP_RELAY_HOST=smtp.brevo.com
SMTP_RELAY_PORT=587
SMTP_RELAY_USER=your-brevo-login
SMTP_RELAY_PASS=your-smtp-key

After 2–4 weeks of consistent sending (low bounces, no spam reports), your IP's reputation improves and you can remove the relay config to send directly.

WorkSpace speaks standard IMAP and SMTP - any mail client works. Use these settings:

• IMAP Server: mail.yourdomain.com, port 993 (TLS) or 1993 (dev)
• SMTP Server: mail.yourdomain.com, port 587 (STARTTLS) or 2587 (dev)
• Username: your full email address (e.g. alice@yourdomain.com)
• Password: your WorkSpace account password

WorkSpace scores every inbound message before delivery. Emails scoring ≥5 are delivered to Spam; below 5 go to INBOX. Score components:

• +1–3: Keyword matches (free, winner, click here, urgent, act now…)
• +2: SPF fail (sender not authorised for the sending domain)
• +1: More than 20% of words are ALL CAPS
• +2: Bulk headers present (List-Unsubscribe, Precedence: bulk)
• 0: Internal emails (127.0.0.1 loopback) are always exempt from spam scoring

The Messaging module is WorkSpace's internal chat - separate from email, for real-time team communication. Key features:

• Direct messages - one-on-one conversations with any team member
• Group channels - create channels for teams or topics
• On-call routing - assign on-call engineers visible to the AI assistant ("Who's on call this week?")
• Message search - the AI can search message history ("Find messages about the deployment yesterday")

Messages are stored in MongoDB collection msg_messages and are included in the AI RAG pipeline.

The AI assistant uses Retrieval Augmented Generation (RAG) - it searches your org's data in MongoDB, assembles relevant context (up to 3,000 characters), and passes it to the LLM to generate a grounded answer.

Step-by-step flow:

1. Your question is classified: Is it a RAG query (searching org data) or a general question?
2. If RAG: MongoDB $text search runs across emails, incidents, projects, knowledge base, and messages
3. Top results are assembled into a context block with numbered citations
4. Context + your question is sent to the configured LLM (Groq, Gemini, or Ollama)
5. The answer is returned and the exchange added to your personal conversation history (20-message rolling window for follow-up questions)

Example queries that trigger RAG: "Show me recent incidents about patient data", "What did the client say about pricing?", "Find emails about the outage last Tuesday".

Edit your .env and recreate the container:

LLM_PROVIDER=groq
LLM_MODEL=llama-3.3-70b-versatile
GROQ_API_KEY=gsk_your_key

LLM_PROVIDER=ollama
LLM_MODEL=gemma3:1b
OLLAMA_BASE_URL=http://localhost:11434

After editing, run: docker compose stop workapp && docker compose rm -f workapp && docker compose up -d workapp

The AI searches your org data using MongoDB's full-text index. Better results come from:

• Be specific: "Incidents involving the patient portal in March" beats "show me incidents"
• Name entities: Use project names, person names, system names that appear in your data
• Follow-up questions work: The assistant keeps a 20-message conversation history - you can say "Who was responsible?" after a search result and it knows the context
• Seed your knowledge base: Upload SOPs, runbooks, and policies to the Knowledge module - the AI searches these too

Response time depends heavily on your LLM provider:

• Groq: ~1–2 seconds - fastest option, cloud-based, free tier
• Gemini: ~2–4 seconds - fast, Google Cloud
• Ollama (gemma3:1b): ~8–15 seconds CPU-only - private, on-device
• Ollama (gemma3:4b): ~40–160 seconds CPU-only - very slow without a GPU

For Ollama: the first query after server restart is slow (model loading). Subsequent queries are faster. Use gemma3:1b or phi4-mini for best CPU performance. A GPU reduces inference time by 10–20×.

This usually means either the data isn't in MongoDB, or the text index isn't matching. Check:

1. Is the data seeded? Run the seed script: docker compose exec workapp ./workspace seed --db workspace
2. Does the collection have a text index? Check via the admin panel → DataView
3. Is your query a RAG trigger? The classifier requires specific phrases ("show me", "find", "what", "who", "recent", "about"). Statements like "Tell me the incidents" may not trigger RAG.
4. Check the AI query log: Admin → AI Queries to see what context was retrieved

Navigate to Incidents in the sidebar. Each incident has: title, severity (P0–P4), status (Open/Investigating/Resolved), assigned team, and a full timeline of updates.

• Create: Click "New Incident" → fill title, severity, and description
• Update: Add timeline entries as the incident progresses - these become searchable by AI
• Resolve: Set status to Resolved and add a root cause note
• P0/P1 incidents trigger automatic notifications to all Admins and Managers

The AI can retrieve incidents: "Show me all P0 incidents in the last 30 days" or "What caused the authentication outage?"

Projects are containers for tasks. Navigate to Projects to create a project with name, description, owner, and due date. Inside each project:

• Add tasks with assignee, priority (Low/Medium/High/Critical), and due date
• Track status: Todo → In Progress → Review → Done
• View team workload from the Projects dashboard

AI queries: "What projects are due this week?" or "What's Alice working on?"

The Knowledge module stores SOPs, runbooks, policies, and reference documents. Upload content via the Knowledge page - drag and drop or paste text directly.

• Documents are chunked and indexed for AI search automatically
• Tag articles with categories (HR, Engineering, Legal, etc.) for organisation
• AI can cite knowledge articles: "What does our HIPAA policy say about patient data?"

MongoDB collections: knowledge_docs (full documents) and knowledge_chunks (indexed segments for RAG).

Notes are private to each user - other team members cannot see your notes. Navigate to Notes (or press G N) to create, edit, and search your personal notes. Notes support Markdown formatting.

Unlike other modules, notes are not included in the org-wide AI RAG search - they are strictly personal.

The Home page is your default landing page after login. It surfaces the most important information from across all modules in one view.

What's on the Home page

• AI Chat widget - type any question about your org's data (emails, incidents, projects) and get an instant grounded answer. Press Space to focus the input.
• Recent incidents - open P0/P1/P2 incidents are pinned at the top so critical issues are never missed
• Unread messages - direct messages and mentions from the Messaging module
• My tasks - project tasks assigned to you, sorted by due date
• Recent emails - latest unread emails from your INBOX

Quick actions

The quick-action bar lets you create a new incident, start a message, or compose an email without navigating away from Home. All modules are reachable from the left sidebar.

Navigate to Calendar (or press G C) to view and manage scheduled events. The calendar shows your personal events and any team events you have been invited to.

Creating events

• Click any time slot on the calendar to open the new event form
• Set title, start/end time, location, description, and invite attendees by email
• Invited attendees receive a notification and can accept or decline

Views

• Day view - hourly breakdown for the current day
• Week view - Monday-to-Sunday overview with event blocks
• Month view - full month grid with event dots

AI queries work with calendar data: "What meetings do I have tomorrow?" or "Who is on leave this week?"

The Team module has two sub-sections: the team directory (your org's employees) and the contacts / CRM (external clients, vendors, and partners).

Team directory

• See all employees with role, department, and contact info
• Click any team member to view their profile, open incidents assigned to them, and active project tasks
• On-call status is set here and visible to the AI ("Who is the on-call engineer right now?")

Contacts / CRM

• Add external contacts (clients, vendors, partners) with company, email, phone, and tags
• Link contacts to email threads and incidents for full context
• AI can retrieve CRM data: "What did Acme Corp say about the contract?" will search linked emails and notes

Navigate with G T.

The Analytics module surfaces operational metrics derived from your org's data - no external BI tool required.

What's tracked

• Incidents: Open vs resolved counts, mean time to resolution (MTTR), incidents by severity over time
• Email: Volume sent/received per day, top senders, spam rate
• Projects: Tasks completed vs overdue, throughput by team member
• AI usage: Query volume, most common query topics, RAG hit rate

AI-powered insights

The AI Insights tab on the Analytics page lets you ask free-form questions about your metrics: "Which team member resolved the most incidents last month?" or "Show me email volume trends for April." The AI generates a natural-language summary with the underlying data.

WorkSpace sends notifications for events that need your attention. Notifications appear in the bell icon (top-right nav) and optionally via email.

Notification types

• Incident alerts: P0 and P1 incidents notify all Admins and Managers automatically
• Mentions: When a team member @mentions you in a message or incident update
• Task assignments: When a project task is assigned or reassigned to you
• Email notifications: New email in INBOX (configurable - can be disabled for high-volume inboxes)
• System alerts: Admin-only — certificate expiry, MongoDB storage warnings

Managing preferences

Go to your Profile → Notifications to toggle each notification type on or off, and choose whether to receive email copies alongside in-app notifications. P0/P1 incident notifications cannot be disabled for Admin and Manager roles.

The Trace module gives Admins visibility into what WorkSpace is doing internally - essential for debugging and compliance. Access via the sidebar → Trace.

What you can see

• Request log: Every API call with method, path, latency, and HTTP status
• Email trace: Inbound/outbound email events - SMTP session, spam score, delivery result
• AI query log: Every AI request with the query, RAG context retrieved, LLM used, and latency
• Auth events: Logins, logouts, failed attempts, session expiry
• System health: MongoDB connection state, active goroutines, memory usage

Press / from any page to open the global search bar. It searches across all modules simultaneously - emails, incidents, projects, knowledge articles, messages, contacts, and notes.

What it searches

• Emails: Subject, sender, recipient, and body (first 500 chars)
• Incidents: Title, description, and timeline updates
• Projects & tasks: Project name, task title, and description
• Knowledge base: Document titles and full content
• Messages: Channel names and message text
• Contacts: Name, email, company

Search tips

• Results are ranked by text relevance using MongoDB's $text index
• Use specific terms - "AWS outage" finds more than "problem"
• The AI chat on Home is better for questions; global search is better for finding specific records

Access your profile by clicking your avatar (top-right) → Profile, or press Ctrl ,.

Profile settings

• Display name and avatar - shown to teammates in messages and assignments
• Change password - requires your current password; takes effect immediately
• Notification preferences - toggle which events send in-app and email notifications
• Theme - switch between dark and light mode (also available via the moon/sun icon in the top-right)
• Time zone - affects how times are displayed in Calendar and incident timelines

Installing WorkSpace as a PWA

WorkSpace is a Progressive Web App - you can install it on your device for a native-app-like experience with no browser chrome, offline access to cached pages, and push notifications.

• Desktop (Chrome/Edge): Click the install icon in the address bar, or go to browser menu → "Install WorkSpace"
• iOS Safari: Tap the Share button → "Add to Home Screen"
• Android Chrome: Tap the three-dot menu → "Add to Home Screen"

Go to /admin and click Users. From here you can:

• View all accounts, their role, and last login
• Change a user's role (Employee / Manager / Admin)
• Enable or disable accounts without deleting data
• Reset passwords (sends a reset link to the user's email)

The ADMIN_USERS env variable is the source of truth for which emails have admin rights - changes here take effect on next login without a restart.

docker compose restart does not re-read --env-file. To apply .env changes you must recreate the container:

docker compose stop workapp
docker compose rm -f workapp
docker compose up -d workapp

Your MongoDB data and volumes are untouched. Only the app container is recreated. Downtime is typically under 15 seconds.

Navigate to /admin/audit. Every significant action is logged with: user, action type, target resource, IP address, and timestamp. Audit entries are immutable - they cannot be edited or deleted.

Managers and Admins can view the audit log. Use it to investigate data changes, user access patterns, or compliance requirements (SOC 2, HIPAA).

WorkSpace uses Okta as its identity provider (IdP) for SSO. Users log in through Okta - no separate WorkSpace passwords needed when SSO is enabled.

Step 1 — Create an Okta OIDC app

1. In your Okta admin console, go to Applications → Create App Integration
2. Choose OIDC - OpenID Connect and Web Application
3. Set Sign-in redirect URI to: https://yourdomain.com/auth/okta/callback
4. Set Sign-out redirect URI to: https://yourdomain.com
5. Assign the app to the groups or users who should have access

Step 2 — Add to .env

OKTA_ISSUER=https://dev-xxxxx.okta.com/oauth2/default
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_REDIRECT_URI=https://yourdomain.com/auth/okta/callback

Recreate the container to apply: docker compose stop workapp && docker compose rm -f workapp && docker compose up -d workapp

WorkSpace creates a mailbox automatically when you create a user account. You can also manage mailboxes and email domains directly from the Admin panel.

Adding an email domain

1. Go to /admin → Email → Domains → Add Domain
2. Enter the domain name (e.g. yourdomain.com)
3. WorkSpace generates a DKIM key pair and shows you the DNS TXT record to add
4. Add the record to your DNS provider, then click Verify

Creating a mailbox

Go to /admin → Email → Mailboxes → New Mailbox. Set the email address, display name, and link it to a WorkSpace user account. The user can then send and receive at that address via the Email module or any IMAP client.

Mailbox aliases

You can add aliases (e.g. hello@yourdomain.com forwarding to a user's primary mailbox) from the same Mailboxes page. Aliases receive but do not send - outbound email always uses the primary address.

Check logs first:

docker compose logs workapp --tail=50

Common causes:

• "address already in use :8080" - another process is using port 8080. Find it: sudo ss -tlnp | grep 8080 and stop it
• "MongoDB connection refused" - MongoDB container isn't ready yet. Wait 10 seconds and try again, or check: docker compose ps mongodb
• "invalid SESSION_STORE_KEY" - the key must be a valid base64 string. Regenerate: openssl rand -base64 32
• Container exits immediately - check for a missing required env variable. All required vars are listed in the env reference

If nginx fails to start with BIO_new_file() failed: Permission denied on the private key, it means nginx (running as www-data) can't read the Let's Encrypt private key (which is 600 root:root by default).

# Fix permissions
sudo chgrp www-data /etc/letsencrypt/archive/yourdomain.com/privkey1.pem
sudo chmod 640 /etc/letsencrypt/archive/yourdomain.com/privkey1.pem
sudo systemctl reload nginx

Add a renewal hook so this auto-applies on every cert renewal:

#!/bin/bash
chgrp www-data /etc/letsencrypt/archive/yourdomain.com/privkey1.pem
chmod 640 /etc/letsencrypt/archive/yourdomain.com/privkey1.pem
systemctl reload nginx

Check the received email's headers. Look for dkim=pass and spf=pass. If either fails:

• SPF fail: Your server's IP is not in the SPF record. Add: v=spf1 ip4:your-ip ~all
• DKIM fail: Check the DKIM TXT record in DNS matches what's in Admin → Email → DKIM. The selector is karyo.
• New IP reputation: Use Brevo relay for first 2–4 weeks (see SMTP relay guide)

Use mail-tester.com to get a deliverability score before going live.

Common Okta login issues:

• Redirect URI mismatch: OKTA_REDIRECT_URI in .env must exactly match the Redirect URI in your Okta app settings - including https:// and no trailing slash
• Issuer URL wrong: Should be in format https://dev-xxxxx.okta.com/oauth2/default - confirm in Okta dashboard under Security → API → Authorization Servers
• Session key changed: If you regenerated SESSION_STORE_KEY, all existing sessions are invalidated. Users need to log in again.
• For testing without Okta: Use dev login at /dev/login?as=your@email.com (only works when APP_ENV is not set to production)

MongoDB takes 5–15 seconds to become ready after a cold start. If the app starts before MongoDB, it will retry automatically. If it doesn't recover:

# Check MongoDB is healthy
docker compose ps mongodb
docker compose logs mongodb --tail=20

# Restart app after MongoDB is confirmed healthy
docker compose restart workapp

If you see Authentication failed: the MongoDB password in MONGO_URI doesn't match what MongoDB was initialised with. Never change MONGO_APP_PASSWORD after initial setup without also resetting it inside MongoDB.

Oracle reclaims Always-Free instances that are idle for 7+ days (CPU + Network + Memory all below 20%). If your WorkSpace is in early pilot with low traffic, you can prevent this with a lightweight keep-alive:

# Ping health endpoint every 4 hours to maintain network activity
0 */4 * * * curl -sf http://localhost:8080/health > /dev/null

Once you have real users, natural traffic eliminates this risk entirely.