App manifest

Keep manifest.yaml beside your app’s single top-level .star file. These are YAML keys, which do not always have the same names as CLI flags.

id: morning-glow
name: Morning Glow
summary: A calm start to your day
desc: Shows the information you need in the morning.
author: Your name
refresh_interval_seconds: 300
network_hosts:
  - api.example.com

Required fields

Field	Meaning and limits	`apps init` flag
`id`	Stable, unique hosted handle: 2–63 ASCII lowercase letters, digits or hyphens; start with a letter or digit	`--handle`
`name`	Nonempty title-case app name, at most 32 UTF-8 bytes	`--name`
`summary`	Nonempty short summary, at most 32 UTF-8 bytes; start with an uppercase character and do not end with `.`, `!` or `?`	`--summary`
`desc`	Nonempty full description; start with an uppercase character and end with `.`, `!` or `?`; hosted descriptions are at most 2,000 UTF-8 bytes	`--description`
`author`	Nonempty author or organization name	`--author`

The name and summary limits include spaces. Exactly 32 bytes is allowed. ASCII characters each use one byte; accented characters and emoji may use more. Older CLI error messages say “less than 32 characters”; the actual validation is a maximum of 32 UTF-8 bytes.

Optional fields

Field	Meaning
`app_id`	Hosted project UUID, written by the first successful `apps push`; keep it to target the same project on later pushes
`refresh_interval_seconds`	Hosted refresh interval from 30 to 86,400 seconds; omitted or `0` uses 300 seconds
`network_hosts`	Exact HTTPS hostname allowlist, without schemes, paths or wildcards; omitted means no network access in Cloud
`network_host_fields`	Non-secret text setting IDs containing HTTPS URLs; Cloud allows the configured hostname. Available with CLI v0.54.10 and the current hosted service.
`credentials`	Secret field ownership declarations, described below
`supports2x`	Boolean compatibility flag for apps supporting 2× local rendering; device previews still require 64×32 pixels
`minPixletVersion`	Minimum compatible runtime version
`broken`	Catalog/checking compatibility flag for intentionally broken apps; not a way to bypass hosted validation or review

An App ID identifies a project. A revision ID identifies one immutable upload. A device ID identifies a display. An installation ID identifies one copy in its rotation. See CLI commands for discovering and using them.

Credentials

credentials:
  - id: api_key
    owner: publisher
    provider: example.com
    required: true

Each id must match a secret text field in the app’s configuration schema. owner is publisher or user; provider is a nonempty provider identifier. required defaults to false. IDs must be unique within the declaration list. Store publisher values with niblet apps secrets set api_key. Users supply user-owned values through their installation settings. Never put secret values in manifest.yaml or source code.

URLs supplied through settings

This manifest field is available with CLI v0.54.10 and the current hosted service.

network_host_fields:
  - feed_url

Declare feed_url as a non-secret text field in get_schema(). Its configured value must be an HTTPS URL on port 443 with a DNS hostname and no username or password. IP literals are rejected. Private and reserved addresses, including addresses reached through DNS or redirects, remain blocked by the egress proxy. Declare static redirect destinations separately in network_hosts. Static hosts and URL fields share a limit of 64 declarations. Network permission is frozen per uploaded revision. Private apps do not need human review to use these permissions. Never put credentials in an ordinary URL setting; use the credential fields instead.

App runtime

Platform

Required fields

Optional fields

Credentials

URLs supplied through settings

​Required fields

​Optional fields

​Credentials

​URLs supplied through settings

Required fields

Optional fields

Credentials

URLs supplied through settings