Skip to main content
Your source stays on your computer while you build. Niblet Cloud receives it only when you push a tested revision.
1

Create the project

The public app handle is stable and lowercase. Choose it carefully; public metadata can be updated later, but the handle does not change.
2

Build and preview locally

Keep iterating until validation passes and the saved preview matches what you want people to see.To check the same locally rendered WebP on one of your displays, sign in and run niblet devices to find the device ID, then niblet apps preview . --device <DEVICE_ID>. The temporary preview expires after five minutes and does not install or publish the app.
3

Declare hosted network access

Local previews use your computer’s network. Cloud allows only the HTTPS hosts that your revision declares. For a fixed endpoint, add its exact hostname to network_hosts. Private apps do not need public review for this access.For an app that calls http.get(config["feed_url"]), use CLI v0.54.10 or later:
feed_url must be a non-secret text field in get_schema(). Configure a public HTTPS URL on port 443. IP literals, private addresses and userinfo are not allowed. Declare static redirect destinations separately. Never put a token in an ordinary URL setting; use a credential field. See all manifest rules.
Configured URL hosts and improved warnings are available with CLI v0.54.10 and the current hosted service. Static network_hosts is also available in v0.54.9.
4

Upload the tested revision

push checks the project, renders a fresh local WebP, creates or links the hosted app when needed, and writes its stable App ID to manifest.yaml. Later pushes use that App ID automatically. It also prints the revision ID you need for installation or submission.See the manifest reference for every field and its limits.If the manifest declares publisher-owned credentials, configure them after the first push with niblet apps secrets set <FIELD>. The value is read from a hidden prompt and is never written to the project.
5

Use it privately

This step requires CLI v0.54.9 or newer. Run niblet update first.
The app stays in your rotation and renders through the isolated Cloud runtime. It is visible only within your account and needs no public review. Configure required credentials before enabling it. Each install creates a separate copy; manage its settings or remove it from the dashboard.A private install does not mark your revision as reviewed or publish it. Use a separate private project to test changes to an app that is already public.
6

Edit settings and update the app

Open Manage on the installed copy to edit its settings. Settings belong to that copy. Running apps install again creates another copy; it does not replace an existing one or inherit its settings.After changing source, validate and preview it, then push:
Use CLI v0.54.10 or later for automatic-update results and configuration warnings.
A private push updates compatible copies while preserving settings. CLI output lists updated installation IDs and Manage links, and counts copies that need configuration. Such copies keep their current revision until you open Manage and apply the update. An additional copy still requires apps install. Public updates go through review.
7

Submit for public review (optional)

Submission does not publish directly. A reviewer sees the immutable source and the WebP that you generated locally. If changes are requested, edit locally and push a new revision; the previous revision remains unchanged.

Understand app review

Follow each review state and learn what reviewers check.

​
Updating installed apps

Automatic updates are available in the hosted service. Use CLI v0.54.10 or later.
Run niblet apps push . after validating your changes:
  • For a private project, Cloud prepares the new release and updates compatible copies already installed across your account. Each copy keeps its settings, credentials, position and schedule. It does not install on additional displays.
  • For a public project, Cloud submits the upload for review automatically. The previously approved version remains live. Approval rolls out the update.
  • An incompatible copy keeps its working version and shows Update needs configuration. Open Manage, review the new settings and save to apply it. Changed credential providers require fresh credentials.
Only one public review can be active per project. A further push is rejected until that review finishes; it neither replaces the pending submission nor silently queues behind it. Existing review submission rate limits also apply. Use apps install only to add another copy. Future uploads update existing copies automatically. Offline displays receive updated rendering when they reconnect. Private installation is separate from public approval.

​
Understand hosted failures

Hosted diagnostics are available in the dashboard. Read retries require CLI v0.54.10 or later.
Refresh failed → Details, also available in Manage, shows a safe failure category, last attempt, last successful render, retained-frame status and a reference you can share with support. The reference identifies the installation and UTC attempt time; it contains no feed URL, token or raw app output. A retained frame is not confirmation of what an offline device is displaying. A freshness warning such as “This frame expires after 60 seconds; refresh is scheduled every 300 seconds” is advisory. A 60-second max_age is valid; it may expire before the next scheduled render. Change the refresh interval or frame freshness deliberately, allowing for scheduling jitter and network time. Read-only CLI requests retry temporary network failures and 502/503/504/520 twice, after 250ms and 500ms. Installation and other writes are not automatically replayed for these failures. For a persistent server error, send support the HTTP status, UTC time and reference/Ray ID; do not send credentials or full private URLs.
Last modified on September 2, 2026