boxel-cli

Boxel Runtime

For a quickstart, see here

Setup

• you will want the Glint vscode extension
• you will want the vscode-glimmer vscode extension
• you will want the Playwright vscode extension
• this project uses mise for tool version management. Install mise and run mise install from the repo root to get the correct Node.js and pnpm versions.
• this project uses pnpm for package management. run pnpm install to install the project dependencies first.
• this project uses docker. Make sure to install docker on your system.
• Ensure that node_modules/.bin is in your path. e.g. include export PATH="./node_modules/.bin:$PATH" in your .zshrc

Orientation

packages/host is the card runtime host application

packages/realm-server is a node app that serves the realm as an HTTP server, as well as, it can also host the runtime application for its own realm.

packages/boxel-ui/addon is the UI components Ember addon

packages/boxel-ui/test-app is the test suite and component explorer for boxel-ui, deployed at boxel-ui.stack.cards

packages/matrix is the docker container for running the matrix server: synapse, as well as tests that involve running a matrix client.

packages/ai-bot is a node app that runs a matrix client session and an OpenAI session. Matrix message queries sent to the AI bot are packaged with an OpenAI system prompt and operator mode context and sent to OpenAI. The ai bot enriches the OpenAI response and posts the response back into the matrix room.

packages/vscode-boxel-tools is a VS Code extension for browsing Boxel workspaces, published as Boxel Tools. It can be deployed via the bot, with staging environment producing a pre-release version.

packages/skills-realm is a realm that hosts AI skills. Skills are maintained in the boxel-skills repository and cloned locally for development. See the Skills Realm README for setup and development workflows.

Catalog Realms

Two catalog realms run side by side. The Cardstack Catalog (served from cardstack/boxel-catalog) is the source of truth for new development and the destination for community submissions. The Legacy Catalog (shipped from this monorepo) remains available during the deprecation window for content that hasn't been migrated upstream.

Realm	Source	URL path	Purpose
Cardstack Catalog	packages/catalog (clones boxel-catalog)	/catalog/	Official catalog. New listings and community submissions land here via pr-listing-create PRs to cardstack/boxel-catalog.
Legacy Catalog	packages/catalog-realm	/legacy-catalog/	Historical catalog shipped from this repo. Kept visible in the workspace chooser while existing content migrates upstream.

Both catalogs appear in the workspace chooser by default; the Cardstack Catalog is sorted first, Legacy Catalog last. Both are controlled by the same SKIP_CATALOG flag — setting SKIP_CATALOG=true skips setup and startup for both.

To learn more about Boxel and Cards, see our documentation

mise Tasks

Development services are managed as mise file-based tasks in mise-tasks/.

Task layout