# Apps
> Author and deploy LimaCharlie "apps" — self-contained AI-generated HTML mini-apps that render in a sandboxed iframe in the LimaCharlie web UI and call LimaCharlie APIs through a brokered, permission-scoped runtime (window.lc). Use when a user wants to create, edit, or understand a custom app/dashboard/tool embedded in the LimaCharlie console (the `app` hive).
- Skill: `refractionpoint/apps` (Agent Skill)
- Install (CLI): `npx skillmds@latest add refractionpoint/apps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/refractionpoint/apps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: refractionpoint (https://skillmd.com/u/refractionpoint)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/refractionpoint/apps
---
# LimaCharlie Apps
An **app** is a single self-contained HTML document (HTML + inline CSS + inline
JS) stored in the `app` hive. The LimaCharlie web UI renders it inside a
**sandboxed iframe** and injects a trusted runtime, `window.lc`, that brokers
LimaCharlie API calls using a JWT scoped to a subset of the viewing user's
permissions. You write **only the app body** — the runtime, base styles, and
security wrapper are injected by the host.
Full contract: `web-app-frontend/docs/ai-guides/apps-runtime-contract.md`.
## The golden rules (apps are validated against these)
1. Output is a **single self-contained `` fragment**. Do NOT emit
``, ``, ``, or `` — the host owns those.
2. **No external resources**: no `
```
## Golden reference app
A complete, conforming app body. Use it as the template.
```html
Sensor status
Loading…
—Sensors online
```
This app would declare `required_permissions: ["sensor.list"]` and no
`allowed_origins`.
## Creating the app record
Apps live in the `app` hive (org-scoped). Authoring is done via the CLI; the web
UI is for running and managing apps, not editing HTML.
1. **Validate the HTML against the golden rules above** before writing it.
2. Write the record JSON to a file (the `data` payload mirrors the backend
`AppRecord`):
```bash
cat > /tmp/app.json << 'EOF'
{
"display_name": "Sensor status",
"description": "Live count of online sensors",
"icon": "🛰️",
"html": "<...the app body from above...>",
"required_permissions": ["sensor.list"],
"allowed_origins": [],
"required_services": [],
"locations": ["standalone"],
"expected_context": []
}
EOF
```
- `locations`: any of `standalone`, `within_a_sensor`, `within_a_detection`,
`within_a_case`, `within_a_dr_rule`. For embeds, list the identifiers you
read from `lc.ctx.context` in `expected_context` (e.g. `["sid"]`).
- `allowed_origins`: only `https://host` origins (no path), and only if the
app must reach an external (third-party) API directly. Empty = LC only (safest).
- `required_services`: first-party LC services the app calls via
`lc.api(..., { service })` — any of `search`, `replay`, `cases`, `ai`. Empty
= main API only. Declaring a service is required before the app can call it.
3. **Set** the record (the `--key` is the app's stable id/slug):
```bash
limacharlie hive set --hive-name app --key sensor-status --input-file /tmp/app.json --oid
```
4. **Enable it** — hive records are NOT auto-enabled on set:
```bash
limacharlie hive enable --hive-name app --key sensor-status --oid
```
5. Manage from the UI: **Apps** in the org sidebar (`/orgs//apps`), or the
matching object-context page for embeds.
## Common pitfalls
- **Author lacks a declared permission** → the `set` is rejected. You can only
require perms you hold.
- **App "works for me" but not for an admin** is impossible by design: at view
time the JWT is `required ∩ viewer's perms`, so it can only ever shrink.
- **Forgot to enable** → the app won't appear/run. Run `hive enable`.
- **External fetch fails silently** → the origin isn't in `allowed_origins`
(CSP blocked it). Add it, or route via `lc.api` if it's LC data.
- **`lc.api(..., { service })` rejected with `denied`** → the service isn't in
`required_services` (or the org can't resolve it). Add it to the record.
- **Unstyled / wrong colors** → you hardcoded styles or loaded an external
sheet. Use `.lc-*` / `--lc-*`.
- **Chart is blank / invisible** → its container has no height. Put the
`