Apps

An app is a small web app that Cengrid hosts behind its own sign-in. Plugins ship two types: static (prebuilt files, nothing runs) and docker (a Dockerfile that Cengrid builds and runs). The agent can also publish apps itself.

Unlike other capabilities, apps are instances, not overrides. Adding an app to a scope creates a deployment owned by that scope: the organisation and each team run separate copies, and a team does not inherit the organisation’s.

Layout

• Directoryapps/

  • Directoryreport/

    • app.json
    • Directorypublic/

      • index.html

Each subdirectory of apps/ that contains an app.json and the files its type requires is one app. Docker apps need a Dockerfile; static apps need a ready-to-serve index.html. Repository build commands never run during import or install, so select a prebuilt output such as public or dist.

app.json

apps/report/app.json

{
  "name": "report",
  "title": "Report dashboard",
  "description": "Browse reports using a configured API endpoint and archive preference.",
  "type": "static",
  "directory": "public",
  "variables": [
    {
      "name": "API_BASE_URL",
      "description": "Base URL of your reports API, for example https://api.example.com.",
      "required": true,
      "type": "string",
      "regex": "^https://[^\\s]+$"
    },
    {
      "name": "SHOW_ARCHIVED",
      "description": "Show archived reports when the dashboard opens.",
      "type": "boolean"
    }
  ]
}

Field	Applies to	Meaning
name	both	1 to 33 lowercase letters, digits or hyphens, not starting or ending with a hyphen. Defaults to the folder name. Identifies copies across folder moves. Changing an installed app’s type needs a new name.
title	both	Display name. Defaults to name.
description	both	Required, up to 400 characters.
type	both	static or docker. Defaults to docker.
variables	both	Configuration fields, see below.
secrets	docker	Secret fields, see below. Static apps cannot declare secrets.
port	docker	Defaults to 8080. The runtime sets PORT. The app must listen on 0.0.0.0 and answer GET / with a status below 500.
env	docker	Non-secret defaults injected at startup. .env files are never imported.
directory	static	The folder to publish, defaulting to the app folder.
spa	static	true falls back to the root index for client-side routes.
configFile	static	Name of the generated public configuration file. Defaults to config.json.

Unknown top-level fields are warnings. File modes are not preserved, so start scripts with sh script.sh or RUN chmod +x.

Configuration fields

Both variables and secrets are arrays of fields:

Key	Meaning
name	A valid environment-variable name, distinct across variables and secrets. PORT is reserved.
description	Required.
required	Optional, default false.
type	string (default), number or boolean.
regex	Optional pattern, checked by a safe-regex validator that rejects unsafe repetition and lookarounds.

An app may declare at most 49 fields combined, with values up to 4,096 characters. Adding an app that declares configuration opens a form, and the installed copy’s Configure action changes its own values. Each change creates a new deployment version, and re-sync preserves configured values.

• Docker variables and secrets become process environment variables, for example process.env.API_BASE_URL. Secrets are encrypted, never returned by configuration APIs and supplied only at process start. On a runtime that cannot inject secrets separately, which today includes AWS, an app with required secrets is unavailable and supplying optional secrets is rejected.
• Static apps get a generated config.json at the root of their published files, containing public variables. Your app should fetch it and validate the values before rendering. The file requires the same sign-in as the app.

Static apps are public to their users

Everything in a static app’s files and config.json is readable by anyone who can open the app. Put credentials and privileged calls behind a backend.

Add an app

1. Connect the plugin and open Apps → Available.
2. Add the app to the organisation or a team and fill in the configuration form.
3. Watch the status: Docker copies show Building, Running or Build failed with output, and static copies show Ready.

A failed update leaves the previous version serving. Re-sync republishes only copies whose files changed. Remove from scope archives that scope’s copy, and adding it again restores it with its configuration. Users can open plugin apps but cannot clone, push to, rename, share or roll them back.

Runtimes

Dockerfile apps run on Docker and on AWS Lambda MicroVMs. Fly does not build Dockerfile apps, so they are listed as unavailable there. Static apps need no build runtime on any target. Static output is limited to 1,000 files, 50 MB total and 20 MB per file by default.

The agent can also publish static pages (publish with static: true) and Dockerfile apps (publish with dockerfile: true) on its own. By default an organisation may have up to 20 non-archived Dockerfile-built apps that the agent published. Apps from plugins do not count toward the limit.

Example

The examples/static-app plugin in the product repository is a ready-to-publish dashboard with these variable declarations. See capability examples.