Quickstart

OpenJevX is one server binary plus one model folder. The binary holds no model. ¹

A release is a small binary per platform plus one model folder archive, and you unpack both into the same directory. ²

The pinned server release is 0.5.9 ("version": "0.5.9" in package.json). ³

The release downloads fetch model 0.5.2. ⁴ ⁵

Pick one of the four paths below, then make your first request.

Path 1: release binary plus model folder

The release has one archive per platform: openjevx-darwin-arm64.tar, openjevx-linux-amd64.tar, openjevx-linux-arm64.tar and openjevx-windows-amd64.zip. ⁶

The platform archives carry no openjevx.json, so a release unpacked over an old one never replaces your config or ships a password. ⁷

The model folder ships as openjevx-model-<version>.tar.gz, holding model/ with openjevx.w8.onnx, config.json and tokenizer.json. ⁸

Download the platform archive and the model archive, then unpack both into the same folder and run the server. ² ⁴

tar -xf openjevx-darwin-arm64.tar && tar -xzf openjevx-model-0.5.2.tar.gz && ./openjevx

On Linux (x86-64) the archive is openjevx-linux-amd64.tar; on Linux ARM (arm64, e.g. Graviton or Ampere) it is the same with openjevx-linux-arm64.tar instead. ⁹

The Linux builds need glibc 2.28 or later. ¹⁰

On Windows, unpack both into the same folder and run openjevx.exe. ¹¹

There is no Intel-Mac build: ONNX Runtime 1.29 has none. ¹²

With no model set, the server looks next to itself for model/, then models/openjevx/, then openjevx.w8.onnx. ¹³ ¹⁴

If none of those exists, it returns the error no model found: set "model" in openjevx.json, or put a model folder at followed by the paths it tried. ¹⁴

Path 2: the npx installer

The npx installer downloads release v0.5.9 with model 0.5.2. ¹⁵

It installs into ~/.local/share/openjevx (override with OPENJEVX_HOME) and puts the openjevx command in ~/.local/bin (override with OPENJEVX_BIN). ¹⁶

Its openjevx command does cd into the install folder and then runs the server binary. ¹⁷

It picks the archive by OS and CPU: Windows gets openjevx-windows-amd64.zip, macOS arm64 openjevx-darwin-arm64.tar, Linux x64 openjevx-linux-amd64.tar and Linux arm64 openjevx-linux-arm64.tar. ¹⁸

Any other OS and CPU stops the installer with OpenJevX: no server build for …. ¹⁹

On an Intel Mac the reason given is that ONNX Runtime 1.29 has no Intel macOS build, so OpenJevX runs on Apple Silicon only (or use Docker). ¹⁹

On an upgrade it reads your openjevx.json before unpacking and writes it back afterwards. ²⁰

It then adds only the keys your file lacks (listen 127.0.0.1:21118, device auto); your values always win. ²¹ ²²

When it finishes, it says the dashboard password is printed once on the first start and kept in openjevx.password in the install folder. ²³

Path 3: from source

You need Go and Task. ²⁴

task run fetches ONNX Runtime and the model folder into .local/, builds, and starts the server on http://127.0.0.1:21118/. ²⁴

task build only builds; task test runs the tests. ²⁴

task run
task build
task test

The build uses cgo: CGO_ENABLED=1 go build -o .local/openjevx ./cmd/openjevx. ²⁵

task setup supports macOS arm64, Linux x86_64 and Linux aarch64, and fails with “unsupported platform” elsewhere. ²⁶

Path 4: the prebuilt Docker image

The prebuilt image is for linux/amd64 and linux/arm64, tagged with each release and latest. ²⁷

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

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. ²⁸

Make a key with openssl rand -hex 24. ²⁹

The container listens on 0.0.0.0; the api_key is on whenever the server listens beyond loopback. ³⁰ ³¹

First request

The server listens on 127.0.0.1:21118 unless openjevx.json says otherwise. ³² ³³

On that loopback address the API key is off unless you set one, so the request below needs no key. ³⁴

Every recipe is one POST /v1/systemone with a state (the text or JSON the question is about) and named questions. ³⁵

A noul question is a yes/no; read the probability of yes from noul. ³⁶

The recipe call sends OPENJEVX_API_KEY; on 127.0.0.1 with no key set the server ignores the header, so the call works unchanged. ³⁷ ³⁸

curl -s -H "Authorization: Bearer $OPENJEVX_API_KEY" localhost:21118/v1/systemone -d '{"state": "git push --force origin main", "questions": {"danger": {"type": "noul", "instructions": "Does this command overwrite history on a shared remote branch?"}}}' | jq -c .answers

The recipe recorded this answer from model 0.5.2 on server 0.5.7, CPU: ³⁹

{"danger":{"action":{"act_probability":1},"answer_confidence":0.5513,"confidence":0.5513,"noul":0.5513,"probabilities":{"false":0.4487,"true":0.5513},"type":"noul"}}

The model missed this one: P(yes) 0.55, so jevx says unsure; treat unsure as yes for anything that rewrites shared history. ⁴⁰

Your inputs will score differently: copy the pattern, not the numbers, and test on your own data. ⁴¹

The full response is {"model":"openjevx","answers":...,"usage":{"input_tokens":...,"output_tokens":0,"server_ms":...}}. ⁴²

Each response also carries a Server-Timing header with encode, wait, run and total in ms. ⁴³ ⁴⁴ ⁴⁵

A non-POST request gets 405, and a body with no questions gets 400 questions missing. ⁴⁶ ⁴⁷

GET /health is open, with no password. ⁴⁸

curl -fsS http://127.0.0.1:21118/health

/health returns status, device, model, version, sha256, source, fallback, loaded_at and dir. ⁴⁹

Security defaults you must know

Warning

/v1/systemone needs Authorization: Bearer <key> whenever the server listens beyond loopback; on 127.0.0.1, ::1 and localhost the key is off unless one is set. ⁵⁰ With no listen in openjevx.json, the server listens on 127.0.0.1:21118, a loopback address. ⁵¹ ⁵² When you set a non-loopback listen and no key, the server generates one into openjevx.api-key beside openjevx.json. ³⁴ The deploy paths all listen beyond loopback, so they need the API key and the dashboard password; there are no default credentials anywhere. ⁵³ Their firewall still opens only SSH; the customer opens port 21118 to their own network or uses an SSH tunnel. ⁵⁴

curl -H "Authorization: Bearer YOUR_API_KEY" http://<host>:21118/v1/systemone -d @body.json

Warning

The dashboard password is always on: unset, the server generates one into openjevx.password. ⁵⁵ A start that creates it shows the value once, and only on a terminal. ⁵⁶ 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. ⁵⁷ The routes behind that password are the dashboard /, /stats, /metrics and /recipes. ⁵⁵

The old published password adminadmin (in openjevx.json up to v0.5.6) is ignored and replaced by a generated one. ⁵⁸

Set your own with "password" in openjevx.json or OPENJEVX_PASSWORD. ⁵⁹

With a password set, the guard accepts HTTP Basic auth (any user name) or a ?password= query parameter. ⁶⁰

allow_no_password (or OPENJEVX_ALLOW_NO_PASSWORD=1) turns the dashboard password off. ⁶¹

Use it from jevx

Use OpenJevX from the jevx CLI by adding a profile for its URL and selecting it. ⁶²

jevx profile add openjevx http://127.0.0.1:21118/v1/systemone --model openjevx
jevx profile use openjevx

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

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

jevx caches answers for 7 days, keyed by the profile’s model name. ⁶⁴

After upgrading the OpenJevX model, run jevx cache clear, or give the profile a versioned model name such as openjevx-0.5.2. ⁶⁵

jevx cache clear

jevx’s default thresholds: act on noul at or above 0.8, act on the no at or below 0.2, and on confidence at or above 0.6 for a choice or score. ⁶⁶

Anything in between means: narrow the question, check it yourself, or ask the user. ⁶⁷

Next: Configuration covers every key, and Model from object storage covers serving the model from a bucket.

Sources

openjevx @ v0.5.9 (ee2a1f4) · README.md L65 ↩
openjevx @ v0.5.9 (ee2a1f4) · scripts/package.sh L4–7 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · package.json L3 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L133–134 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · deploy/MODEL_VERSION L1 ↩
openjevx @ v0.5.9 (ee2a1f4) · scripts/package.sh L5 ↩
openjevx @ v0.5.9 (ee2a1f4) · scripts/package.sh L37 ↩
openjevx @ v0.5.9 (ee2a1f4) · scripts/package.sh L6 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L137–146 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/platform.js L1–2 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L148–150 ↩
openjevx @ v0.5.9 (ee2a1f4) · docs/adr/0011-inference-runtime.md L30 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/model.go L25 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/model.go L64–70 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L10–13 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L15–16 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L71–76 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/platform.js L3–7 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/platform.js L3–11 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L54–61 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/config.js L1–2 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/config.js L11–14 ↩
openjevx @ v0.5.9 (ee2a1f4) · bin/openjevx.js L82 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L220 ↩ ↩² ↩³
openjevx @ v0.5.9 (ee2a1f4) · Taskfile.yml L32–36 ↩
openjevx @ v0.5.9 (ee2a1f4) · Taskfile.yml L15–19 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L154 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L169–170 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L171 ↩
openjevx @ v0.5.9 (ee2a1f4) · deploy/docker-entrypoint.sh L16 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L21–23 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L447–449 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L474–476 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L31 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L34–35 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L37–39 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/07-is-this-command-dangerous.md L7 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L21–22 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/07-is-this-command-dangerous.md L13 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/07-is-this-command-dangerous.md L37 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L50 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L96–100 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L19–20 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L95 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L112–115 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L23–26 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/decision.go L56–59 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L208 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L190–194 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/auth.go L22–23 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L447–448 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L460–462 ↩
openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L14–16 ↩
openjevx @ v0.5.9 (ee2a1f4) · docs/DEPLOY.md L19–20 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L32 ↩ ↩²
openjevx @ v0.5.9 (ee2a1f4) · README.md L38–39 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L38–40 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L42–43 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L202 ↩
openjevx @ v0.5.9 (ee2a1f4) · cmd/openjevx/main.go L514–525 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L34 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L175–180 ↩
openjevx @ v0.5.9 (ee2a1f4) · README.md L182 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L87–88 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L87–89 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L77–84 ↩
openjevx @ v0.5.9 (ee2a1f4) · recipes/README.md L81 ↩