Documentation · Reference

The app.json manifest

Every app folder contains an app.json file. The engine reads it at startup to determine how to run the app. An Owner can edit the manifest in the app’s Configuration tab in the engine console.

01 /Example

This manifest belongs to “Parts price list”, the sample app in the agent standard. It is a PocketBase app with sign-in, two roles and the import tool. As the standard requires, technical identifiers are in English. Users see the name and description.

{
  "id": "parts-pricelist",
  "name": "Parts price list",
  "description": "Prices of the spare parts in the warehouse, updated from the supplier's Excel or CSV file.",
  "kind": "pocketbase",
  "access": "login",
  "port": 8105,
  "version": "0.1.0",
  "owner": "Spare parts warehouse",
  "auth": {
    "collection": "users",
    "roleField": "role",
    "roles": ["manager", "storekeeper"],
    "defaultRole": "storekeeper"
  },
  "tools": ["import"]
}

A static app that serves only pages and is open to everyone has a shorter manifest.

{
  "id": "guida-officina",
  "name": "Workshop guide",
  "kind": "static",
  "access": "public",
  "port": 8106,
  "version": "0.1.0",
  "owner": "Workshop"
}

02 /Fields

03 /Values for kind

04 /The auth section

This section applies to PocketBase apps with login access. When a person enters from the portal, the engine creates or updates a user with the same email address inside the app. On first sign-in the engine assigns the base role. After that, roles are managed in the app or through “Access and roles” in the console. The auth section tells the engine where to write these values.

The sample app has two roles, manager and storekeeper, stored in the role field. New users start as storekeepers.

"auth": {
  "collection": "users",
  "roleField": "role",
  "roles": ["manager", "storekeeper"],
  "defaultRole": "storekeeper"
}

An app migration creates the role field with the same values as roles. When a role is added to the manifest later, the engine adds it to the field’s allowed values. If a role is removed from the manifest, the field still accepts it so existing users can continue signing in. The console stops offering it for new assignments.

When you create a PocketBase app with sign-in and roles in the console, the engine writes the auth section and adds the role field to the app’s users.

05 /Code layout

apps\<id>\
├── app.json            the manifest
├── app.json.prima      previous manifest version after a console edit
├── release\            code, replaceable independently of the data
│   ├── public\         static app pages
│   ├── pb_public\      PocketBase app pages
│   ├── pb_hooks\       hooks (PocketBase JavaScript)
│   └── pb_migrations\  schema migrations
├── state\
│   └── pb_data\        data, excluded from the delivery package
└── logs\               process output

A static app needs only app.json and release\public.

06 /Reserved engine paths

The engine handles these paths on every app port. Reserve them for the engine when building your app.

The engine rejects PocketBase administrator calls on app ports (/api/collections/_superusers/…). Use the engine console for administration.

07 /Engine validation

The engine reads app manifests at startup and when an Owner selects “Rescan folders”. It rejects a manifest if any of the following applies.

• The file is invalid JSON.
• The file has two keys equal apart from upper and lower case (for example port and Port).
• kind is outside the three allowed values.
• name is missing.
• port falls outside 1024–64000, or the engine, another app or another program is already using the public or internal port.
• defaultRole is not one of the declared roles.

New folders also undergo the “New app” checks. The identifier must be 3–32 characters long, unreserved and unused by any other app. If access has a value other than public or login, the app requires sign-in.

An invalid manifest does not stop a registered app. It keeps running with its last valid manifest and the engine reports the issue. The engine disables the app only when its folder disappears. Warnings appear in the “Rescan folders” message and in the engine history. When you create an app in the console, the engine also checks that roles contain only lowercase letters, digits and underscores.

08 /Rules for app developers

The agent standard contains the full rules, code examples and pre-delivery checklist. The main points are listed below.

• Use relative paths and /__platform/portal for the link back to the portal. Keep hardcoded addresses and ports out of your code.
• Package only the code. Exclude pb_data, real data and test accounts.
• Change the data schema through migrations. Never delete pb_data to change the schema.
• Protect data using PocketBase’s server-side API rules. Hiding a button leaves the underlying data accessible.
• Users cannot change their own role. The engine enforces that restriction. An Owner or an Admin who manages the app can change roles from the console. If the app allows it, the person with its highest role can also assign roles.
• Apps with sign-in do not need a registration page or a “Sign out” button. Users sign in and out through the portal.