Documentation — Dockbox

Overview

Dockbox is a self-hosted AI infrastructure platform. It gives your organization a multi-channel AI assistant accessible through Slack, Telegram, WhatsApp, email, voice, and a web dashboard — all running on your own server with your data staying private.

The platform runs on port 3200 by default. After deployment, you'll access the admin dashboard to create users, configure integrations, and manage your AI groups.

Quick start: After deploying, visit your-server:3200 in a browser. You'll be prompted to set an admin password on first launch.

Admin Dashboard

The admin dashboard is your control center for managing users, groups, integrations, and system settings.

Logging In

Navigate to your Dockbox instance and click Log In. Select the admin account and enter the password you set during initial setup.

Managing Users

From the admin dashboard, you can create, edit, and remove user accounts. Each user gets their own isolated session with the AI assistant.

Create a user — Click the + button, choose a display name, and optionally set a password for login.
API keys — Each user can have their own API keys for the AI providers they use. Keys are stored encrypted on your server.
Quotas — Set per-user token quotas to manage usage across your organization.

Managing Groups

Groups are isolated AI conversation environments. Each group can have its own model, system prompt, and connected integrations. Think of them as separate "rooms" for different purposes (e.g., a general assistant, a code helper, a customer support bot).

System Settings

Configure global settings including:

Default AI model and provider
Ollama (local model) connection
Backup schedules
Custom API endpoints

User Dashboard

The user dashboard is the daily interface for interacting with the AI assistant.

Chat Interface

Select a group from the sidebar and start chatting. Messages support markdown, code blocks, and file attachments. You can also use voice input for hands-free interaction.

File Manager

Upload, organize, and share files within your groups. Files are versioned automatically — you can view history and revert to previous versions at any time.

Calendar

A built-in shared calendar for your organization. Events can be created through the dashboard or by the AI assistant. Supports ICS export for syncing with external calendar apps, and two-way sync with Google Calendar and Microsoft Outlook via OAuth.

Work Tasks

Create and track tasks assigned to users. Tasks support priorities, due dates, and project grouping. The AI assistant can also create tasks on your behalf during conversations.

PII Vault

The PII vault automatically detects and scrubs personal information from files. Any detected PII is stored in an encrypted vault so it can be referenced when needed but isn't exposed in plain text.

Slack Integration

Connect Dockbox to your Slack workspace so team members can interact with the AI assistant directly from Slack channels and DMs.

Create a Slack App

Go to api.slack.com/apps and click Create New App. Choose "From scratch" and give it a name (e.g., "Dockbox AI"). Select your workspace.

Configure Bot Permissions

Under OAuth & Permissions, add these Bot Token Scopes:

chat:write — Send messages
app_mentions:read — Read @mentions
im:history — Read DM history
im:read — Read DM metadata
im:write — Open DMs
channels:history — Read channel messages (if using in channels)

Enable Event Subscriptions

Under Event Subscriptions, set the Request URL to:

https://your-dockbox-domain/api/slack/events

Subscribe to bot events: app_mention, message.im.

Install to Workspace

Click Install to Workspace and authorize. Copy the Bot User OAuth Token (starts with xoxb-) and the Signing Secret from Basic Information.

Add to Dockbox

In your Dockbox admin dashboard, go to the group you want to connect and add the Slack integration. Paste the bot token and signing secret. Choose which Slack channels or DMs should route to this group.

Telegram Integration

Connect a Telegram bot to Dockbox so users can message the AI assistant through Telegram.

Create a Telegram Bot

Open Telegram and message @BotFather. Send /newbot, follow the prompts to name it, and copy the API token it gives you.

Configure the Webhook

Dockbox sets up the webhook automatically. In the admin dashboard, go to the target group, add the Telegram integration, and paste your bot token. Dockbox will register the webhook URL with Telegram.

Set Bot Commands (Optional)

Back in BotFather, send /setcommands and add any custom commands you'd like (e.g., clear - Reset conversation).

Tip: Telegram bots require HTTPS. Make sure your Dockbox instance has a valid SSL certificate (via a reverse proxy like Caddy or nginx).

WhatsApp Integration

Dockbox supports WhatsApp through the WhatsApp Business API. Messages sent to your WhatsApp Business number are routed to the AI assistant.

Set Up WhatsApp Business API

You'll need a Meta Business account and a WhatsApp Business API setup (through Meta's Cloud API or a BSP). Obtain your Phone Number ID and Permanent Access Token.

Configure the Webhook

In the Meta Developer Portal, set the webhook URL to:

https://your-dockbox-domain/api/whatsapp/webhook

Subscribe to the messages webhook field.

Add to Dockbox

In the admin dashboard, add the WhatsApp integration to the target group. Enter your Phone Number ID and access token.

Email Integration

Connect email accounts (IMAP/SMTP) so the AI assistant can read and send emails on behalf of users.

Add an Email Account

In the admin dashboard, go to Email and click Add Account. Enter the IMAP and SMTP server details, credentials, and the email address.

Test the Connection

Click Test Connection to verify both incoming (IMAP) and outgoing (SMTP) work correctly.

Use in Chat

Users can ask the AI to check emails, draft replies, or send new messages. The AI accesses the configured accounts through the email API.

Calendar & Scheduling

Dockbox includes a shared calendar. Events can be synced with Google Calendar or Microsoft Outlook.

Google Calendar Sync

Connect Google Account

In the user dashboard, go to Calendar and click Connect Google Calendar. You'll be redirected to Google to authorize access. Dockbox requests calendar read/write permissions.

Select Calendars

After authorization, choose which Google calendars to sync. Events will appear in Dockbox and changes sync both ways.

ICS Export

Every user gets a personal ICS feed URL for subscribing in any calendar app. Find it under Calendar Settings in the user dashboard.

Voice Assistant

Dockbox supports voice input and output. You can send audio to the API and receive transcribed text and AI responses.

Using Voice in the Dashboard

Click the microphone icon in the chat input to record a voice message. Dockbox transcribes it locally and sends it as a text message to the AI.

Voice API

For building custom voice integrations (smart speakers, phone systems, etc.), send raw audio to the voice endpoint:

    POST
    /api/voice?jid=GROUP_JID&sender_name=USER
  
// Send raw audio as the request body
// Content-Type: audio/wav, audio/webm, audio/mp3, etc.
// Returns:
{
  "ok": true,
  "transcript": "What's on the calendar today?",
  "id": "msg_abc123"
}

API Authentication

Dockbox runs behind a Cloudflare Zero Trust tunnel. Every request to the API must pass through two layers of authentication:

Cloudflare Access — proves you're allowed to reach the server at all
Dockbox session — identifies which user or admin you are

Layer 1: Cloudflare Access

If you're accessing the API from a browser that you've already authenticated with (e.g. via Google SSO or a one-time email link), Cloudflare sets a CF_Authorization cookie automatically and you're good to go.

For programmatic access (scripts, bots, IoT devices, voice assistants), you need a Cloudflare Service Token. Include the token's client ID and secret as headers on every request:

    Cloudflare Service Token headers
  
CF-Access-Client-Id: your-client-id.access
CF-Access-Client-Secret: your-client-secret

Creating a Service Token

Go to Cloudflare Zero Trust dashboard → Access → Service Auth → Create Service Token.

Name it something descriptive (e.g. "Voice Assistant", "Home Automation"). Copy the Client ID and Client Secret — the secret is only shown once.

Go to Access → Applications, find your Dockbox application, and add a policy that allows your service token. Set the policy action to Service Auth and select the token you just created.

Keep your service token secret. Anyone with the client ID and secret can bypass Cloudflare Access and reach your Dockbox API directly. Rotate tokens if they're ever exposed.

Layer 2: Dockbox Session

Once past Cloudflare, you still need a Dockbox user session. Log in as a user and include the session token with every request:

Header: x-user-session: SESSION_TOKEN
Query param: ?usersession=SESSION_TOKEN

    POST
    /api/users/:id/login
  
// Request
{ "password": "user-password" }

// Response
{ "session": "sess_abc123..." }

Full Example (programmatic access)

    curl — send a message via the API
  
# Both Cloudflare + Dockbox headers required
curl -X POST https://your-dockbox-domain/api/messages \
  -H "CF-Access-Client-Id: your-client-id.access" \
  -H "CF-Access-Client-Secret: your-client-secret" \
  -H "x-user-session: sess_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"text": "What meetings do I have today?", "jid": "general"}'

Admin Authentication (admin endpoints only)

A separate admin session is required only for endpoints under /api/admin/* and for user management operations like creating or deleting users. Use x-admin-session instead of x-user-session.

Header: x-admin-session: SESSION_TOKEN
Query param: ?adminsession=SESSION_TOKEN

Public Endpoints (No Auth Required)

These endpoints still require Cloudflare Access but do not need a Dockbox session:

GET /api/health
GET /api/login-info
GET /api/oauth/start
GET /api/oauth/callback
GET /api/calendar/export.ics?token=... (per-user token)
GET /api/users/:id (for login page)

Getting started: For browser-based access, just log in normally — Cloudflare handles the rest. For scripts and automations, create a Cloudflare service token, then log in with POST /api/users/:id/login and include both sets of headers on every request.

Auth & Sessions

Method	Endpoint	Description
POST	`/api/admin/login`	Admin login. Body: `{ password }` → `{ session }`
POST	`/api/admin/verify`	Verify admin session. Body: `{ session }` → `{ valid }`
POST	`/api/admin/logout`	Admin logout. Body: `{ session }`
POST	`/api/admin/change-password`	Change admin password. Requires admin session.
POST	`/api/users/:id/login`	User login. Body: `{ password }` → `{ session }`
POST	`/api/users/:id/set-password`	Set user password. Body: `{ session, password }`
POST	`/api/users/:id/verify-session`	Verify user session. Returns `{ valid, user }`
POST	`/api/users/:id/logout`	User logout. Body: `{ session }`

Example: Admin Login

    POST
    /api/admin/login
  
// Request
{ "password": "your-admin-password" }

// Response
{ "session": "sess_abc123..." }

Messaging

The messaging API is the core of the AI assistant. Send text or audio and receive AI responses.

Method	Endpoint	Description
GET	`/api/messages?jid=&since=&limit=50`	Fetch message history for a group.
POST	`/api/messages`	Send a message and trigger the AI agent. Body: `{ text, jid?, sender_name?, model?, is_bot_message?, verbose?, thinking? }`
POST	`/api/voice?jid=&sender_name=`	Send raw audio. Transcribes locally, sends as message. Returns `{ ok, transcript, id }`
POST	`/api/chat/stop`	Stop a running AI response.

Example: Send a Message

    POST
    /api/messages
  
// Headers: x-user-session: YOUR_SESSION

// Request
{
  "text": "What meetings do I have today?",
  "jid": "group-folder-name",
  "sender_name": "Alice"
}

// The AI response streams via SSE (see Notifications)

SSE / Notifications

Real-time streaming of AI responses and push notifications via Server-Sent Events.

Method	Endpoint	Description
GET	`/api/users/:id/notifications`	SSE stream. Sends `{"type":"connected"}` on connect, then push events. Keepalive every 30s.
GET	`/api/users/:id/notifications/poll?since=`	Polling fallback. Returns `{ notifications: [...] }`
GET	`/api/notifications?since=`	Bot message notifications (admin only).

Voice Assistant Hot Path

For building a voice assistant, the typical flow is:

POST /api/users/:id/login → get a session token

POST /api/messages with { text, jid } → send the command

GET /api/users/:id/notifications (SSE) → stream the response back

Or use POST /api/voice to skip local STT and let Dockbox transcribe

Groups & Containers

Method	Endpoint	Description
GET	`/api/groups`	List all groups.
POST	`/api/groups`	Create a group. Body: `{ name, model?, system_prompt? }`
POST	`/api/groups/:folder/clear-session`	Clear the conversation context for a group.
GET	`/api/status`	Full system status (groups, containers, metrics).
POST	`/api/containers/kill`	Kill a running container.
POST	`/api/server/restart`	Restart the server.
POST	`/api/stress-test`	Trigger a stress test.

Files

Method	Endpoint	Description
POST	`/api/files/upload`	Multipart file upload.
POST	`/api/files/mkdir`	Create a directory.
POST	`/api/files/rename`	Rename a file or directory.
POST	`/api/files/copy`	Copy a file or directory.
POST	`/api/files/revert`	Revert a file to a previous version.
GET	`/api/files/download?path=`	Download a file.
GET	`/api/files/serve?path=&usersession=`	Serve a file (for embedding in iframes).
GET	`/api/files/read?path=`	Read file contents.
GET	`/api/files/history?path=`	File version history.
GET	`/api/files/version?path=&hash=`	Get a specific file version.

Users

Method	Endpoint	Description
GET	`/api/users`	List all users.
GET	`/api/users/check-username?name=`	Check name availability.
POST	`/api/users`	Create a user.
GET	`/api/users/:id`	Get user details.
PUT	`/api/users/:id`	Update a user.
DELETE	`/api/users/:id`	Delete a user.
GET / PUT	`/api/users/:id/heartbeat`	Read/write HEARTBEAT.md.
PATCH	`/api/users/:id/trigger`	Toggle trigger mode. Body: `{ jid, requiresTrigger }`

API Keys & Usage

Method	Endpoint	Description
GET	`/api/users/:id/api-keys`	List keys (masked).
POST	`/api/users/:id/api-keys`	Add an API key.
PUT	`/api/users/:id/api-keys/:keyId`	Update key label or active status.
DELETE	`/api/users/:id/api-keys/:keyId`	Remove a key.
GET	`/api/users/:id/api-usage/summary`	Aggregated usage by model + daily breakdown.
GET	`/api/users/:id/api-usage?days=30`	Usage stats for a given period.
GET / PUT	`/api/users/:id/api-quota`	View or update user quota.

Calendar

Method	Endpoint	Description
GET	`/api/calendar/events?start=&end=&user=`	List events in a date range.
POST	`/api/calendar/events`	Create event. Body: `{ title, start_time, end_time?, description?, location?, all_day?, recurrence?, color?, assigned_to?, created_by? }`
PUT	`/api/calendar/events/:id`	Update an event.
DELETE	`/api/calendar/events/:id`	Delete an event.
GET	`/api/calendar/export.ics?start=&end=&user=&token=`	ICS export (public with token).
GET	`/api/users/:id/calendar/export.ics`	Per-user ICS export.
POST	`/api/calendar/import`	Import events from ICS text (raw body).
GET / POST	`/api/users/:id/calendar-token`	Manage per-user calendar token.

Work Tasks

Method	Endpoint	Description
GET	`/api/work-tasks`	List all work tasks.
POST	`/api/work-tasks`	Create a work task. Body: `{ title, created_by, description?, priority?, assigned_to?, due_date?, project_id? }`

Scheduled Automations

Method	Endpoint	Description
GET	`/api/tasks`	List all scheduled tasks.
POST	`/api/tasks`	Create a scheduled task. Body: `{ group_folder, prompt, schedule_type: "cron", ... }`
PATCH	`/api/tasks/:id`	Update task status. Body: `{ status: "active" \| "paused" }`
DELETE	`/api/tasks/:id`	Delete a scheduled task.

PII Vault

Method	Endpoint	Description
GET	`/api/vault`	List all vault entries.
POST	`/api/vault/scrub`	Scrub files for PII. Body: `{ paths: [...], useOllama? }`
GET	`/api/vault/dictionary`	Get custom PII dictionary.
POST	`/api/vault/dictionary`	Update PII dictionary.
DELETE	`/api/vault/:id`	Delete a vault entry.

Email

Method	Endpoint	Description
GET	`/api/email/accounts`	List email accounts.
POST	`/api/email/accounts`	Create an email account.
PUT	`/api/email/accounts/:id`	Update an email account.
DELETE	`/api/email/accounts/:id`	Delete an email account.
GET	`/api/email/inbox?accountId=&folder=&limit=&offset=`	Fetch emails from inbox.
GET	`/api/email/message?accountId=&emailId=`	Fetch a single email.
POST	`/api/email/send`	Send an email.
POST	`/api/email/test`	Test email connection.
GET	`/api/email/drafts?accountId=`	List drafts.
DELETE	`/api/email/drafts/:id`	Delete a draft.

OAuth

Method	Endpoint	Description
GET	`/api/oauth/start?provider=google\|microsoft&userId=&...`	Start OAuth flow. Optional: `read_only`, `client_id`, `client_secret`.
GET	`/api/oauth/callback?code=&state=`	OAuth redirect callback.
GET	`/api/oauth/accounts?userId=`	List connected OAuth accounts.
DELETE	`/api/oauth/accounts/:id`	Revoke an OAuth account.
PATCH	`/api/oauth/accounts/:id`	Update OAuth account settings.
POST	`/api/oauth/accounts/:id/sync-calendar`	Push local events to the provider.
GET	`/api/oauth/accounts/:id/calendars`	List the provider's available calendars.

Webdev / FTP

Method	Endpoint	Description
GET	`/api/webdev/ftp?folder=`	Get FTP config for a group.
POST	`/api/webdev/ftp`	Save FTP config.
POST	`/api/webdev/test-ftp`	Test FTP connection.
POST	`/api/webdev/ftp-browse`	Browse remote FTP directories.
POST	`/api/webdev/seed`	Snapshot current files (baseline for push).
POST	`/api/webdev/push`	Upload changed files via FTP.

Ollama (Local LLM)

Method	Endpoint	Description
GET	`/api/ollama/test`	Test Ollama connection, list available models.
GET / POST	`/api/ollama/model-names`	Get or set friendly model display names.
GET / POST	`/api/ollama/thinking-support`	Get or set per-model thinking support flags.
POST	`/api/ollama/toggle`	Enable or disable Ollama. Body: `{ enabled }`
GET / POST	`/api/automation/model`	Get or set the automation model.

Search & Activity

Method	Endpoint	Description
GET	`/api/search?q=`	Search across messages, files, and vault.
GET	`/api/activity?limit=20`	Recent activity feed.
GET	`/api/skills`	List installed integrations.

Backup

Method	Endpoint	Description
GET	`/api/backup`	List backups and config.
GET	`/api/backup/config`	Get backup configuration.
POST	`/api/backup/config`	Save backup configuration.
POST	`/api/backup/full`	Create a full backup.
POST	`/api/backup/incremental`	Create an incremental backup.
POST	`/api/backup/restore/:id`	Restore from a backup.
GET	`/api/backup/download/:id`	Download backup archive.
DELETE	`/api/backup/:id`	Delete a backup.

Admin

Method	Endpoint	Description
GET	`/api/admin/api-keys`	List all user API keys.
GET	`/api/admin/api-usage?days=30`	Global API usage stats.
PUT	`/api/admin/api-quota`	Set user quota. Body: `{ user_id, usage_quota_tokens?, usage_reset_day?, quota_exempt? }`
POST	`/api/admin/api-quota/reset`	Reset a user's quota. Body: `{ user_id }`
GET	`/api/admin/custom-apis`	List custom API endpoints.
POST	`/api/admin/custom-apis`	Create a custom API. Body: `{ name, url, method?, headers?, body?, description? }`
PATCH	`/api/admin/custom-apis/:id`	Update a custom API.
DELETE	`/api/admin/custom-apis/:id`	Delete a custom API.
POST	`/api/admin/custom-apis/:id/execute`	Execute a custom API.
GET / POST	`/api/settings`	Read or write server settings.

Session Links

Method	Endpoint	Description
GET	`/api/session-links`	List linked sessions.
POST	`/api/session-links`	Create a session link.

Static / Preview

Path	Description
`/preview/:groupFolder/...`	Serves group files with correct relative paths (for iframe previews).

Everything you need toget started with Dockbox

Overview

Admin Dashboard

Logging In

Managing Users

Managing Groups

System Settings

User Dashboard

Chat Interface

File Manager

Calendar

Work Tasks

PII Vault

Slack Integration

Create a Slack App

Configure Bot Permissions

Enable Event Subscriptions

Install to Workspace

Add to Dockbox

Telegram Integration

Create a Telegram Bot

Configure the Webhook

Set Bot Commands (Optional)

WhatsApp Integration

Set Up WhatsApp Business API

Configure the Webhook

Add to Dockbox

Email Integration

Add an Email Account

Test the Connection

Use in Chat

Calendar & Scheduling

Google Calendar Sync

Connect Google Account

Select Calendars

ICS Export

Voice Assistant

Using Voice in the Dashboard

Voice API

API Authentication

Layer 1: Cloudflare Access

Creating a Service Token

Layer 2: Dockbox Session

Full Example (programmatic access)

Admin Authentication (admin endpoints only)

Public Endpoints (No Auth Required)

Auth & Sessions

Example: Admin Login

Messaging

Example: Send a Message

SSE / Notifications

Voice Assistant Hot Path

Groups & Containers

Files

Users

API Keys & Usage

Calendar

Work Tasks

Scheduled Automations

PII Vault

Email

OAuth

Webdev / FTP

Ollama (Local LLM)

Search & Activity

Backup

Admin

Session Links

Static / Preview

Everything you need to
get started with Dockbox