DocsJade Cloud

Self-hosting

Run a Jade Cloud on a server of one’s own: install, settings, admin commands and backups.

On this page
What it takesInstallSettingsThe web serverThe jade commandBackups and restorePush notificationsWhat gets installed

What it takes

A Linux server (a small VPS is enough) with a domain name pointing at it, root access over SSH, and a few GB of disk. The setup installs everything else: Docker, a web server or proxy, certificates, backups and a jade command for running it.

The same code runs the hosted Jade Cloud. A server of one’s own has no plan limits, and pairs devices with one-time codes instead of App Store subscriptions.

Install

  1. Copy the code over and start the setup. From a checkout of the project on the Mac:
    bash runner/deploy/upload.sh root@your-server --domain jade.example.com
    The code goes into a folder only the SSH account can read, and the setup runs there in the same terminal, as a menu. Nothing on the server changes until Install is chosen. --dry-run shows what it would do without changing anything.
  2. Choose the settings. Every setting starts with a value that fits the server. The menu covers the address, the mode, the web server and the keys below.
  3. Pair a device. When it finishes:
    jade pair
    # prints a one-time code and a link
    Open the link on the phone, or type the code under “Have a pairing code?” in the app.

Keep the master key. jade master-key prints it. It wraps every account’s data key, and it is stored outside the database and the backups. Lose it and the data can’t be opened. Keep a copy somewhere safe, away from the server.

Settings

The menu writes these as environment variables. The ones most people touch:

VariableWhat it does
JADE_PUBLIC_URLThe server’s public address. Webhook URLs and pairing links are built from it.
JADE_MODEselfhosted (paired devices only) or hosted (App Store subscribers).
JADE_MODELS_URL, JADE_MODELS_KEY_FILEThe model server behind Jade AI, if it is offered. Any OpenAI-compatible server works. The key is pasted into the menu, never typed on a command line.
JADE_MASTER_KEY_FILEWhere the master key is kept (made by the setup).
JADE_DATA_DIRThe data folder. The default on a server is /var/lib/jade-runner.
JADE_HOST, JADE_PORTWhere the runner listens. It is local only by default.
JADE_TRUST_PROXYRead the visitor’s address from the proxy’s header (set when a web server sits in front).
JADE_MAX_ACTIVE_TASKSTasks working at once (default 8).
JADE_DAILY_TASK_LIMITThe daily limit of new tasks for accounts without a plan’s limits (very high by default).
JADE_SITE0 turns this website off.
JADE_SERVICES_DIR, JADE_SERVICES_AUTO_APPROVE, JADE_SERVICES_SUBMITS_PER_HOURThe module marketplace: where submissions live, whether new ones are approved automatically, and the hourly limit per address.
JADE_CODE_URL, JADE_CODE_TOKEN_FILEThe code workspace container.
JADE_ALLOW_PRIVATE_NETWORKLets the browser and workspaces reach private addresses. Off by default, and best left off.

Change a setting with jade configure. It keeps every other value and offers to apply the change.

The web server

Jade Cloud listens on 127.0.0.1 only. A web server is the one door from outside:

  • nginx, if it is already there: the setup adds one include line to the site that serves the domain, or a site file of its own. Other sites on the server are left alone. Changed files are backed up first and restored if nginx -t fails.
  • Caddy, if there is no web server: it gets certificates by itself, and runs as an account of its own.
  • none, to put it behind something else.

The jade command

Everything is one command on the server. Run it with no arguments for a menu, or give it a command. jade <command> help explains one.

CommandWhat it does
jade statusHow it is doing.
jade configureChange settings (the menu).
jade updateRebuild from the code on the server and restart.
jade logs [runner|browser|code|caddy]Follow the logs.
jade pair [--new | --account ID | --plan pro|max [--percent N] [--days N]]A one-time code to pair a device. See Sharing a server.
jade accounts, jade devicesThe accounts with their limits, and the paired devices.
jade set-plan ID pro|max|none [--percent N] [--days N]Change an account’s limits.
jade unpair DEVICESign a device out, by id, start of id or name. --all --account ID --yes does all of an account’s.
jade delete-account ID --yesDelete an account and all its data.
jade master-key, jade check-keyPrint the master key. Check that it opens the data.
jade backup, jade restore FILEBack up now (it also runs on a schedule). Put a backup back.
jade models, jade code, jade imagesCheck the model server, the code workspaces and Jade AI Images.
jade services …The marketplace: list [--pending], show, approve, reject, remove, add FILE.
jade keys …Publisher keys for the marketplace: create --label “Name” [--days N], revoke, list. keys list also shows pairing codes, accounts and devices.
jade license showCheck an installed license (for push relay).
jade uninstall [--purge]Remove it. --purge deletes the data too.

Backups and restore

A backup runs on a schedule and on demand (jade backup), into /var/backups/jade-runner. It holds a consistent copy of the database and the settings, readable by root only. The master key stays out of it unless that is switched on in the menu, so a copied backup is unreadable on its own. To restore on the same server: jade restore FILE. To restore on another, give the key the backup was made with: jade restore FILE --master-key FILE. jade check-key confirms that a key opens the data.

Push notifications

Notifications and Live Activities need Apple’s push service. A server of one’s own has two choices:

  • Relay. With a license (--license FILE), pushes go through the hosted Jade Cloud’s relay. No Apple key needed. The relay sees the device token, the kind of push and a task id, never content.
  • Own APNs key. An APNs key from the Apple Developer account (--apns-key) with the team id.
  • Neither. Tasks run, and the app shows them the next time it opens or refreshes.

What gets installed

/opt/jade-runner
Settings, the compose file, secrets, and the code in app/.
/var/lib/jade-runner
The data (SQLite, sealed).
/var/backups/jade-runner
Backups.
Accounts
jade-runner (owns the data), jade-browser, and jade-proxy with Caddy. No shell, password or sudo; not in the docker group.
Containers
The runner, the browser and the code workspace, with read-only filesystems, every capability dropped, memory and process limits, and no privilege escalation. gVisor is an option.

The privacy side of this is in How Jade Cloud is kept apart.