panda.json reference
Updated 2026-11-13. Sources include the platform manifest reference, JSON Schema, manifest validation, and configuration field validation.
The panda.json file identifies the app, its web entry point, and any backend or agent instructions. Store it in the app root with the source files.
File location and fields
- Use UTF-8 JSON and set
manifestVersionto2. Update older manifests to the current format. The platform rejectsruntime, unknown fields, duplicate keys, invalid types, and explicitnull. - The manifest declares the app structure and available settings. The platform records instance IDs, ownership, saved configuration values, secrets, and logs.
- Use
/as the path separator. An entry is relative to its corresponding root. Other paths are relative to the app root. Avoid absolute paths, paths that escape the app, and links to external locations. A web root cannot point todata/,node_modules/, or hidden content. - Validate changes against the shared schema. The platform also checks file existence, path boundaries, and references between fields.
| Field | Required | Meaning |
|---|---|---|
manifestVersion |
Yes | 2 |
$schema |
No | Editor hint. The platform does not fetch it. |
app.name |
Yes | Name shown on the app card and in the window title |
app.version, app.description, app.icon |
No | Version, summary, and path to a PNG icon in the app folder |
web.root, web.entry |
Yes | The web root can be .. The entry is relative to the web root. |
backend |
No | Declares a backend. Set root, entry, nodeMajor: 24, and protocolVersion: 1. |
backend.apiPrefixes |
No | Full path-segment prefixes for app endpoints. Defaults to /api and /tts. Use [] to disable proxying. The root path, prefixes starting with /_platform, encoded paths, and dot paths are forbidden. |
platform.sdkApiVersion |
No | Set to 1. Any app can enable the SDK. |
development |
No | sourceDir defaults to .. Set build.kind to npm and build.script to an existing npm script. This builds the web interface only. |
configuration |
No | User configuration fields. secret: true requires backend. |
documentation |
No | readme, development, and database. Declared files must exist. |
agent.instructions |
No | Path to an existing non-hidden regular file inside the app, such as AGENTS.md |
window |
No | Both width and height are required when declared. rememberSize defaults to true. |
runtimeRequirements |
No | External addresses and device purposes for the web interface. The backend’s network requests are independent of this policy. |
localization |
No | Overrides platform display text for zh-CN and en. |
If web output is missing, the build declaration determines whether the platform can prepare it. The backend entry and dependencies must be ready ahead of time. Paths in agent.instructions cannot include empty segments, ., .., backslashes, colons, or hidden directories. Agent and backend declarations are independent. The platform uses isAgent for display and continues to validate file access against the manifest and path boundaries.
User configuration
Set configuration.version to 1. The fields array can have up to 32 entries.
| Field | Required | Meaning |
|---|---|---|
name |
Yes | Unique environment variable name. Start with an uppercase English letter and use uppercase letters, digits, and underscores only. Avoid names reserved by the platform or operating system. |
label |
Yes | Name displayed in the form |
type |
Yes | string, url, integer, boolean, or select |
required |
Yes | Whether the user must enter a value |
secret |
Yes | Secret fields must have type string and require backend. |
description |
Yes | Purpose of the setting |
howToGet |
Yes | An array of 1 to 12 nonempty strings explaining how to obtain the value |
placeholder |
No | Input hint |
default |
No | Must match the field type. Secret fields cannot have defaults. A url default must be a valid HTTPS address, and a select default must match one of the options. |
helpUrl |
No | HTTPS URL with no credentials, query, or fragment |
options |
For select only |
1 to 32 value and label pairs with unique values. Other types cannot declare options. |
endpointField |
No | A secret field can reference a public url field in the same declaration to associate the key with a service address. |
The user enters values in the platform form. The web interface can read public values through /_platform/config.json or panda.config(). Strings, numbers, and booleans retain their types. Unset optional values are omitted. At startup, the backend receives configuration through environment variables named by each field’s name. Secrets are injected only into the corresponding backend.
Platform display text and app language
| Localizable object | Keys and supported fields |
|---|---|
app |
name, description |
configuration |
Keyed by the original field name. Supports label, description, placeholder, howToGet, and options. Option labels are keyed by the original value. |
runtimeRequirements.network |
Keyed by connect, images, or media, then by the original origin. Supports purpose and dataSent. |
runtimeRequirements.devices |
Supports purpose for declared camera and microphone entries. |
- Group
localizationbyzh-CNanden. Overrides apply field by field, with missing translations falling back to the original text. AhowToGetoverride replaces the entire nonempty step array. The platform rejects invalid references, empty strings, explicitnull, and unknown keys. - Overrides apply to the platform interface and native window titles. Configuration values, defaults, permissions, paths, and original app information returned by the SDK come from the base declaration.
- Changing the platform language updates display text already loaded. The app can follow
navigator.languageor offer its own setting. The platform does not send its language setting through the SDK, environment variables, or notifications. Reload after editing the manifest.
Reloading after changes
- Prepare the runtime files and save pending input. Then click Reload in the title bar or run
app reload --app <id>. This opens the app if it is closed. - If the manifest is invalid or required configuration is missing, the platform keeps the running instance. A failed startup switch displays an error. Fix the issue and reload again.
- To add a backend, declare
backendand prepare the runtime files. To remove it, also remove all secret configuration declarations. The platform deletes the old secrets after a successful switch and keeps them if the switch fails. - Adding or removing a backend preserves the app ID, address, folder,
data/, public configuration, and browser data. A successful switch invalidates old sessions.
Example 1. Minimal web app
Place index.html in the app root.
1 | { |
Example 2. Agent app with the SDK and a web build
Place AGENTS.md in the app root. The build script in package.json creates dist/index.html. Include a matching npm lockfile.
1 | { |
Example 3. Backend, secret settings, and display translations
Place the backend in backend/server.mjs and the web entry in web/index.html. The user enters their own key in the platform form. The base display text is in Chinese, and localization.en overrides selected labels for English.
1 | { |
Platform rules · App runtime · Data and configuration · Adding apps