Skip to content
OpenJevX wiki
Every statement on this page is cited and was checked against jev-cloud origin/main (10a744c), jevx HEAD (4a4722d), openjevx v0.5.9 (ee2a1f4) on 2026-10-04.

Upgrading to v0.5.9

This is a checklist for moving a server from v0.5.6 or older to v0.5.9. Work through each section that matches how you run OpenJevX. Every setting is also listed on Configuration.

1. Decisions need an API key off loopback

Section titled “1. Decisions need an API key off loopback”
  • The key is api_key in openjevx.json, or the OPENJEVX_API_KEY environment variable. 1
  • It guards POST /v1/systemone, sent as Authorization: Bearer <key>, and must be 16+ characters. 2
  • An API key shorter than 16 characters is an error that asks you to use at least 16. 3 4
  • The key is on whenever listen is not loopback; it is off on 127.0.0.1, ::1 and localhost unless you set one. 2
  • The environment wins over openjevx.json. 5
  • Left unset on a public listen address, the server generates one into openjevx.api-key beside openjevx.json. 2
  • A request without the right key gets 401 with the body {"error":"missing or wrong API key"}. 6
  • allow_no_api_key (OPENJEVX_ALLOW_NO_API_KEY=1) turns the key off even when public, e.g. behind a proxy that checks it. 7

Clients send the key as Authorization: Bearer <key>, the header jevx and the jev-cloud gate send. 8

Terminal window
curl -H "Authorization: Bearer $(cat openjevx.api-key)" http://<host>:21118/v1/systemone -d @body.json

With an API key (any server not on loopback), let jevx read it from the environment. 9

Terminal window
jevx profile add openjevx http://<host>:21118/v1/systemone --model openjevx --header 'Authorization: Bearer $OPENJEVX_API_KEY'

Request and response shapes are on the API page.

2. The dashboard password

Section titled “2. The dashboard password”
  • There is no default password. 10
  • The password guards the dashboard /, /stats, /metrics and /recipes with HTTP Basic, and any user name works. 11
  • Set "password" in openjevx.json or OPENJEVX_PASSWORD; unset, the server generates one on its first start and keeps it in openjevx.password. 12
  • The npx install keeps it in ~/.local/share/openjevx/. 13
  • adminadmin shipped in openjevx.json up to v0.5.6; it is public, so the server counts it as no password. 14
  • An old adminadmin is ignored and replaced by a generated password. 15
  • A generated value is shown once, and only on a terminal. 16
  • Logs (Docker, systemd, ECS) get the file and a fingerprint, never the secret. 17

3. The npx installer keeps your config

Section titled “3. The npx installer keeps your config”
  • Archives up to v0.5.6 carried an openjevx.json (with the password “adminadmin”) that replaced the user’s on every upgrade. 18
  • Releases no longer ship one; the user’s file is still put back after unpacking, whatever the archive holds. 18
  • On install and upgrade the user’s values always win; only keys the user does not have yet are added. 19
  • The keys it adds are listen (127.0.0.1:21118) and device (auto). 20
  • Release archives carry no openjevx.json, so unpacking a new release over an old one never replaces yours. 21

4. Docker

Section titled “4. Docker”
  • The image refuses to start without OPENJEVX_PASSWORD and OPENJEVX_API_KEY, or your own openjevx.json mounted at /data/openjevx.json. 22
  • The Docker image refuses to start without OPENJEVX_PASSWORD (12+ characters) and OPENJEVX_API_KEY (16+). 23
  • The image runs as uid 10001, not root, and /data is its writable working folder. 24
  • /data holds the generated openjevx.json, any generated credential files and the model cache; /app is read-only to it. 25
  • Make a key with openssl rand -hex 24. 26
Terminal window
docker run -d -p 127.0.0.1:21118:21118 \
  -e OPENJEVX_PASSWORD=YOUR_PASSWORD -e OPENJEVX_API_KEY=YOUR_API_KEY \
  ghcr.io/deemwar-products/openjevx:v0.5.9

Marketplace image on 0.5.6

Section titled “Marketplace image on 0.5.6”
  • The jev-cloud image pins OPENJEVX_TAG=v0.5.6. 27
  • The container product is built in the jev-cloud repo, not from the openjevx Dockerfile. 28
  • Its gate checks Authorization: Bearer <JEV_API_KEY> and runs openjevx on 127.0.0.1:21119, where openjevx’s own key is off. 29
  • Because the gate runs openjevx on 127.0.0.1:21119 and checks the key in front, the API-key change needs no action; verify the loopback bind in the startup log. 30

5. Clear the jevx answer cache

Section titled “5. Clear the jevx answer cache”
  • jevx caches answers by model name, so run jevx cache clear after upgrading, or give the profile a versioned model name such as --model openjevx-v0.5.2. 31
  • A stored answer is used for cache_ttl_days (default 7). 32

6. Platforms

Section titled “6. Platforms”
  • Server archives are released for macOS on Apple Silicon, Linux amd64 and arm64 (glibc 2.28+), and Windows amd64. 33
  • The linux-arm64 archive is packed with the aarch64 ONNX Runtime library. 34
  • On an Intel Mac the installer stops with an error: ONNX Runtime 1.29 has no Intel macOS build, so OpenJevX runs on Apple Silicon only (or use Docker). 35

If a step fails, see Troubleshooting.

Sources

Section titled “Sources”

Footnotes

Section titled “Footnotes”

  1. openjevx @ v0.5.9 (ee2a1f4) · README.md L29–31 ↩

  2. openjevx @ v0.5.9 (ee2a1f4) · README.md L31 ↩ ↩2 ↩3

  3. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L33 ↩

  4. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L75–78 ↩

  5. openjevx @ v0.5.9 (ee2a1f4) · README.md L36 ↩

  6. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L181–186 ↩

  7. openjevx @ v0.5.9 (ee2a1f4) · README.md L33 ↩

  8. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L22 ↩

  9. openjevx @ v0.5.9 (ee2a1f4) · README.md L182 ↩

  10. openjevx @ v0.5.9 (ee2a1f4) · README.md L202 ↩

  11. openjevx @ v0.5.9 (ee2a1f4) · README.md L32 ↩

  12. openjevx @ v0.5.9 (ee2a1f4) · README.md L202–204 ↩

  13. openjevx @ v0.5.9 (ee2a1f4) · README.md L203–204 ↩

  14. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L34–35 ↩

  15. openjevx @ v0.5.9 (ee2a1f4) · README.md L42–43 ↩

  16. openjevx @ v0.5.9 (ee2a1f4) · README.md L38–39 ↩

  17. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L28–29 ↩

  18. openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L54–55 ↩ ↩2

  19. openjevx @ v0.5.9 (ee2a1f4) · bin/config.js L1 ↩

  20. openjevx @ v0.5.9 (ee2a1f4) · bin/config.js L2 ↩

  21. openjevx @ v0.5.9 (ee2a1f4) · README.md L40–41 ↩

  22. openjevx @ v0.5.9 (ee2a1f4) · README.md L169–170 ↩

  23. openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L21–22 ↩

  24. openjevx @ v0.5.9 (ee2a1f4) · README.md L170–171 ↩

  25. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L21–22 ↩

  26. openjevx @ v0.5.9 (ee2a1f4) · README.md L169–171 ↩

  27. jev-cloud @ origin/main (10a744c) · image/Dockerfile L4 ↩

  28. openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L85 ↩

  29. openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L86–87 ↩

  30. jev-cloud @ origin/main (10a744c) · docs/upgrade-openjevx-0.5.7-plan.md L10 ↩

  31. openjevx @ v0.5.9 (ee2a1f4) · README.md L188 ↩

  32. jevx @ 4a4722d (4a4722d) · site/src/content/docs/reference/privacy.md L34 ↩

  33. openjevx @ v0.5.9 (ee2a1f4) · bin/platform.js L1–2 ↩

  34. openjevx @ v0.5.9 (ee2a1f4) · scripts/package.sh L43 ↩

  35. openjevx @ v0.5.9 (ee2a1f4) · bin/platform.js L8–11 ↩