Self-hosting Enjazy
This guide describes how to deploy the Enjazy server on your own machine. It covers the requirements, installing and running the server, Docker, HTTPS and reverse proxying, e-mail, first-run setup, the AI assistant, backups, migrating a 1.x server, and the database CLI.
For the console itself see the admin guide.
Requirements
- Node.js 24 (
>=24.13.0 <25). - npm 11.7.0 or newer.
- A writable data directory. The defaults are all under
./data/in the server working directory. - A public URL (for accounts mode) that the server can validate on first run.
Install and run
Download the server archive (enjazy-server-<version>.zip) from the Enjazy download page and extract it. The archive holds the built server (apps/server/dist/, with the web app and the documentation inside), the Dockerfile (apps/server/Dockerfile) and a README.txt. From the extracted folder, start the server with:
node apps/server/dist/server.mjs
The server serves the API, the server-rendered pages, the admin console (/console/), the same-origin web app, this documentation (/docs/), the API reference (/docs/api) and the OpenAPI document (/docs/json). It keeps its data under ./data/ in the folder you start it from, unless the variables below say otherwise.
To build the archive's contents from a source checkout instead, run npm run build:server; the bundle is then apps/server/dist/server.mjs.
Docker
Build the image from the extracted archive and run it:
docker build -t enjazy-server -f apps/server/Dockerfile .
docker run -p 8787:8787 -v enjazy-data:/data enjazy-server
The image is based on node:24-slim, runs as a non-root user, exposes port 8787, and mounts a volume at /data for the database and per-user stores. The environment defaults inside the image point the data files at /data.
Environment variables
Every variable the server reads is listed below, with its default. Nothing else is configuration. Product constants (lockout windows, link lifetimes, retention) are not environment-configurable.
| Variable | Default | Purpose |
|---|---|---|
ENJAZY_HOST | 0.0.0.0 | The interface the HTTP server binds to. |
ENJAZY_PORT | 8787 | The TCP port the HTTP server listens on. |
ENJAZY_AUTH | none | Auth mode: none, api-key or accounts (truthy 1.x values map to accounts). |
ENJAZY_API_KEYS | (empty — no API keys) | A comma-separated list of API keys for single-tenant api-key mode. |
ENJAZY_API_KEYS_SYNC | false | In api-key mode, true puts the API-key guard on the sync channel /api/sync/* too (no or wrong key answers 401 unauthorized). Off keeps sync public so 1.x apps keep syncing, and the server logs the api_key_sync_public boot warning. Turn it on once every app that syncs with the server sends a key. |
ENJAZY_DB_DRIVER | sqlite | The single-tenant store driver: sqlite or mysql. |
ENJAZY_DB | ./data/enjazy-server.db | The single-tenant SQLite database path. |
ENJAZY_MYSQL_HOST | 127.0.0.1 | The MySQL host when ENJAZY_DB_DRIVER=mysql. |
ENJAZY_MYSQL_PORT | 3306 | The MySQL port. |
ENJAZY_MYSQL_USER | enjazy_user | The MySQL user. |
ENJAZY_MYSQL_PASSWORD | (empty) | The MySQL password. |
ENJAZY_MYSQL_PASSWORD_FILE | unset | A file whose content (without its final line ending) is the MySQL password; ENJAZY_MYSQL_PASSWORD wins when both are set. |
ENJAZY_MYSQL_DATABASE | enjazy_db | The MySQL database name. |
ENJAZY_MYSQL_TLS_CA | unset | A PEM CA used for the MySQL TLS connection. |
ENJAZY_MYSQL_TLS_REJECT_UNAUTHORIZED | true | Whether to verify the MySQL server certificate. |
ENJAZY_AUTH_DB | ./data/auth.db | The auth/control database path in accounts mode. |
ENJAZY_USERS_DIR | ./data/users | The per-user store directory in accounts mode. |
ENJAZY_ISSUER | unset | The public issuer URL ({issuer}) used in links and e-mails. |
ENJAZY_SITE_ORIGIN | unset | Online only: the public website and /console origin. Defaults to http://localhost:<port> on Online; its app/issuer defaults to the. plus this hostname, with the same scheme and port. Ignored by the self-hosted composition root. |
ENJAZY_CORS | * | The CORS allow-list; unset, blank or * reflects any origin. |
ENJAZY_TLS_CERT | unset | A TLS certificate file to enable the built-in HTTPS listener. |
ENJAZY_TLS_KEY | unset | The TLS key file for the built-in HTTPS listener. |
ENJAZY_HTTP_PORT | unset | An optional cleartext companion port alongside built-in TLS. |
ENJAZY_TRUST_PROXY | loopback | Which proxies' X-Forwarded-* headers are trusted: none, loopback, or a list of addresses. |
ENJAZY_ADMIN_USER | unset | The first-run admin username. |
ENJAZY_ADMIN_EMAIL | unset | The first-run admin e-mail. |
ENJAZY_ADMIN_PASSWORD | unset | The first-run admin password. |
ENJAZY_ADMIN_PASSWORD_FILE | unset | A file whose content (without its final line ending) is the first-run admin password; ENJAZY_ADMIN_PASSWORD wins when both are set. |
ENJAZY_SIGNUPS | false | Whether self-service sign-up is enabled. |
ENJAZY_SETUP_SKIP_VALIDATION | false | Skips the first-run public-URL validation. |
ENJAZY_PLAN_GATES | off | Plan gates: off, legacy or all. |
ENJAZY_SMTP_URL | unset | A full SMTP connection URL. |
ENJAZY_SMTP_HOST | unset | The SMTP host (used when ENJAZY_SMTP_URL is unset). |
ENJAZY_SMTP_PORT | 587 | The SMTP port. |
ENJAZY_SMTP_USER | unset | The SMTP user name. |
ENJAZY_SMTP_PASSWORD | unset | The SMTP password. |
ENJAZY_SMTP_PASSWORD_FILE | unset | A file whose content (without its final line ending) is the SMTP password; ENJAZY_SMTP_PASSWORD wins when both are set. The setup wizard writes this one. |
ENJAZY_SMTP_SECURE | false | Whether SMTP uses a secure connection. |
ENJAZY_MAIL_FROM | unset | The sender address; unset derives no-reply@<public host>. |
ENJAZY_MAIL_FROM_NAME | unset | The sender name; unset uses the public host on a self-hosted server. |
ENJAZY_MAIL_TRANSPORT | smtp when ENJAZY_SMTP_URL or ENJAZY_SMTP_HOST is set; otherwise file in development and none in production | The mail transport override: smtp, file or none. |
ENJAZY_SUPPORT_EMAIL | unset | The support e-mail published in the public config. |
ENJAZY_DEVICE_LICENCE_SALES | false | Enjazy Online only: true sells the lifetime Desktop + Mobile licence at Checkout. Off by default (the Desktop and Mobile apps are free; Checkout refuses device). A self-hosted server ignores it. |
ENJAZY_SALES_EMAIL | info@roaa.tech | Enjazy Online only: the inbox that receives the Business "Contact us" requests from the website's pricing page (one e-mail per request, through the mail outbox). One address. A self-hosted server has no such form. |
ENJAZY_WEB_APP_ORIGIN | unset | The public origin used in copied links behind a rewriting proxy. |
ENJAZY_PRIVACY_URL | unset | The target of /privacy; unset renders the family 404. |
ENJAZY_TERMS_URL | unset | The target of /terms; unset renders the family 404. |
ENJAZY_HELP_URL | unset | The target of /help; unset renders the family 404. |
ENJAZY_STATUS_URL | unset | The status link published in the public config. |
ENJAZY_LOG_LEVEL | info | The pino log level: fatal, error, warn, info, debug, trace or silent. |
ENJAZY_SAAS_URL | unset | The Enjazy Online URL used by clients, and where a Free server buys Pro (unset: https://the.enjazy.app). A server key names its own issuer, so a key does not need it. |
ENJAZY_LICENSE_KEY | unset | A signed server key (esk1.…) from Enjazy Online. It wins over a key installed on the admin Licence page, which then shows it read-only. Old esl_ keys are not accepted. |
ENJAZY_LICENSE_OWNER_TOKEN | unset | Retired: ignored. When it is set the server logs licence.owner_token_ignored at boot and the Licence page says so. Use a server key. |
ENJAZY_LICENCE_ROOT_KEY_FILE | unset | Enjazy Online only: the licence root private key file (Ed25519 JWK) that signs server keys and server licences. Keep it secret and outside the repository. A release build without it cannot create server keys. |
ENJAZY_PLANS_DB | ./data/saas/plans.db | The plans catalogue database path. |
ENJAZY_SERVER_LICENSES_DB | ./data/saas/server-licenses.db | The server licence keys database path. |
ENJAZY_CLIENT_LICENSES_DB | ./data/saas/client-licenses.db | The client licence keys database path. |
ENJAZY_PLAN_SUBSCRIPTIONS_DB | ./data/saas/plan-subscriptions.db | The subscriptions database path. |
ENJAZY_TRIAL_DAYS | 14 | Enjazy Online only: the days of the free Business trial each new account gets (counted only while it is the plan in force, after the sign-up offer); 0 turns it off. A self-hosted server has no trial. |
ENJAZY_SIGNUP_PROMO_MONTHS | 4 | Enjazy Online only: the sign-up offer of each new account in months of 30 days (counted only while it is the plan in force, before the trial); 0 turns it off. A self-hosted server has no offer. |
ENJAZY_REQUIRE_VERIFIED_EMAIL | false (Enjazy Online: true) | When true, an account must confirm its e-mail address before it can use a paid plan or share lists. Turn it on only when mail delivery works (ENJAZY_SMTP_URL or ENJAZY_SMTP_HOST), so people get the confirmation link. Administrators can mark an address verified in the console. |
ENJAZY_REFERRALS | true | Enjazy Online only: invite codes and their rewards; false turns the program off. A self-hosted server has no invite program. |
ENJAZY_STRIPE_SECRET_KEY_FILE | unset | Enjazy Online only: the file holding the Stripe secret key. With the two settings below it turns billing on; a self-hosted server ignores it. |
ENJAZY_STRIPE_WEBHOOK_SECRET_FILE | unset | Enjazy Online only: the file holding the Stripe webhook signing secret (whsec_…). |
ENJAZY_STRIPE_PRICES | unset | Enjazy Online only: the Stripe price ids, plan:interval=price_id, comma-separated (plans pro, team, business; intervals month, year). |
ENJAZY_STRIPE_AUTOMATIC_TAX | false | Enjazy Online only: Stripe Tax calculates tax at Checkout. |
ENJAZY_STRIPE_SUCCESS_URL | <web app>/settings/plan | Enjazy Online only: where Stripe Checkout returns after a payment. |
ENJAZY_STRIPE_CANCEL_URL | <web app>/settings/plan | Enjazy Online only: where Checkout returns when abandoned, and where the billing portal returns. |
ENJAZY_WEBHOOKS | (empty — no webhooks) | The operator-configured webhook URLs. |
ENJAZY_WEBHOOK_SECRET | unset | The HMAC secret for webhook signing. |
ENJAZY_WEBHOOK_POLL_MS | 1000 | The webhook poll interval in milliseconds. |
ENJAZY_TEST_MYSQL_URL | unset | A MySQL URL used by tests only. |
ENJAZY_AI_PROVIDER | unset | The AI provider type: openai (OpenAI-compatible) or anthropic (Anthropic-compatible). See AI assistant. |
ENJAZY_AI_BASE_URL | unset | The provider's base URL, for example https://api.deepseek.com. |
ENJAZY_AI_MODEL | unset | The provider's model id, for example deepseek-chat. |
ENJAZY_AI_KEY_FILE | unset | A file whose whole content (trimmed) is the provider API key. The key itself is never an environment value. |
ENJAZY_AI_TIMEOUT_MS | 30000 | The time limit of one provider request in milliseconds, kept within 1000–120000. |
ENJAZY_AI_MAX_TOKENS | 1024 | The most tokens the provider may write in one answer, kept within 64–8192. |
ENJAZY_PUSH_CONTACT | unset (falls back to mailto: + ENJAZY_SUPPORT_EMAIL, then an https:// ENJAZY_ISSUER) | The operator contact sent to browser push services with every web push reminder (VAPID sub): mailto:you@example.com or an https:// URL. |
ENJAZY_PUSH_VAPID_FILE | push-vapid.json in the data directory | The VAPID key file of web push reminders. Created at first start when missing; keep it with your backups. |
ENJAZY_ENV | unset | Set to production (or set NODE_ENV=production) to enable production behaviour. |
NODE_ENV | unset | Set to production to enable the same production behaviour as ENJAZY_ENV=production. |
ENJAZY_STRIPE_SERVER_PRICES | unset | Enjazy Online only: Server Pro prices, month=price_…, year=price_… (recurring) and lifetime=price_… (paid once, the lifetime server licence), comma-separated and distinct from the Online prices. Unset disables server purchases. Use Stripe test-mode prices until the owner configures the live account. |
In development the file transport writes e-mails as .eml files to the data directory's outbox/; in production without SMTP configured, mail is off until the admin provides the mail configuration.
Server licence
A self-hosted server unlocks Server Pro with a server key issued by Enjazy Online (Subscriptions → Server keys). Install it in one of two ways:
- Admin console. Open Settings → Server license, paste the key and choose Install. The key is saved in the data directory (
server-licence.key, readable only by the server's user) and takes effect at once, without a restart. - Settings file. Set
ENJAZY_LICENSE_KEY. It wins over a key installed in the console, and the console shows it read-only.
The key names the Enjazy Online that issued it, and the server checks it offline against the Enjazy licence root key built into the server, so a forged or altered key is refused before anything is sent. Keys in the old esl_ format no longer work: ask for a new server key.
Server ID, checks and one key per server
- Server ID. On first start the server creates its identity key pair in the data directory (
server-identity.key, readable only by the server's user). The secret half never leaves the machine. The fingerprint of the public half is the server ID, shown on the Licence page next to the plan; you never type it anywhere. Back up the data directory with this file: a new data directory is a new server ID. Deleting the file makes a new ID, and the key must then be detached from the old ID or released by support. - Buying Pro. On a Free server, Settings → Server license → Upgrade to Pro opens the Enjazy payment page in a new tab with this server's ID and the signed-in admin's e-mail. Choose monthly or yearly Server Pro, or the lifetime licence, paid once. After payment the key appears on screen and in an e-mail to that address, and the server fetches it by its ID within five minutes and switches to Pro by itself.
- Lifetime licence. A lifetime server key gives the same features as Server Pro, never expires and includes updates. It has no subscription, so there is no renewal and no Manage subscription; it is still one key for one server, and moving it works as below. Lifetime purchases are final.
- Checks. Every check is a challenge-response: Enjazy Online sends a one-time value and the server signs it with its identity key, so a licence or key copied to another server does not work there. The server checks hourly, and every five minutes while a purchase, a renewal or a detach is in progress. Enjazy Online keeps only the server ID (its public key), the key and the time of the last successful check.
- Renewal. Stripe can confirm a renewal a few minutes after the paid period ends. While the subscription is set to renew, the server checks at the end of the period and stays on Pro: Enjazy Online gives it a short licence until it sees the renewal, and the server checks every five minutes. Once Enjazy Online sees the renewal, the server continues on Pro for the new period. If the subscription was cancelled, or a day passes after the period end without a renewal, the server drops to Free.
- Offline. If Enjazy Online cannot be reached the server stays on Pro until it reconnects or until the paid period ends, whichever comes first, and the Licence page warns while checks fail. The renewal day above applies only while the server reaches Enjazy Online: a server that cannot reach it at the period end drops to Free, and one that stops reaching it during that day drops to Free within ten minutes. Any change (cancelled, detached, moved, released) applies at the next successful check.
- One key, one server. A key locks to the first server that uses it. To move it, choose Detach licence on the old server, then install the key on the new one. If the old server has not checked in for more than a day, ask Enjazy support to release the key. A key used elsewhere, cancelled, released or past its paid period drops the server to Free with a warning.
- Owner token.
ENJAZY_LICENSE_OWNER_TOKENis retired and ignored (a boot warning,licence.owner_token_ignored). - Updating an older server. Update self-hosted servers before Enjazy Online switches to the new server licensing. Older servers keep their current licence until it expires (at most 30 days), then use Free until they update. The
ENJAZY_LICENSE_OWNER_TOKENsetting is no longer used; use a server key instead, and keepserver-identity.keyin the data folder: it is the server's identity.
HTTPS and reverse proxy
Two supported options:
- Built-in TLS. Set
ENJAZY_TLS_CERTandENJAZY_TLS_KEYto enable an HTTPS listener. Optionally setENJAZY_HTTP_PORTfor a cleartext companion port. - Reverse proxy. Terminate TLS at the proxy and forward to
ENJAZY_HOST:ENJAZY_PORT. SetENJAZY_TRUST_PROXYto the proxy addresses soX-Forwarded-*headers are trusted; without it every user behind the proxy shares one lockout IP (and one sign-up quota: 20 new accounts per IP per hour) andSecure/HSTS cannot be decided. SetENJAZY_WEB_APP_ORIGINwhen the proxy rewrites the public host, so copied links use the public origin. Passkeys work only on the server's own origins:ENJAZY_ISSUER,ENJAZY_WEB_APP_ORIGIN,ENJAZY_SITE_ORIGINand the origins listed inENJAZY_CORS; a passkey prompt opened from any other address fails. Proxy the WebSocket upgrade for/api/sync/ws.
Plain HTTP on a LAN host. The admin console sets its session cookies as Secure __Host- cookies, and the web app's sign-in, passkeys and two-step setup need a secure browser context. Browsers grant both only to https:// origins and to localhost / *.localhost names. On a plain-HTTP host such as http://server1.lan:8787 the admin sign-in loops back to the login page and those features fail in every browser; use the *.localhost development hosts from .env.example, or put HTTPS in front as described above.
The web app is always served same-origin by the server that hosts its API.
Web push reminders
Installed or open in a browser, the web app can receive task reminders while no Enjazy tab is open (Settings › Notifications › Push notifications, on the web only). The server sends them through the browser's push service (Google FCM for Chrome, Edge on some systems, Opera and Samsung Internet; Mozilla for Firefox; Microsoft WNS for Edge; Apple for Safari and web apps added to the Home Screen on iPhone and iPad).
- HTTPS is required. Browsers offer push only to a secure origin (
https://, orlocalhostwhile developing). See HTTPS and reverse proxy. - VAPID keys. At first start the server creates a P-256 key pair in
push-vapid.jsonin the data directory (readable only by the server's user), or uses the fileENJAZY_PUSH_VAPID_FILEnames. Back it up with the data directory. If the file is lost or replaced, every browser has to turn push notifications on again (the app re-subscribes on its next start). A file that exists but is not a valid key pair is never replaced: push stays off (push.vapid_invalidin the log) until you fix or remove it. - Contact. Set
ENJAZY_PUSH_CONTACTto amailto:address or anhttps://URL that push services can use to reach you. Without it the server usesENJAZY_SUPPORT_EMAIL, then anhttps://ENJAZY_ISSUER, and logspush.contact_missingat start when it has neither; Apple's push service refuses messages without a contact. - Outbound traffic. The server makes HTTPS requests to the push services above only (other hosts, IP addresses and non-HTTPS endpoints are refused), so allow outbound HTTPS to them from the server.
- What is sent. One message per reminder per browser: the task title and its due time, in the browser's app language, encrypted end to end to that browser (RFC 8291); never notes. A task whose every list is locked on that device is sent as "A task in a locked list", without its title. Each browser sends its time zone, its all-day reminder time, its "Remind me when a task is due" switch and the ids of the lists locked on it, so reminders fire at that device's wall time.
- Data. Subscriptions live in
push.dbin the data directory, created with the first subscription. A subscription ends when the browser turns push off, when its session signs out, when the account is deleted, or when the push service says it expired.
SMTP and e-mail
Set ENJAZY_SMTP_URL, or ENJAZY_SMTP_HOST with ENJAZY_SMTP_PORT, ENJAZY_SMTP_USER, ENJAZY_SMTP_PASSWORD and ENJAZY_SMTP_SECURE. The mail transport is smtp when SMTP is set, file in development, and none in production when unset. In development the file transport writes e-mails under the data directory's outbox/. Never use SMTP in automated runs.
First-run setup
In accounts mode the server validates the public URL before any database initialisation. Provide ENJAZY_ADMIN_USER, ENJAZY_ADMIN_EMAIL and ENJAZY_ADMIN_PASSWORD to seed the first admin, then sign in to the console at /console. Set ENJAZY_SETUP_SKIP_VALIDATION=1 only for local development behind *.localhost.
Setup in the browser
When the server starts with no .env or .env.local (or, with --instance=<name>, no .env.<name> pair) in its working folder or its data folder, no ENJAZY_* configuration variable in its environment and no completed setup (<data>/setup.json), it starts in setup mode instead. The variables a launcher always sets do not count: ENJAZY_HOST, ENJAZY_PORT, ENJAZY_DB, ENJAZY_AUTH_DB, ENJAZY_USERS_DIR (the Docker image's) and ENJAZY_ENV. Anything else boots exactly as before, so a headless or Docker install that passes its answers in the environment keeps the flow above.
In setup mode the server opens no database. It prints one line on standard output with the wizard address and a one-time setup code:
Enjazy setup: open http://localhost:8787/setup in a browser and enter the setup code XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
The code is shown only there, never written to a file or a log, and stops working when setup completes or the process exits. Five wrong codes from one address within 15 minutes block that address for the rest of the window. Every path other than the wizard answers 503 {"error":"setup_required"}; / and /console lead to /setup.
The wizard asks for the language, the code, the public address (checked with the same reachability test as above; Enjazy Online also shows the app host the.<address> and <address>/console), the data folder (shown, not asked: accounts mode keeps every account and its tasks in the built-in database there), e-mail (optional, with Send test email), the first administrator, and the optional AI provider (with Test connection) and, on Enjazy Online, Stripe. Save and start Enjazy writes .env in the data folder (the folder of ENJAZY_AUTH_DB: ./data by default, ./data/saas for Enjazy Online, /data in the Docker image), beside setup.json, with mode 0600. It puts every secret (the SMTP password, the AI key, the Stripe keys) in its own file under secrets/ in that folder, referenced by a *_FILE variable, seeds the administrator, writes setup.json and starts normally in the same process. It never replaces an existing .env, and a failed write leaves no partial file. AI configured this way stays off until Test connection succeeds in the admin console.
Every start reads the env files in this order, and a value already set is never replaced: exported variables, then the working folder's .env.local and .env, then the data folder's .env.local and .env. A recreated Docker container that keeps its /data volume therefore keeps the configuration the wizard wrote; back up the data folder as a whole.
If setup.json exists but its configuration is gone (no env file and no ENJAZY_* configuration variable sets ENJAZY_AUTH any more, or Enjazy Online no longer has the addresses setup saved), the server refuses to start and names the marker and the folders it looked in. It never falls back to open mode after setup. Restore the .env from the data folder backup, or pass the configuration in the environment.
The wizard always sets up accounts mode, which keeps sign-in accounts and each person's and share's tasks in SQLite files under the data folder, so it has no database choice. MySQL (ENJAZY_DB_DRIVER=mysql with the MySQL settings above, the password inline or in ENJAZY_MYSQL_PASSWORD_FILE) is for the shared-workspace modes without accounts (ENJAZY_AUTH=none or api-key); set it by hand in .env instead of running the wizard.
The wizard page is part of the admin build (npm run build:admin builds apps/admin/dist-setup; the release bundle carries it as public/setup).
AI assistant (bring your own key)
The AI assistant suggests sub-tasks and a priority for a task, summarizes the week, and plans a goal: a person describes what they want to plan and gets a plan of projects, lists, tasks and sub-tasks to choose from before anything is added. On a self-hosted server it runs with your own provider account and key. The app never holds the key: it calls this server, and the server calls the provider.
AI needs accounts mode (ENJAZY_AUTH=accounts), because every request is counted against a signed-in account. In none and api-key mode AI is always off.
AI is included on the server Free plan. No plan gates it.
When AI is on
AI is off until both of these are true:
- The provider type, base URL, model and key are all set.
- Test connection in the admin console (Settings → AI assistant) succeeded for exactly that configuration.
Any change of the provider type, base URL, model or key needs a new test. This includes a new key in the key file. Test connection must succeed for AI to be on: a failed test turns AI off. Changing the timeout, the maximum tokens or the daily limit does not need a new test. The admin guide describes the console section.
Once AI is on, a provider that is slow, unreachable or refuses a request does not turn it off. The person sees "Couldn’t reach the AI provider" with Try again, and the request is not counted. Only a change of the configuration or a failed Test connection turns AI off.
A model on your own machine
A local model (for example one served by llama.cpp or Ollama with an OpenAI- or Anthropic-compatible API) answers much more slowly than a hosted one. Set the AI timeout to 120000 ms (ENJAZY_AI_TIMEOUT_MS=120000, or 120 seconds in Settings → AI assistant), then run Test connection. A plan always gets up to 120 seconds, whatever the timeout, because a whole plan takes 25 seconds or more on a local model. If a reverse proxy sits in front of the server, let it wait at least as long for an answer (for example proxy_read_timeout 130s; in nginx). Otherwise the proxy gives up first.
Provider types
openai— an OpenAI-compatible chat completions API. The server sendsPOST {base URL}/chat/completionswith the key as a bearer token. DeepSeek works this way: base URLhttps://api.deepseek.com, model for exampledeepseek-chat.anthropic— an Anthropic-compatible messages API. The server sendsPOST {base URL}/v1/messageswith the key in thex-api-keyheader. A base URL that already ends in/v1is not doubled.
A trailing slash on the base URL is ignored.
The key
The key is never an environment value. Give it in one of two ways:
- Key file. Set
ENJAZY_AI_KEY_FILEto a file whose whole content is the key (surrounding spaces and line breaks are trimmed). Make the file readable only by the server's user. The server reads the file each time it needs the key; an unreadable or empty file counts as no key. - Admin console. Paste the key in Settings → AI assistant. It is write-only: no page or API shows it again. The server stores it sealed (AES-256-GCM, under a key derived from the server secret in the accounts database).
A key entered in the console wins over the key file. Remove it in the console to use the key file again.
Configuration
Set the provider with the AI variables in the environment table, in the admin console, or both. A value set in the console wins over the environment. Clearing a field in the console falls back to the environment value. The maximum tokens can only be set in the environment.
Each provider request has the timeout (default 30 seconds). A server error (5xx) or a network failure is retried once. A timeout is not retried.
Example settings. The key goes only in the key file, never in a settings file or the repository:
ENJAZY_AUTH=accounts
ENJAZY_AI_PROVIDER=openai
ENJAZY_AI_BASE_URL=https://api.deepseek.com
ENJAZY_AI_MODEL=deepseek-chat
ENJAZY_AI_KEY_FILE=/etc/enjazy/ai-key
Create the key file on Linux:
sudo install -m 600 -o enjazy -g enjazy /dev/null /etc/enjazy/ai-key
sudo nano /etc/enjazy/ai-key # paste the key, save
Use the user the server runs as in place of enjazy. In Docker the server runs as node: mount the key file read-only into the container and set ENJAZY_AI_KEY_FILE to its path there. Then restart the server, sign in to the admin console and choose Test connection.
Check a provider before you turn AI on
tools/ai-smoke.mjs checks a provider from a repository checkout (after npm ci), without starting the server. It sends one small sub-task request and one priority request through the server's own provider code (the same adapters, prompts and answer checks the server uses) and prints, for each, ok or the failure kind with the time it took. It never prints the key, the prompt or the provider's answer, and it stores nothing.
The key is read only from a file (--key-file); the tool refuses a key given on the command line. Each option falls back to the server's variable (ENJAZY_AI_PROVIDER, ENJAZY_AI_BASE_URL, ENJAZY_AI_MODEL, ENJAZY_AI_KEY_FILE, ENJAZY_AI_TIMEOUT_MS), so the server's own settings can be checked as they are.
Check DeepSeek (or any OpenAI-compatible provider):
node tools/ai-smoke.mjs --type openai --base-url https://api.deepseek.com --model deepseek-chat --key-file /etc/enjazy/ai-key
A working provider prints:
ai-smoke: openai-compatible · model deepseek-chat
subtasks ok 812 ms
priority ok 640 ms
For an Anthropic-compatible provider use --type anthropic and its base URL. The exit code is 0 when both requests are ok, 1 when one failed and 2 for a missing option or an unreadable or empty key file. A failure line names the gateway's kind and reason, for example priority failed unavailable (auth, HTTP 401) 95 ms:
| Reason | What to check |
|---|---|
auth | The key is refused: check the key file. |
not_found | Wrong base URL or model, or an address that is not http(s). |
rate_limited | The provider's rate limit or balance. |
http_5xx, network, timeout | The provider or the network; try again, or raise --timeout-ms. |
http_4xx, bad_response, invalid_output (kind failed) | The provider answered, but not as expected: check that the model follows instructions and can answer in JSON. |
The tool sends two real requests, which the provider may bill. They are not counted against any person's daily limit. After a successful check, turn AI on with Test connection in the admin console.
Daily limit
The administrator can set a daily limit per person in the admin console. The default is no limit. One successful request counts as one; a failed request is not counted. A plan counts as one request; Regenerate in the planner asks again and counts as another.
A plan is a longer answer than a sub-task suggestion. The server asks the provider for up to 4,096 output tokens for a plan (never more than 8,192, and never less than the maximum tokens you set). It waits up to 120 seconds for a plan, or longer than the timeout you set if that is longer, up to the same 120-second maximum. The count starts again at midnight UTC. When a person's requests for the day are used up, the app shows when they start again.
The AI usage section of the admin console (in Settings, below AI assistant) shows how many successful requests the server answered today and in the last 30 days, with the daily limit. It shows counts only. A failed or cancelled request is not counted.
Privacy
- The app sends a request only when the person presses an AI action, after allowing it in Settings → AI.
- A request carries only what the action needs: the task's title, notes, sub-task titles and due state, or, for the weekly summary, the week's done and overdue counts and the task titles.
- A plan request carries the goal the person typed (up to 2,000 characters), the optional finish-by date, today's date, weekday and time zone, the app language and the names of the person's lists and projects, so the plan can use them. It never carries a task title. The person can turn Use my list and project names off, and then no names are sent. The planner shows what will be sent before it asks.
- The app never sends tasks of a PIN-locked list or of a list inside a locked project, even while it is unlocked. The weekly summary leaves their titles out, and a plan request never names a locked list or project.
- The server never logs or stores prompts, task text, answers or the key. It stores only a daily request counter per account, and for the admin usage view a daily count per plan. Counters per account older than yesterday are deleted; counts per plan are kept for 30 days.
- There is no telemetry.
Endpoints and errors
GET /health on an accounts server includes "ai": {"available": true} or "ai": {"available": false}. A signed-in app asks GET /api/ai/status to know whether the Cloud provider can be chosen.
The app uses these endpoints. Each needs a signed-in account.
| Endpoint | Purpose |
|---|---|
POST /api/ai/subtasks | Suggests up to five sub-tasks for a task. |
POST /api/ai/priority | Suggests importance and urgency for a task, with a reason. |
POST /api/ai/summary | Summarizes the week. |
POST /api/ai/plan | Plans a goal: up to 3 new projects, 6 new lists and 40 tasks, nested at most three levels, with priorities and dates between today and two years ahead. The server checks the answer and drops what does not fit. |
GET /api/ai/status | Whether AI is on, and the person's limit, use and reset time today. |
A request must carry consent: true; without it the server answers 400 invalid_body and sends nothing to the provider. The AI errors are:
| Code | Status | Meaning |
|---|---|---|
ai_quota | 429 | The daily limit is used up. resetsAt gives the next midnight UTC. |
ai_unavailable | 503 | AI is not on here: no accounts mode, the provider is not set up, or Test connection has not succeeded for this configuration. |
ai_provider_unavailable | 502 | AI is on, but the provider did not answer or refused now. retryable is true for a timeout, a network failure, a provider server error or a rate limit, and false for a refused key or a wrong model or URL (fix the provider settings). |
ai_failed | 502 | The provider refused this request for another reason, or its answer could not be read. |
Backups
Back up the data directory: in accounts mode this holds auth.db, users/, setup.json and outbox/; in every mode it also holds push-vapid.json (and push.db once a browser turned push notifications on). Restore by placing the files back while the server is stopped. Backups contain user data, never the PIN hash, credentials or device-local state.
Enjazy desktop apps on your team's computers
For administrators who install the Enjazy desktop app for their users:
- Where Windows setup installs. Per user, in
%LOCALAPPDATA%\Programs\Enjazy, with one Start-menu shortcut named Enjazy (no folder, no Uninstall shortcut: users uninstall from Settings › Apps) and the Apps & features name Enjazy (إنجازي when setup runs in Arabic). If another program's shortcut already has the name (the earlier Enjazy 1.x), the shortcut is named Enjazy (new) until the name is free; setup never overwrites or deletes a shortcut that starts another program. - Upgrades from earlier builds. Setup moves an earlier install of this app from the folder older builds used under
%LOCALAPPDATA%: it removes the old program files and the old shortcuts that start the old copy, puts the new shortcuts in their place (a desktop shortcut only if there was one), moves the autostart entry and registersenjazy://for the new copy. It does this with/S,/Pand/UPDATEtoo, and also when the old folder was already deleted by hand. The data folders below stay where they are. - Windows setup switches.
/Sinstalls silently for the current user and adds the desktop shortcut;/NSleaves the shortcut out;/Pshows progress only. Setup never starts the app in these modes. An interactive setup ends with Run Enjazy and Create a desktop shortcut. If the app is running, setup asks the user to quit it; a silent setup waits about ten seconds, then exits with code 5 and changes nothing. - Autostart. The app's entry under
HKCU\Software\Microsoft\Windows\CurrentVersion\Runis namedtech.roaa.enjazy2; Task Manager lists it as Enjazy. Enjazy 1.x keeps its own entry, namedEnjazy. - Windows uninstall switches. The app's
uninstall.exe /S(theQuietUninstallStringof its Apps & features entry) removes the app and keeps the user's data; add/DELETEDATAto delete it too./UPDATEnever deletes data. Quit the app first: a running copy keeps its files open. - Where the desktop app keeps data. Windows:
%APPDATA%\tech.roaa.enjazy2(the local store, attachments and settings) and%LOCALAPPDATA%\tech.roaa.enjazy2(the WebView2 profile, caches and the notification icon). Linux:~/.config/tech.roaa.enjazy2(store, attachments, settings),~/.local/share/tech.roaa.enjazy2(WebKitGTK data) and~/.cache/tech.roaa.enjazy2if present. Enjazy 1.x keeps its data undertech.roaa.enjazyand is never touched. - Linux packages (.deb, .rpm, AppImage) ask nothing on install or removal;
apt remove enjazyordnf remove enjazyleaves the data folders above in place.
Migrating a 1.x server
migrate-v1 migrates a 1.x server into a new database, never in place and never without a backup copy:
npm run -w @enjazy/server migrate-v1 -- --from <1.x data dir or MySQL URL> --to <new data dir> [--dry-run]
Run the dry run first; it reports the count of each mapping. Accounts, password hashes, two-step, passkeys, shares, invitations, plans, subscriptions and keys are carried.
Database CLI
npm run -w @enjazy/server db -- status
npm run -w @enjazy/server db -- up
npm run -w @enjazy/server db -- down
status reports the current schema, up applies the forward-only ladder, and down restores the pre-upgrade backup copy instead of running destructive down migrations.
Self-hosted bundles serve the app at / and the console at /console; they do not include the public website. Old /admin links redirect permanently to /console.
The setup wizard preserves the SMTP encryption choice. For a host/port SMTP configuration, ENJAZY_SMTP_REQUIRE_TLS=true requires STARTTLS for normal delivery; implicit TLS uses ENJAZY_SMTP_SECURE=true. Existing configurations keep their defaults when the new variable is absent.