Skip to content

CLAUDE.md

Latest commit

 

History

History
129 lines (104 loc) · 5.42 KB

CLAUDE.md

File metadata and controls

129 lines (104 loc) · 5.42 KB
Raw

BoxLite Documentation Site

Project Overview

This is the official documentation site for BoxLite — a local-first micro-VM sandbox for AI agents. Stateful, lightweight, hardware-level isolation, no daemon required. The site is built with Mintlify and deployed automatically on push to main.

Tech Stack

  • Mintlify — documentation platform (config in docs.json)
  • MDX — Markdown + JSX for page content
  • GitHub App — auto-deploys to production on push to main

Directory Structure

docs.json              # Mintlify config: navigation, theme, colors, logo
index.mdx              # Home page
faq.mdx                # FAQ & troubleshooting
getting-started/       # Quickstart guides (Python, Node.js, Rust, C)
architecture/          # Architecture, components, security, networking
reference/             # SDK API reference (python/, nodejs/, rust/, c/)
boxrun/                # BoxRun platform docs (CLI, Python SDK, REST API, config)
guides/                # How-to guides (build, examples, AI integration, etc.)
development/           # Internal docs (CLI, Rust style guide)
snippets/              # Reusable MDX snippets (e.g., prerequisites.mdx)
images/                # Static images (hero, screenshots)
logo/                  # Light/dark SVG logos
.github/workflows/     # GitHub Actions (docs sync automation)

Common Tasks

# Preview locally
mint dev               # → http://localhost:3000

# Check for broken links
mint broken-links

# Update Mintlify CLI
mint update

Key Conventions

Page Structure

  • Every .mdx page must have frontmatter with title and description
  • Use sidebarTitle in frontmatter when the nav title should differ from the page title
  • Start with introductory context before diving into steps

Navigation

  • All navigation is defined in docs.json under navigation.tabs
  • 4 tabs: Documentation, SDK Reference, Guides, Development
  • Never add a page to navigation without creating the file first
  • Never remove a page without checking for inbound links

Writing Style

  • Active voice, second person ("you")
  • Sentence case for headings
  • Bold for UI elements: Click Settings
  • Code formatting for: file names, commands, paths, code references
  • One idea per sentence

MDX Components

  • Use Mintlify built-in components (Card, CardGroup, Note, Warning, Tip, Tabs, Tab, Snippet, etc.)
  • Prefer MDX components over raw HTML
  • Code blocks: always include language identifier, add filename.ext title when relevant
  • Use realistic parameter values, not foo/bar placeholders

Snippets

  • Reusable content goes in snippets/ and is included with <Snippet file="filename.mdx" />
  • Currently: snippets/prerequisites.mdx (system requirements)

Theming & design system

The site uses an ASCII / terminal design language mirroring the BoxLite console restyle (boxlite-ai/boxlite#829). Tokens are split across two files:

  • docs.json → colors (primary #00B0F0), appearance.default: dark, fonts (heading IBM Plex Mono, body Inter), background.color, styling.codeblocks (github theme).
  • custom.css → everything Mintlify config can't express: square corners (radius 0), bordered card/code surfaces, terminal-dark code panel, cyan step markers, uppercase sidebar labels, recolored callouts. Mintlify auto-loads any root custom.css.
Token Dark Light
accent (brand) #00B0F0 #00B0F0
page bg #13161B #FFFFFF
card #1A1D24 #F3F4F6
code panel #0D0F13 #F7F9FC
border #2A2F3A #E2E5EA

When adding CSS, target stable Mintlify hooks (.card, .code-block, .callout, .steps, .sidebar-title, table.table) — utility classes are unstable. Verify both themes with mint dev; mind that Mintlify ships some rules !important, so overrides may need higher specificity (see the code-panel block in custom.css).

Important Files

File Purpose
docs.json Mintlify config — navigation structure, theme, colors, logo, links
custom.css Terminal/ASCII design system — square corners, surfaces, code panel, accents
index.mdx Home page — hero section, feature cards, entry points
snippets/prerequisites.mdx Shared system requirements snippet
.mintignore Files excluded from Mintlify build
.github/workflows/sync-from-boxlite.yml Auto-syncs docs when BoxLite SDK PRs merge

Terminology

Use these terms consistently across all documentation:

Term Usage
BoxLite Local-first micro-VM sandbox (capital B, capital L)
BoxRun Sandbox management platform (capital B, capital R)
LiteBox The VM instance type (capital L, capital B)
box Generic reference to a sandbox instance (lowercase)
SimpleBox / CodeBox / BrowserBox Python/Node.js SDK box types
BoxHandle BoxRun SDK handle to a specific box
BoxRunClient BoxRun Python SDK client class
Guest Agent The agent running inside the VM
Jailer The security isolation component
ShimController Process lifecycle manager