Self-hosting
Run a Jade Cloud on a server of one’s own: install, settings, admin commands and backups.
On this page
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
- Copy the code over and start the setup. From a checkout of the project on the Mac:
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.
bash runner/deploy/upload.sh root@your-server --domain jade.example.com
--dry-runshows what it would do without changing anything. - 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.
- Pair a device. When it finishes:
Open the link on the phone, or type the code under “Have a pairing code?” in the app.
jade pair # prints a one-time code and a link
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:
| Variable | What it does |
|---|---|
JADE_PUBLIC_URL | The server’s public address. Webhook URLs and pairing links are built from it. |
JADE_MODE | selfhosted (paired devices only) or hosted (App Store subscribers). |
JADE_MODELS_URL, JADE_MODELS_KEY_FILE | The 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_FILE | Where the master key is kept (made by the setup). |
JADE_DATA_DIR | The data folder. The default on a server is /var/lib/jade-runner. |
JADE_HOST, JADE_PORT | Where the runner listens. It is local only by default. |
JADE_TRUST_PROXY | Read the visitor’s address from the proxy’s header (set when a web server sits in front). |
JADE_MAX_ACTIVE_TASKS | Tasks working at once (default 8). |
JADE_DAILY_TASK_LIMIT | The daily limit of new tasks for accounts without a plan’s limits (very high by default). |
JADE_SITE | 0 turns this website off. |
JADE_SERVICES_DIR, JADE_SERVICES_AUTO_APPROVE, JADE_SERVICES_SUBMITS_PER_HOUR | The module marketplace: where submissions live, whether new ones are approved automatically, and the hourly limit per address. |
JADE_CODE_URL, JADE_CODE_TOKEN_FILE | The code workspace container. |
JADE_ALLOW_PRIVATE_NETWORK | Lets 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 -tfails. - 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.
| Command | What it does |
|---|---|
jade status | How it is doing. |
jade configure | Change settings (the menu). |
jade update | Rebuild 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 devices | The 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 DEVICE | Sign a device out, by id, start of id or name. --all --account ID --yes does all of an account’s. |
jade delete-account ID --yes | Delete an account and all its data. |
jade master-key, jade check-key | Print the master key. Check that it opens the data. |
jade backup, jade restore FILE | Back up now (it also runs on a schedule). Put a backup back. |
jade models, jade code, jade images | Check 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 show | Check 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, andjade-proxywith 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.