Before we tackle more‑complicated use cases, you should familiarize yourself with the Boxel environment.
Dashboard
This is where you see all the workspaces you have access to. Workspaces are like separate Google Drive or Dropbox folders that organize everything related to one project or domain.
Once you enter a workspace, you’ll see the Card Browser—a reflection of the workspace’s database. It shows all items that have been created, across all types. It starts out empty but fills up quickly.
If you want to see how this content and code are represented, flip to Code Mode, which lets you browse via a file‑system view. In Code Mode, click File List to see everything that exists in the workspace.
There are two main file types: card definitions and card instances.
Card Definitions
These files contain code—think of them as templates shared across many entities or documents. Changes you make here propagate to every instance that uses that definition. Card‑definition files end with a .gts extension and are viewable and editable in Code Mode.
Card Instances
Think of instances as rows in a spreadsheet. They store unique data for a specific person, project, or company. Editing data changes only that record; the formatting and business logic remain shared. Card instances are saved as .json files and can be edited in the code editor or in the Preview pane on the right.
Be mindful of whether you’re looking at a template (.gts) or an instance (.json); that determines whether a change affects one record or every record that shares the template. Don’t worry—if you describe your intent clearly, the AI agent usually does the right thing.
AI Assistant & Models
Whether you’re in Interact Mode or Code Mode, you can summon the AI assistant. It’s context‑aware:
- Interact Mode (default model: ChatGPT 4.1) for day‑to‑day tasks.
- Code Mode (default model: Claude Sonnet 4.0) for code generation.
Different models have different pricing; more‑capable “frontier” models consume more Boxel credits.
To check your credit balance, click your user icon in the bottom‑left corner. You’ll see your monthly allowance and any extra credits purchased or granted during community testing. If you run out, the AI won’t respond until you top up or upgrade your plan. Code generation can consume ~1,000 tokens per session; interacting with data is cheaper, especially with GPT‑4.1. Actions in Code Mode send more information to the AI and hence use more tokens; if you’re only manipulating data, stay in Interact Mode.
Working With Your Application
After creating your app, you can browse it or use Search to find cards in your workspace. You can also open cards side by side in Interact Mode; a common pattern is to open the same card on the right in Edit mode to see real‑time changes.
Incremental Prompting
Boxel lets you make incremental changes by instructing the AI to work on one part of the code at a time. Instead of asking for an end‑to‑end experience, you can proceed methodically.
- Start with the schema (data structure). In Code Mode, click New → Card Definition and name it—for example, Expense Report.
- Tell the AI: “Create a schema for an expense report: key fields for the report plus an item for associated receipts. Fields only; no template yet.”
- After the schema is created, switch to Edit view to test data entry. Expense Report.gts will now contain multiple card and field definitions—similar to tabs in a spreadsheet. Use Inspector (left column) to switch between Expense Report, Expense Item, and Receipt.
Even without a custom template, you’ll see the skeleton of a working app. Navigation is off in Preview, so to drill down into items, open a card in Interact Mode (card stacking). With Boxel development skills loaded, you can edit templates in either mode, but Code Mode lets you specify field types and formatting precisely.
Adding Computed Fields
Back in Code Mode, ask the AI to add a computed field:
“In Expense Item, add a field that shows ‘Requires approval’ when the amount is over $300, ‘No approval needed’ when under $300, and ‘Requires corporate review’ when over $1,000.”
The new computed field updates automatically as data changes. Then ask the AI to create sample content:
“Please make a sample dataset for these cards and fields so I can navigate an example expense report.”
Use Search‑and‑Replace if needed.
Designing the Views
Once the structure looks good:
- In Code Mode, open Isolated View and design a user‑friendly template.
- When satisfied, ask the AI to create Fitted and Embedded views so the report can be embedded elsewhere (e.g., an employee profile).
If a format is missing, ask the AI:
“Create a beautiful embedded and fitted view.”
Preview the fitted view via its tab or in Interact Mode; toggle to Strip view with View As in the Card Browser.
By incrementally building your card‑based application, you guide direction more precisely and save tokens (fewer large, expensive generations). Think of Boxel as building with LEGO bricks—one component at a time—rather than throwing paint at a canvas and hoping for a good outcome.
In future chapters, we’ll cover design techniques to align the app’s style with your brand guidelines.
