BoxedAI

Appearance

Core Concepts ​

Understanding how BoxedAI organizes data is key to managing your instance effectively.

Deployment Models ​

BoxedAI offers two primary deployment models to suit different privacy and infrastructure needs:

  • BoxedAI Self Hosted: You run the entire platform on your own infrastructure (on-premise servers or private cloud). You have complete control over the database, storage, and network access.
  • BoxedAI Cloud: A managed service hosted by BoxedAI. While secure, this relies on our infrastructure. Note: Most of this documentation focuses on the Self Hosted version.

Inference Modes ​

The "Brain" of BoxedAI can run in two different modes. This distinction is critical for understanding data privacy.

  • OpenRouter / Cloud Inferencing: The system connects to external API providers like OpenAI, Anthropic, or Google via OpenRouter.
    • Pros: Access to the smartest models (GPT-4, Claude 3.5 Sonnet) without needing expensive hardware.
    • Cons: Data (prompt content) is sent over the internet to the provider for processing.
  • Local Inferencing: The AI model runs directly on your server's hardware (GPU/CPU).
    • Pros: 100% Private. No data ever leaves your network.
    • Cons: Requires powerful hardware (high-end consumer GPU or enterprise accelerator).
    • Availability: Exclusive to BoxedAI Self Hosted.

Organizations ​

The Organization is the top-level container for all data.

  • In a standard deployment, there is usually one Organization (Single-Tenant Mode).
  • All users, chats, files, and configurations belong to an Organization.
  • Encryption is enabled or disabled at the Organization level (zero-knowledge, client-side).

Users & Groups ​

  • Users: Individuals with access to the platform. Users log in with an email and password.
  • Superuser: A special user with full administrative privileges across the entire system.
  • Groups: Collections of users. Currently used for logical grouping, but will support fine-grained permission policies in future updates.

Capabilities ​

Capabilities are toggleable AI tools — like browser extensions for the LLM. Each capability gives the AI access to a specific function (e.g., Calculator, File Search, Spreadsheet Generation) that it can invoke during a conversation via function calling.

  • System-Defined: Capabilities are defined in Go code and registered at startup.
  • Per-Org Toggle: Admins enable or disable capabilities for their organization. When disabled, the tool is simply not sent to the LLM.
  • Extensible: New capabilities can be added by implementing the Capability interface and registering them.

Chats ​

A Chat is a conversation thread between a user and the AI.

  • Ownership: Chats are private to the user who created them (unless shared).
  • History: The system retains message history to provide context for follow-up questions.
  • Context Window: The backend automatically manages the "context window" (how much memory the AI has) to ensure conversations stay within the model's limits.
  • Tool Calls: When the AI uses a capability, the tool call and its result are stored with the message and displayed as collapsible cards in the UI.

Objects (Files) ​

Objects are files uploaded to the system (PDFs, Text files, Spreadsheets).

  • Storage: Files are stored as binary data directly in PostgreSQL (no filesystem dependencies). This simplifies backup and deployment.
  • Async Processing: When you upload a file, it enters an asynchronous pipeline — the server stores the binary, then a background goroutine handles encryption, text analysis, and indexing.
  • Scoping: Objects can be permanent (visible across the organization) or temporary (scoped to a specific chat). Temporary files are attached via drag-and-drop in a chat and only visible within that conversation.
  • Search: Full-text search is powered by Bleve, serialized into the database. When encryption is enabled, the search index is also encrypted.

Analyzers ​

Analyzers extract text content from uploaded files, enabling full-text search and RAG.

  • System-Defined: Like capabilities, analyzers are defined in Go code and registered at startup.
  • Per-Org Toggle: Admins enable or disable analyzers for their organization.
  • Built-in Analyzers:
    • text_plain — Extracts text from plain text files (.txt, .md, .csv, .json, etc.)
    • pdf_extract — Extracts text content from PDF documents
    • docx_extract — Extracts text from Microsoft Word (.docx) files by parsing the document XML

Real-Time Events ​

BoxedAI uses WebSocket connections for real-time event delivery.

  • Auto-Reconnect: The frontend maintains a persistent WebSocket connection with automatic reconnection and exponential backoff.
  • Event Types: Events like file_analysis_complete notify the UI when background processing finishes, so file status updates appear without manual refresh.

Sessions ​

BoxedAI uses secure, server-side sessions.

  • Token: When you log in, you receive a session token.
  • Expiration: Sessions typically expire after 7 days of inactivity.
  • Security: You can view and revoke active sessions from your profile settings.