App structure and runtime
Updated 2026-11-13. Sources include the platform skill, app window and web runtime, backend protocol, agent apps, and SDK.
Every app has a web interface. Apps that use private service keys can include a backend. Apps can also provide instructions for the user’s AI tool to carry out routine tasks.
Web interface and SDK
- The platform serves static web files from the registered app folder.
web.entryis relative toweb.root. The entry can be a standalone HTML file or output from a build using a tool such as Vite or React. - Load
/_platform/sdk.jsbefore the app’s module to access the SDK throughwindow.panda. Any app can enable SQL, attachments, and AI handoff throughplatform.sdkApiVersion: 1. The platform handles/_platform/*even when the app has a backend. - The web interface reads public values from
/_platform/config.jsonorpanda.config(), independently of the SDK data setting. The platform injects secrets into the backend only. panda.context.get().projectRootreturns the app folder’s absolute path in the operating system’s native format. The SDK must be enabled.- A user click can call
panda.ai.open(text)ifcapabilitiesincludesai.open. Text must be nonempty and at most 2,000 characters. The platform opens the selected AI tool in the current app folder and fills in the text for the user to send. If direct opening is unavailable, the platform copies the text and asks the user to paste it. The app can also offer a copy button.
Building and reloading
development.buildprepares the web interface with or without a backend. The platform runs managednpm ciand the declarednpm run <script>indevelopment.sourceDir, which defaults to.. The script must produce the entry underweb.root. The platform does not append an output directory argument.- Close the app window before using Prepare app or
app build --app <id>. For a CLI build, usetask waitto wait for the result. Builds write to the app folder. If a build fails, check the logs, Git status, and actual output. - When the runtime files are ready, confirm that the user has saved pending edits, then click Reload in the title bar or run
app reload --app <id>. The platform reads the manifest and configuration again, restarts the backend if present, and opens the app if closed. - Each app has one native window. Opening the app again brings the existing window to the front. If the manifest is invalid or a required setting is missing, reload preflight preserves the current instance. A failed startup switch reports an error. Fix it before reloading again.
- Declare both
window.widthandwindow.heightas integers from 1 through 32768.rememberSizedefaults totrue. Without a window declaration, the default is 1080 × 780, resizing is remembered, and the minimum content area is 640 × 480. alert,confirm, andpromptuse native dialogs. External links andwindow.openopen in the system browser.
Optional Node 24 backend
Apps that declare backend must ship ready-to-run backend files and dependencies alongside the web interface. The web build does not compile the backend. Starting the backend does not install dependencies. Opening the app starts the service, and closing the app stops it.
| Stage | Protocol |
|---|---|
| Startup | Exchange newline-delimited JSON over stdin and stdout. On initialize, check protocolVersion: 1, the instanceId, and the token. Once listening, send ready with the actual host and port. |
| HTTP | Requests include Authorization: Bearer <token> for the current instance. GET /_platform/health returns the same instanceId, protocolVersion: 1, and status: "ok". |
| Heartbeat | Reply to ping with a pong containing the same instanceId and requestId. |
| Shutdown | On shutdown, send stopping, stop accepting requests, save data, close listeners and child processes, and exit. Follow the same cleanup steps when stdin closes. |
Reserve stdout for control messages and write normal logs to stderr. Backend startup and the web proxy share a 30-second budget. Each health check has up to 10 seconds, a ping has 3 seconds, and a graceful shutdown has 5 seconds.
| Environment variable | Meaning |
|---|---|
APP_HOST |
Backend listen address, 127.0.0.1 |
APP_PORT |
Backend listen port. 0 requests a system-assigned port. |
APP_DATA_DIR |
The app’s data/ directory, created before startup |
APP_CACHE_DIR |
Private platform cache directory |
APP_TEMP_DIR |
Private platform temporary directory |
Each configuration field’s name |
The user-supplied value injected into the target backend |
Web paths and network access
- An app runs at the root of a fixed
http://127.0.0.1:<port>address and can refer to assets as/assets/.... A missing page path without an extension falls back to the home page. Asset files and platform endpoints do not use the fallback. - The platform serves
/_platform/sdk.js,/_platform/config.json, and/_platform/api/v1/. The web root does not expose database or dependency directories, hidden files,panda.json, links that leave the app boundary, or hard links that fail validation. - Declare
origin,purpose, anddataSentunderruntimeRequirements.network.connectfor external requests from the web interface. The service must allow cross-origin access. Camera and microphone use requires a purpose underruntimeRequirements.devicesand operating-system permission. - The web interface reaches the backend on same-origin paths listed in
backend.apiPrefixes. Omission defaults to/apiand/tts. Use[]to disable proxying. External web requests follow the web declaration. Backend network requests are independent of that policy. - Validate application request sizes. Keep the backend port and token out of the web interface. The proxy supports streaming requests. Application redirects and WebSockets are outside the proxy contract.
Agent apps
agent.instructionspoints to instructions for routine tasks. The user’s AI follows them to gather or process information. The app shows the results, stores data, and accepts feedback. Gleaner is one example.- The app root is the AI tool’s working directory. Routine tasks write only to tables and columns allowed by the instructions. The app creates and upgrades tables on startup. If a database or table is missing, ask the user to open the app first.
- Users can continue using the app while their AI tool is offline. The database retains their feedback for the next run. When they want new results, they start a task in their own AI conversation.
- Use Change it your way to modify the app itself. Explain proposed changes before editing its instructions. Schema upgrades only add tables or columns. Update affected instructions and documentation, then reload before running routine tasks.
Platform rules · Manifest format · Shared data rules · Adding apps