Skip to content
OpenJevX wiki
Every statement on this page is cited and was checked against openjevx v0.5.9 (ee2a1f4) on 2026-10-04.

Configuration

Where the config file is read from

Section titled “Where the config file is read from”

The config paths are openjevx.json (relative, so the working directory) and then openjevx.json in the executable’s folder. 1

The server loops over those paths and stops at the first file that it can read and that parses as JSON. 2

With no file, listen is 127.0.0.1:21118 and device is auto. 3

A configured model path is checked with os.Stat exactly as written. 4

Keys

Section titled “Keys”
openjevx.json key env / flag default what it does
listen — 127.0.0.1:21118 address and port the HTTP server binds; a non-loopback address turns the API key on 5 3 6 7 8
device -device, OPENJEVX_DEVICE auto auto, cpu or gpu; any other value becomes auto 9 10 11 12
api_key OPENJEVX_API_KEY on when listen is not loopback: generated into openjevx.api-key; off on 127.0.0.1, ::1 and localhost unless set key for POST /v1/systemone, sent as Authorization: Bearer <key> (16+ characters) 8
password OPENJEVX_PASSWORD always on: generated into openjevx.password dashboard /, /stats, /metrics and /recipes password (HTTP Basic, any user name) 13
allow_no_api_key OPENJEVX_ALLOW_NO_API_KEY=1 off turns the key off even when public, e.g. behind a proxy that checks it 14
allow_no_password OPENJEVX_ALLOW_NO_PASSWORD=1 off turns the dashboard password off 15
model -model, OPENJEVX_MODEL model/, models/openjevx/, then openjevx.w8.onnx next to the executable model folder, .onnx file, or s3://bucket/prefix/ (or .tar.gz) 16 17 18 19
runtime OPENJEVX_ORT libonnxruntime.so, libonnxruntime.dylib or onnxruntime.dll next to the executable path to the ONNX Runtime library 20
threads OPENJEVX_THREADS auto-detected (see below) CPU threads one request uses 21
model_sha256 OPENJEVX_MODEL_SHA256 none pin: sha256 of the .tar.gz, or of the folder’s openjevx.w8.onnx 22
model_cache OPENJEVX_MODEL_CACHE user cache dir/openjevx/models, else $TMPDIR/openjevx-models where downloads live 23
model_reload OPENJEVX_MODEL_RELOAD off check the ETag this often (5m; at least 10s) 24
model_fallback OPENJEVX_MODEL_FALLBACK the model/ lookup next to the executable served while the bucket holds no model yet 25
model_s3_path_style AWS_S3_USE_PATH_STYLE=true false bucket in the path, not the host name: MinIO, Ceph, R2 26

The model_* keys are for remote models, where model is an s3:// URL. 27

See Model from object storage.

Override order

Section titled “Override order”

Flags and environment override the file: -model / OPENJEVX_MODEL, -device / OPENJEVX_DEVICE, threads / OPENJEVX_THREADS. 7

For model and device the order is flag, then environment, then openjevx.json, then the default model location. 28

If OPENJEVX_MODEL_SHA256, OPENJEVX_MODEL_CACHE, OPENJEVX_MODEL_RELOAD, OPENJEVX_MODEL_FALLBACK or OPENJEVX_THREADS is not empty, its value overwrites the config value. 29

For api_key and password, the environment wins over openjevx.json. 30 31

OPENJEVX_THREADS must be a whole number, 1 or more, or the server stops at startup. 32

runtime is the exception: path := cfg.Runtime comes first, and OPENJEVX_ORT is read only if that path is empty, so here the file beats the environment. 33

AWS_S3_USE_PATH_STYLE is read without regard to case: true or 1 turns path style on; empty, false and 0 set nothing; any other value is an error. 34

The server passes model_s3_path_style to the S3 source as PathStyle. 35 36 AWS_S3_USE_PATH_STYLE=false (or 0) sets nothing, so it does not turn a true off; only true or 1 sets PathStyle. 37

main defines the flags -help, -model and -device. 38

Credentials

Section titled “Credentials”

Generated files are created once with mode 0600 and reused. 31 They go beside openjevx.json (or beside the executable when there is none), else in $OPENJEVX_DATA, else the working folder, whichever is writable, so a config mounted read-only still starts. 39 A start that creates one shows the value once, and only on a terminal. 40 When stderr is a log (Docker, systemd, ECS, CloudWatch), it logs the file and a fingerprint (sha256 ...37dd), never the secret, so read it from the file. 41 With a password in use, every start logs where it came from, as dashboard password: from <source>. 42 A created credential file holds 26 random letters and digits (128 bits). 43 An API key shorter than 16 characters fails startup with use at least 16. 44 45 46 The old published password adminadmin (in openjevx.json up to v0.5.6) is ignored and replaced by a generated one. 47

How the key and password are checked is on the API reference page.

Device

Section titled “Device”

auto uses the first GPU provider that loads (CUDA, CoreML on macOS, DirectML on Windows) and whose answers match the CPU on a probe, otherwise CPU. 48

gpu refuses to start unless one of them loads. 48

The startup error is device gpu was set and no GPU provider ran the model. 49

A GPU provider is rejected if its logits differ from the CPU’s by more than 0.25 on the probe. 50 51

Threads

Section titled “Threads”

threads (or OPENJEVX_THREADS, which wins) is the CPU threads one request uses. 52

Unset, the server first takes the cgroup CPU quota (/sys/fs/cgroup/cpu.max, or v1 cpu.cfs_quota_us / cpu.cfs_period_us), rounded up. 53

With no quota, on ECS / Fargate it takes the task’s Limits.CPU from the task metadata endpoint, else the container’s. 21

Otherwise it uses GOMAXPROCS. 54

The ECS step applies when ECS_CONTAINER_METADATA_URI_V4 is set, with a 1 s timeout. 55

The thread count is never more than NumCPU and never below 1. 56 57

The server logs the choice at startup, for example threads: intra-op 1 (from ecs), GOMAXPROCS 2, NumCPU 2; the source is config, env, cgroup, ecs or GOMAXPROCS. 58

On Linux a second line names the CPU and its SIMD flags. 59

Fargate limits CPU with shares that neither the quota nor Go can see, so a 1 vCPU task reports 2 CPUs; running 2 threads there was 4x slower. 60 The ECS step is there for Fargate, which limits CPU with shares that neither the cgroup quota nor Go can see. 61

On x86, AVX2-only hosts are about 2x slower than AVX-512 VNNI ones, and Fargate hands out both. 62 The x86 latency report measured model 0.5.2 on ONNX Runtime 1.29.0 CPU. 63

Telemetry

Section titled “Telemetry”

The server turns ONNX Runtime’s telemetry off (ORT_DISABLE_TELEMETRY=1 unless you set it). 64

In code, it sets ORT_DISABLE_TELEMETRY=1 before creating the ONNX Runtime environment when the variable is unset, and then calls DisableTelemetry. 65

ORT 1.29’s Linux build has telemetry on by default and crashed with SIGSEGV in distroless images; this fix shipped in server 0.5.3. 66

Docker

Section titled “Docker”

A prebuilt image is published for linux/amd64 and linux/arm64, for each release tag and latest. 67

Terminal window
docker run -d -p 127.0.0.1:21118:21118 \
  -e OPENJEVX_PASSWORD=<12+ characters> -e OPENJEVX_API_KEY=<16+ characters> \
  ghcr.io/deemwar-products/openjevx:v0.5.9

Or build it from source, with OPENJEVX_PASSWORD=<12+ characters> and OPENJEVX_API_KEY=<16+ characters>. 68

Terminal window
OPENJEVX_PASSWORD=<12+ characters> OPENJEVX_API_KEY=<16+ characters> docker compose up -d --build

Make a key with openssl rand -hex 24. 69

The image has no default credentials: it refuses to start without OPENJEVX_PASSWORD and OPENJEVX_API_KEY, or your own openjevx.json mounted at /data/openjevx.json. 70

The entrypoint checks them only when neither /app/openjevx.json nor /data/openjevx.json exists. 71

A shorter password stops the container with openjevx: OPENJEVX_PASSWORD must be at least 12 characters. 72

A shorter key stops it with openjevx: OPENJEVX_API_KEY must be at least 16 characters. 73

OPENJEVX_ALLOW_NO_API_KEY=1 skips the key check and opens the decision API on purpose, e.g. behind a proxy that checks the key. 74 75

When neither /app/openjevx.json nor /data/openjevx.json exists, the entrypoint writes /data/openjevx.json with "listen": "0.0.0.0:21118", "device": "cpu" and "model": "/app/model". 76 77

That file holds no credentials: the server reads both from the environment. 74 77

The container listens on 0.0.0.0; the api_key is on whenever the server listens beyond loopback. 77 78

The compose file publishes the port on 127.0.0.1:21118 only. 79

The runtime image is debian:bookworm-slim with ca-certificates and curl. 80

The build uses ONNX Runtime 1.29.0 and the model version in deploy/MODEL_VERSION. 81

/app/model is found next to /app/openjevx; mount another model folder there to swap models. 82

The image exposes 21118 and has a health check: curl -fsS http://127.0.0.1:21118/health every 30 s, 3 s timeout, 60 s start period. 83

The image runs as uid 10001, never root. 84 85

/app (binary, runtime, model) is read-only to that user; /data is its working folder for the generated openjevx.json, any generated credential files and the model cache. 86

Your own openjevx.json can be mounted at /data/openjevx.json or read-only at /app/openjevx.json. 87 Credentials the image has to generate go to /data (OPENJEVX_DATA), and the logs show only their file and a fingerprint, never the value. 88 89

Sources

Section titled “Sources”

Footnotes

Section titled “Footnotes”

  1. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L474–477 ↩

  2. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L449–457 ↩

  3. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L447–448 ↩ ↩2

  4. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/model.go L57–62 ↩

  5. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L33 ↩

  6. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L209–210 ↩

  7. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L580–582 ↩ ↩2

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

  9. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L56 ↩

  10. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L69–73 ↩

  11. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L448 ↩

  12. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L466–472 ↩

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

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

  15. openjevx @ v0.5.9 (ee2a1f4) · README.md L34 ↩

  16. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L55 ↩

  17. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L63–68 ↩

  18. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/model.go L25 ↩

  19. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/model.go L64 ↩

  20. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L281–296 ↩

  21. openjevx @ v0.5.9 (ee2a1f4) · README.md L49–52 ↩ ↩2

  22. openjevx @ v0.5.9 (ee2a1f4) · README.md L97 ↩

  23. openjevx @ v0.5.9 (ee2a1f4) · README.md L98 ↩

  24. openjevx @ v0.5.9 (ee2a1f4) · README.md L99 ↩

  25. openjevx @ v0.5.9 (ee2a1f4) · README.md L100 ↩

  26. openjevx @ v0.5.9 (ee2a1f4) · README.md L101 ↩

  27. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L41–46 ↩

  28. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L63–73 ↩

  29. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L74–83 ↩

  30. openjevx @ v0.5.9 (ee2a1f4) · README.md L30–32 ↩

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

  32. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L84–90 ↩

  33. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L281–285 ↩

  34. openjevx @ v0.5.9 (ee2a1f4) · internal/modelsrc/s3.go L39–45 ↩

  35. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L46 ↩

  36. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/source.go L97 ↩

  37. openjevx @ v0.5.9 (ee2a1f4) · internal/modelsrc/s3.go L39–42 ↩

  38. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L54–56 ↩

  39. openjevx @ v0.5.9 (ee2a1f4) · README.md L36–38 ↩

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

  41. openjevx @ v0.5.9 (ee2a1f4) · README.md L39–40 ↩

  42. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L106–110 ↩

  43. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L138–139 ↩

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

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

  46. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L97–100 ↩

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

  48. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L574–576 ↩ ↩2

  49. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L381–384 ↩

  50. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L353–355 ↩

  51. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L369–373 ↩

  52. openjevx @ v0.5.9 (ee2a1f4) · README.md L49 ↩

  53. openjevx @ v0.5.9 (ee2a1f4) · README.md L49–51 ↩

  54. openjevx @ v0.5.9 (ee2a1f4) · README.md L52 ↩

  55. openjevx @ v0.5.9 (ee2a1f4) · README.md L51–52 ↩

  56. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/threads.go L44 ↩

  57. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/threads.go L60–63 ↩

  58. openjevx @ v0.5.9 (ee2a1f4) · README.md L54–55 ↩

  59. openjevx @ v0.5.9 (ee2a1f4) · README.md L55–56 ↩

  60. openjevx @ v0.5.9 (ee2a1f4) · README.md L52–53 ↩

  61. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/threads.go L42–44 ↩

  62. openjevx @ v0.5.9 (ee2a1f4) · README.md L56–57 ↩

  63. openjevx @ v0.5.9 (ee2a1f4) · llmresults/14-x86-cpu-latency.md L1–3 ↩

  64. openjevx @ v0.5.9 (ee2a1f4) · README.md L216–218 ↩

  65. openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L304–315 ↩

  66. openjevx @ v0.5.9 (ee2a1f4) · docs/adr/0011-inference-runtime.md L32–35 ↩

  67. openjevx @ v0.5.9 (ee2a1f4) · README.md L154 ↩

  68. openjevx @ v0.5.9 (ee2a1f4) · README.md L162–166 ↩

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

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

  71. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L7–9 ↩

  72. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L10 ↩

  73. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L14 ↩

  74. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L4–5 ↩ ↩2

  75. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L11 ↩

  76. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L7 ↩

  77. openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L16 ↩ ↩2 ↩3

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

  79. openjevx @ v0.5.9 (ee2a1f4) · docker-compose.yml L5–6 ↩

  80. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L19–20 ↩

  81. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L3–6 ↩

  82. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L32 ↩

  83. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L39–40 ↩

  84. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L21 ↩

  85. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L38 ↩

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

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

  88. openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L23–24 ↩

  89. openjevx @ v0.5.9 (ee2a1f4) · Dockerfile L25–26 ↩