Current architecture: This post describes the product thesis and early architecture. The current service map, auth model, subagent model, and receipt system are documented in the Architecture reference, Authentication reference, and Audit Trail reference.

The sovereign AI thesis​

"Sovereign AI" is not a marketing term. It describes a concrete constraint: inference, data storage, and agent orchestration can run on infrastructure you own and control. A strict deployment can keep model calls local; the default developer path can also route through external providers such as OpenRouter when the operator configures that route.

This matters for three reasons:

1. Regulatory compliance. HIPAA, PCI-DSS, ITAR, and similar frameworks impose strict controls on where data can be processed. Sending patient records or classified documents to an external LLM endpoint is a non-starter.

2. Latency and availability. If your AI workflows depend on an external API, you inherit that API's outage schedule. A self-hosted inference stack on local GPUs gives you low-latency inference with no dependency on someone else's uptime.

3. Cost at scale. API pricing works fine for prototyping. At thousands of requests per hour, running your own vLLM instance on commodity hardware is dramatically cheaper.

The design principle is "local-first, not local-only." The platform can optionally route requests to external providers like OpenRouter, but only when an administrator explicitly enables it and only through a policy-gated external gateway that logs every outbound call.

Architecture overview​

AI-in-a-Box is a microservices platform. Each subsystem is an independent service with its own API, communicating via REST and async events. Here is the high-level layout:

User -> Frontend (React/Vite) -> API Gateway (Go)
  -> Agent Runtime (Python)
    -> Guardrail Service (input check)
    -> Memory Service (context retrieval)
    -> Inference Router -> vLLM / External Gateway (OpenRouter)
    -> Guardrail Service (output check)
    -> Memory Service (store new memories)
  -> API Gateway -> Frontend (streamed response via SSE)

The key services:

• API Gateway (Go): OIDC authentication, rate limiting, SSE streaming, audit logging. Every request gets a correlation ID and tenant extraction from JWT claims.

• Agent Runtime (Python, OpenAI Agents SDK): The brain. Handles chat, typed tool dispatch, SKILL.md loading, and Delegate-based subagent dispatch.

• Inference Router (Go): A lightweight proxy between the agent runtime and inference backends. Maintains a model registry mapping public model IDs such as google/gemma-4-E4B-it or openai/gpt-5.4 to backends such as vllm and openrouter, health-checks backends, and exposes a unified OpenAI-compatible API.

• Guardrail Service (Python): Constitutional AI layer with pluggable backends. Input guardrails handle jailbreak detection, PII redaction, and topic control. Output guardrails enforce content policy and flag hallucinations. Policies are scoped hierarchically: global, then tenant, then per-agent. Lower levels can only restrict, never relax.

• Memory Service (Python): Typed memory powered by Mem0 and Qdrant. Four memory types (user, feedback, project, reference) are stored as vector embeddings in per-tenant Qdrant collections. The message buffer lives in Redis as a sliding window. Memories are automatically extracted from conversations and retrievable via semantic search.

• Code Sandbox: Per-session Docker containers with hardened security (all capabilities dropped, PID limits, no network, non-root user). Optional GPU passthrough for ML workloads.

What makes it different​

There are other self-hosted AI tools. Dify provides visual workflow building. Open WebUI gives you a chat interface. LocalAI wraps inference. AI-in-a-Box is not trying to replace any one of these. It integrates with Dify for visual workflows and runs its own inference via vLLM. The difference is in what it adds on top:

Multi-tenant isolation from day one. Every database table has a tenant_id column. Vector collections are per-tenant. Memory scopes are per-tenant. The gateway extracts tenant identity from OIDC tokens. This is not an afterthought bolted onto a single-user system.

Enterprise compliance built in. The audit service produces hash-chained, HMAC-signed immutable logs suitable for SOC2, HIPAA, and PCI-DSS audits. Every agent action, every guardrail decision, every external API call is logged with a tamper-evident chain.

Agent orchestration, not just chat. The agent runtime supports adaptive single-agent conversations, Delegate-based typed subagents for focused independent work, and visual workflows via Dify. Agents have typed memories and load skills on demand using the SKILL.md format.

Inference flexibility. The inference router supports vLLM for local GPU serving and policy-gated external providers via OpenRouter. Models are pre-staged from MinIO or local storage, supporting fully air-gapped deployments with no need to download from HuggingFace at runtime.

Deployment model​

The platform deploys two ways:

Docker Compose for single-node or small team setups. One docker-compose.yml brings up all services plus infrastructure (PostgreSQL, Redis, Qdrant, MinIO, Keycloak, Langfuse). Works on a single machine with one or more GPUs.

Helm Charts for Kubernetes. Same container images, Kubernetes-native: Deployments with HPAs, GPU scheduling via NVIDIA device plugin, persistent volumes, Ingress, ConfigMaps, and optional service mesh for mTLS.

The smallest useful deployment is a single machine with an RTX 3070 or better, running a 2B-7B parameter model via vLLM. The largest is a multi-node Kubernetes cluster with dedicated vLLM instances per tenant.

What comes next​

The platform is functional today for chat, multi-agent workflows, RAG, code execution, web search, and memory. The next priorities are:

• Model management UI for uploading and registering models
• Skill marketplace for sharing SKILL.md packages across tenants
• Voice and multimodal input support
• Automatic memory summarization and compression for long-running agents

The code is open source under MIT. If you are building sovereign AI infrastructure, we would like to hear what you need.

We built this into AI-in-a-Box's agent runtime using the OpenAI Agents SDK.

Current runtime model: This post is historical. The current implementation uses a main agent with a Delegate tool and subagent definitions in deploy/config/subagents/*.md; the old YAML handoff team model has been removed. Use the Agents reference and Multi-Agent tutorial for current behavior.

The current Delegate tool​

The current mechanism is the Delegate tool. The main agent calls it when a task benefits from dedicated instructions rather than handling everything inline. The tool takes a short description, a configured subagent_type, and the prompt the child agent should execute.

The implementation has changed since the early prototype below. Today the tool shape is:

Delegate(description="short label", subagent_type="researcher", prompt="<task brief>")

The early prototype used a delegate_task helper that built subagents from tool-category strings:

def create_delegate_tool(config, tenant_id, user_id, memory_client):
    """Create a tool that spawns sub-agents with custom system prompts."""
    from agents import Runner

    # Pre-build tool pools so sub-agents can select what they need
    sandbox_tools = create_sandbox_tools(config.sandbox_url, tenant_id, ...)
    tool_pools = {
        "memory": create_memory_tools(memory_client, tenant_id, user_id),
        "search": create_search_tools(config.search_url),
        "code": sandbox_tools,
        "knowledge": create_knowledge_tools(config.knowledge_url, tenant_id),
    }

    @function_tool
    async def delegate_task(task: str, approach: str, tools_needed: str) -> str:
        """Delegate a complex task to a focused sub-agent."""
        requested = [t.strip().lower() for t in tools_needed.split(",")]
        sub_tools = []
        for category in requested:
            if category in tool_pools:
                sub_tools.extend(tool_pools[category])

        sub_agent = Agent(
            name="sub-agent",
            instructions=approach,
            model=model,
            tools=sub_tools,
        )

        result = await Runner.run(sub_agent, task)
        return result.final_output or "Sub-agent completed but produced no output."

    return [delegate_task]

The current implementation gets its tool allowlists from deploy/config/subagents/*.md, not from free-form tool-category strings. A research subagent can be configured with web and knowledge tools, while a code subagent can be configured with sandbox tools. This limits the subagent's blast radius and keeps its tool list focused.

The main agent's system prompt includes guidance on when to use delegation:

Use for: deep research requiring multiple searches and synthesis, complex data analysis pipelines, multi-file code projects, document drafting that needs iteration. Do NOT use for: simple questions, single tool calls, quick lookups, or tasks you can handle in one or two steps.

SKILL.md: on-demand skill loading​

The second pattern we borrowed from Claude Code is progressive skill loading. Claude Code uses SKILL.md files with YAML frontmatter to define skills that can be loaded on demand. We adopted the same format, compatible with the agentskills.io specification:

---
name: summarizer
description: >
  Use when the user asks to "summarize", "give me a tldr",
  or "condense this document".
version: 1.0.0
---

# Document Summarizer

You are a summarization specialist...

The SkillLoader class scans a skills directory, parsing each SKILL.md file into a Skill dataclass:

@dataclass
class Skill:
    name: str
    description: str
    instructions: str
    version: str | None = None

    def to_system_prompt(self) -> str:
        return f"## Skill: {self.name}\n\n{self.instructions}"

The critical optimization: at agent creation time, only skill names and one-line descriptions are injected into the system prompt. The full instructions stay unloaded until the agent explicitly calls load_skill:

if skills:
    skill_index = "\n".join(f"- **{s.name}**: {s.description}" for s in skills)
    instructions += (
        f"\n\n# Available skills\n\n"
        f"Use load_skill to activate a skill before starting a task it covers.\n"
        f"{skill_index}"
    )

    skill_map = {s.name: s for s in skills}

    @function_tool
    async def load_skill(skill_name: str) -> str:
        """Load a skill's full instructions."""
        skill = skill_map.get(skill_name)
        if not skill:
            return f"Skill '{skill_name}' not found."
        return skill.to_system_prompt()

This saves context window space. An agent with 20 available skills only pays for 20 one-line descriptions in its system prompt, not 20 full instruction sets. When the agent recognizes a task that matches a skill, it loads just that skill's instructions on demand.

Skill precedence and import (planned)​

Skills will be layered with clear precedence: platform built-in skills as the base, tenant-custom skills extending or overriding them, and agent-specific skills taking highest priority. Currently, skills are loaded from the local filesystem. Database-backed skill registration and GitHub import are planned features that have not yet been implemented.

Current subagent model​

The old hub-and-spoke model with an orchestrator and YAML handoffs was replaced by an adaptive main agent. The main agent receives the conversation, decides whether the work should stay inline or be delegated, and calls Delegate only for independent work that benefits from a focused context.

Subagent types are defined as Markdown files with YAML frontmatter in deploy/config/subagents/. The main agent sees the available types and writes the task brief itself. Subagents do not recursively spawn more subagents.

Lessons learned​

Building these patterns taught us a few things:

Sub-agent isolation matters. Early versions gave sub-agents all tools. This led to confused sub-agents trying to use tools they did not need, wasting tokens on irrelevant tool descriptions. Curated tool pools solved this.

Skill descriptions need to be trigger-oriented. A description like "summarization tool" does not help the agent decide when to load the skill. A description like "Use when the user asks to summarize, give me a tldr, or condense this document" gives the agent clear matching criteria.

The OpenAI Agents SDK's Runner.run is synchronous from the caller's perspective. The parent agent blocks while the sub-agent executes. For long-running tasks, this means the user sees no streaming output until the sub-agent finishes. We are exploring ways to stream sub-agent progress back to the parent.

Current reference: This post explains the design intent behind sandbox isolation. The current API and deployment knobs are documented in the Code Sandbox reference and Run Code tutorial.

We built a per-session Docker sandbox system that gives each user session its own isolated container.

Why subprocess execution fails at multi-tenant​

The simplest code execution approach is subprocess.run() on the host. Many AI tools start here. The problems show up quickly:

• No isolation. One tenant's code can read another tenant's files, environment variables, and process memory.
• Resource exhaustion. A fork bomb or memory leak in one session takes down the entire host.
• Privilege escalation. If the host process runs as root (common in Docker-in-Docker setups), executed code inherits those privileges.
• No cleanup. Files, processes, and network connections persist between sessions.

You could sandbox with something like nsjail or gVisor, but we wanted per-session state persistence (files created in one code execution are available in the next) and the ability to pass through GPUs for ML workloads. Docker containers gave us both.

The container manager​

The ContainerManager class manages the lifecycle of sandbox containers. Each tenant+session pair gets its own container with its own Docker volume for workspace persistence:

class ContainerManager:
    def __init__(self, worker_image, idle_timeout=900, mem_limit="512m",
                 cpu_quota=100000, enable_gpu=False, max_concurrent_sessions=50):
        self.client = docker.from_env()
        self.sessions: dict[str, SandboxSession] = {}

When a code execution request arrives, get_or_create either returns an existing running container or creates a new one:

def get_or_create(self, tenant_id, session_id) -> SandboxSession:
    key = f"{tenant_id}:{session_id}"
    if key in self.sessions:
        session = self.sessions[key]
        session.container.reload()
        if session.container.status == "running":
            session.touch()
            return session

    # Reject if at capacity
    if len(self.sessions) >= self.max_concurrent_sessions:
        raise RuntimeError("Maximum concurrent sessions reached.")

    # Create volume and container...

The capacity limit prevents resource exhaustion at the platform level. When you hit the limit, new sessions are rejected with a clear error rather than silently degrading the host.

Container hardening​

Every sandbox container is created with aggressive security constraints:

kwargs = dict(
    image=self.worker_image,
    command="sleep infinity",
    user="1000:1000",                   # Non-root
    mem_limit=self.mem_limit,
    memswap_limit=self.mem_limit,        # No swap
    cpu_period=100000,
    cpu_quota=self.cpu_quota,
    pids_limit=256,                      # Prevent fork bombs
    network_disabled=True,               # No network access
    security_opt=["no-new-privileges:true"],
    cap_drop=["ALL"],                    # Drop ALL Linux capabilities
    cap_add=["CHOWN", "SETUID", "SETGID", "DAC_OVERRIDE"],
    tmpfs={"/tmp": "size=100M,noexec,nosuid,nodev"},
)

Breaking this down:

• user="1000:1000": The container runs as a non-root user. Even if code exploits a vulnerability in the container runtime, it starts from an unprivileged position.

• cap_drop=["ALL"]: Every Linux capability is dropped. The container cannot mount filesystems, change network configuration, load kernel modules, or use raw sockets. Only the four capabilities needed for basic file operations are added back.

• no-new-privileges:true: Prevents privilege escalation via setuid/setgid binaries. Even if a setuid binary exists in the container image, it cannot gain elevated privileges.

• pids_limit=256: Hard cap on the number of processes. A fork bomb hits this limit and stops rather than consuming all PIDs on the host.

• network_disabled=True: No network access at all. The sandbox cannot make outbound HTTP requests, connect to databases, or exfiltrate data. All external operations go through the agent runtime's tools (web_search, scrape_url) which are not available inside the sandbox.

• mem_limit with memswap_limit equal: Memory is capped with no swap. When the limit is hit, the OOM killer terminates the process rather than swapping to disk and slowing down the host.

• tmpfs with noexec: The /tmp directory is a size-limited tmpfs with no-exec. Code cannot write an executable to tmp and run it.

Path traversal prevention​

File read/write operations go through a validation function before touching the container:

@staticmethod
def _validate_path(path: str) -> str:
    if "\x00" in path:
        raise ValueError("Path contains null bytes")
    if path.startswith("/"):
        raise ValueError("Absolute paths are not allowed")
    if ".." in path.split("/") or ".." in path.split("\\"):
        raise ValueError("Path traversal ('..') is not allowed")
    normalized = posixpath.normpath(path)
    if normalized.startswith("..") or normalized.startswith("/"):
        raise ValueError("Path traversal is not allowed after normalization")
    return normalized

This prevents agents from reading /etc/passwd or writing to /usr/bin inside the container. All paths are relative to /workspace.

GPU passthrough​

For ML workloads (training small models, running inference on data, generating visualizations with GPU acceleration), the container manager supports GPU passthrough:

if self.enable_gpu:
    kwargs["device_requests"] = [
        docker.types.DeviceRequest(count=-1, capabilities=[["gpu"]])
    ]
    if self.enable_network:
        kwargs["network_disabled"] = False
    kwargs["cap_add"].append("SYS_PTRACE")  # CUDA profiling

GPU passthrough is separate from network access. GPU containers still keep networking disabled unless an operator explicitly enables networked sandbox sessions, and SYS_PTRACE is added only for CUDA profiling support. These containers are created only when an administrator explicitly enables GPU mode for a tenant.

Lifecycle management​

Containers are not permanent. A background task runs cleanup_stale() periodically, removing containers idle for longer than the configured timeout (default 15 minutes):

def cleanup_stale(self):
    now = time.time()
    stale_keys = [
        k for k, s in self.sessions.items()
        if now - s.last_used > self.idle_timeout
    ]
    for key in stale_keys:
        session = self.sessions.pop(key)
        session.container.stop(timeout=5)
        session.container.remove(force=True)
        self.client.volumes.get(session.volume_name).remove(force=True)

Both the container and its volume are destroyed. No state leaks between sessions after cleanup.

Why not E2B?​

E2B is a solid hosted sandbox service. We evaluated it and decided against it for two reasons:

1. Sovereignty. E2B runs containers on their infrastructure. For an air-gapped or on-premise deployment, that is a non-starter. The sandbox system needs to run on the same infrastructure as everything else.

2. GPU access. E2B does not currently support GPU passthrough. Our users need to run PyTorch and CUDA workloads inside sandboxes.

The tradeoff is that we maintain our own container management code. For a platform that already runs Docker Compose and Kubernetes, this is a reasonable cost. The ContainerManager class is around 250 lines and handles the full lifecycle.

Historical post: This post records an early hardening sprint. Some implementation details have changed since it was written. Use the current Security guide, Authentication reference, and Audit Trail reference as the source of truth.

Before shipping AI-in-a-Box to production, we ran a comprehensive security audit across all services. We found 27 vulnerabilities: 5 critical, 8 important, and 14 medium. This post captures the findings and the intended remediation work from that point in time.

The audit process​

We reviewed every service for the OWASP Top 10, then added AI-specific checks: prompt injection pathways, guardrail bypass scenarios, and agent tool abuse vectors. Each finding was categorized by severity and given a specific remediation.

Critical fixes​

These were stop-shipping issues that could lead to data exposure or remote code execution.

SSRF via URL parameters. The web scraping tool accepted arbitrary URLs from the agent. An attacker could craft a prompt that made the agent scrape http://169.254.169.254/latest/meta-data/ (the AWS metadata endpoint) or internal service URLs. Fix: we added URL validation with an allowlist of schemes (http/https only) and a denylist of internal IP ranges (RFC 1918, link-local, loopback). The Firecrawl integration now rejects requests to non-routable addresses.

Command injection in sandbox. The code sandbox passed user input directly into shell commands via string formatting. A carefully crafted filename like ; rm -rf / could escape the intended command. Fix: we replaced string interpolation with proper argument arrays and added input sanitization. The exec_run call now uses ["bash", "-c", command] with the command as a single argument, and file paths go through _validate_path before use.

Path traversal in file operations. The sandbox file read/write endpoints accepted paths like ../../etc/passwd without validation. Fix: we added the _validate_path static method that rejects absolute paths, null bytes, and .. components both before and after normalization. All file operations are confined to /workspace.

Guardrail fail-open. When the guardrail service was unreachable (network error, timeout, crash), the agent runtime silently continued without safety checks. Fix: we changed the guardrail client to fail-closed. If the guardrail service returns an error or times out, the request is blocked with an explicit error message. The system prompt is checked on every request, not just the first.

Audit chain race condition. The hash-chained audit log used a simple in-memory counter for chain sequencing. Under concurrent requests, two events could get the same sequence number, breaking the chain's integrity guarantee. Fix: we moved chain sequencing to a PostgreSQL sequence with a SELECT ... FOR UPDATE lock, ensuring strict ordering even under high concurrency.

Important fixes​

These were significant security gaps that required attention before production use.

httpx client reuse. Several services created a new httpx.AsyncClient on every request, leaking file descriptors under load. More importantly, this meant no connection pooling and no shared TLS session cache. Fix: we moved to a single shared client per service, created at startup and closed on shutdown, with proper connection limits and timeouts.

Session eviction. There was no mechanism to invalidate active sessions. If a user's access was revoked in Keycloak, their existing JWT continued to work until expiration. Fix: we added a token revocation check to the API gateway that validates tokens against Keycloak's introspection endpoint on a configurable interval.

Missing rate limiting on auth endpoints. The login and token refresh endpoints had no rate limiting, allowing brute-force attacks. Fix: we added per-IP rate limiting with exponential backoff on the gateway's auth routes.

Agent tool abuse. Early delegation prototypes made recursive subagent launches too easy. The current runtime exposes a bounded Delegate tool: configured subagents return one final result to the main agent and cannot dispatch further subagents.

Webhook URL validation. The Dify integration accepted arbitrary webhook URLs for workflow callbacks without validation. Fix: same URL validation as the SSRF fix, applied to all outbound HTTP calls from the platform.

Memory scope leakage. A bug in the memory service's query filtering allowed agents to read memories from other tenants when the tenant_id parameter was omitted from the query. Fix: we made tenant_id a required parameter at the API level, with the gateway injecting it from the JWT claims so agents cannot override it.

Langfuse credentials in logs. The inference router logged full request/response bodies for debugging, which included the Langfuse API keys in headers. Fix: we added a header sanitization pass that redacts Authorization, X-Api-Key, and similar headers before logging.

Unencrypted inter-service communication. Services communicated over plain HTTP within the Docker network. While the Docker network provides some isolation, this is insufficient for compliance requirements. Fix: we added mTLS support via the service mesh (Istio/Linkerd) in Kubernetes deployments, and documented TLS configuration for Docker Compose setups.

Medium fixes​

These improved defense-in-depth without addressing immediate exploits.

Docker healthchecks. None of the service containers had healthchecks defined. Docker Compose and Kubernetes had no way to detect a hung service. Fix: we added /health endpoints to every service and corresponding HEALTHCHECK directives in Dockerfiles.

Kubernetes security contexts. The Helm chart deployments ran containers as root by default. Fix: we added securityContext blocks to all pod specs: runAsNonRoot: true, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, and capabilities.drop: [ALL].

NetworkPolicy. The Kubernetes deployment had no NetworkPolicy resources, meaning any pod could communicate with any other pod. Fix: we added NetworkPolicy resources that restrict traffic to the minimum required paths (e.g., only the agent runtime can reach the guardrail service).

CORS configuration. The API gateway accepted * as the allowed origin in the default configuration. Fix: we changed the default to reject all cross-origin requests, requiring administrators to explicitly configure allowed origins.

Missing Content-Security-Policy headers. The frontend nginx configuration served pages without CSP headers. Fix: we added a strict CSP that restricts script sources to the application's own origin.

Redis without AUTH. The default Docker Compose configuration ran Redis without a password. Fix: we added a generated password to deploy/.env.example and configured all services to use it.

MinIO default credentials. The default MinIO deployment used minioadmin/minioadmin. Fix: same approach as Redis, generated credentials in deploy/.env.example.

Qdrant without API key. The vector database was accessible without authentication from any container on the Docker network. Fix: we enabled Qdrant's API key authentication and added the key to the service configuration.

Log injection. User-supplied strings were written directly into structured logs without sanitization. A user could inject fake log entries. Fix: we switched to structured JSON logging with proper escaping across all Python services.

Sandbox image pinning. The sandbox worker image tag was latest, meaning container content could change unpredictably. Fix: we pinned to a specific digest in the configuration.

Guardrail policy caching. Guardrail policies were fetched from the database on every request with no caching. Under load, this created a hot path to PostgreSQL. Fix: we added a TTL cache (default 60 seconds) for policy lookups, with cache invalidation on policy updates.

Missing request size limits. The API gateway had no maximum request body size, allowing memory exhaustion via large uploads. Fix: we added a configurable max_body_size (default 10MB) to the gateway.

Dependency pinning. Python requirements.txt files used >= version specifiers. Fix: we switched to exact pins with hashes for reproducible builds.

TLS certificate validation. The external LLM gateway did not verify TLS certificates when connecting to OpenRouter. Fix: we enabled certificate verification with the system CA bundle.

Lessons learned​

Three patterns stood out:

1. Fail-closed by default. Every security boundary (guardrails, auth, rate limiting) should block requests when the checking mechanism is unavailable. Fail-open is the most dangerous default in a security-sensitive system.

2. Multi-tenant isolation is an ongoing discipline. Adding tenant_id to every table is the easy part. The hard part is ensuring every query path, every cache key, and every error message respects the tenant boundary.

3. AI-specific attack surfaces are real. SSRF via agent tool calls, prompt injection to bypass guardrails, and recursive agent spawning are not theoretical. They showed up in our audit and needed specific mitigations.

Choosing the values​

We used browser inspection and side-by-side screenshots to compare headings, body text, code blocks, tables, sidebar links, and the navbar. That let us tune actual rendered values instead of guessing from a screenshot.

The key values we captured:

• Page background: rgb(14, 12, 13), nearly black with a warm undertone, not pure #000
• Body text: #a6a1a0 on dark, Inter font, 16px, line-height 1.75
• Headings: #e6e1e0, DM Sans, varying weights from 600 to 700
• Primary accent: A warm amber, adapted to #d4a574 to give the docs their own identity while staying readable on dark backgrounds.

The warm dark theme​

The default Docusaurus dark theme uses cool grays and blues. We wanted a warmer neutral range, so the backgrounds have a slight red/brown shift:

[data-theme='dark'] {
  --ifm-background-color: #0e0c0d;
  --ifm-background-surface-color: #131112;
  --ifm-font-color-base: #a6a1a0;
  --ifm-heading-color: #e6e1e0;
  --ifm-navbar-background-color: #0e0c0d;
  --ifm-footer-background-color: #0a0909;
}

The difference between #0e0c0d and Docusaurus's default #1b1b1d is subtle in isolation but obvious side by side. The warm background makes text feel less harsh and reduces eye strain during long reading sessions.

Table styling​

This was the biggest visual improvement. Default Docusaurus tables have alternating row backgrounds, visible borders on all sides, and a distinct header background color. The revised tables use just separator lines:

.markdown table thead tr {
  border-bottom: 1px solid rgba(70, 65, 64, 0.5) !important;
  background: transparent !important;
}

.markdown table tbody tr {
  background: transparent !important;
  border-bottom: 1px solid rgba(45, 40, 38, 0.5) !important;
}

We had to use !important liberally because Docusaurus injects table styles at a high specificity through its theme. Killing the striped row backgrounds (--ifm-table-stripe-background: transparent) and the default border color (--ifm-table-border-color: transparent) handles most of it, but some rules needed the override.

Code blocks​

The code blocks use a 16px border radius and a #1f1f1f background that is slightly lighter than the page background, giving them subtle contrast without a visible border:

.prism-code {
  border-radius: 16px !important;
  border: none !important;
  font-size: 14px;
  line-height: 1.7;
  padding: 14px 16px !important;
}

[data-theme='dark'] .prism-code {
  background-color: #1f1f1f !important;
}

The monospace font is JetBrains Mono, which has better readability at small sizes than most monospace options and includes programming ligatures.

The result​

The total CSS override is about 500 lines. The visual impact is significant: the documentation feels like a purpose-built site rather than a template with swapped colors. Three fonts (Inter for body, DM Sans for headings, JetBrains Mono for code) provide clear hierarchy. The warm palette reduces the clinical feel common in technical documentation.

The result is still Docusaurus underneath, but it reads more like a focused product manual than a generated documentation shell.