How to Use WorldJen

This page walks through installing and running the runner, creating a run, and navigating your way around the app.

Installing the runner

The runner runs on a machine with an NVIDIA GPU. Install the Python package with the runner extra, then register using a one-time token from the app.

1. Create a runner in the app — Go to Runners and click New Runner. You'll get a registration token and setup steps.

2. Install on your GPU machine (Linux only) — The runner requires a Linux system with systemd. Install with pip or uv (Python 3.10+):

   pip install "worldjen[runner]"

   With uv, activate a virtual environment first:

   uv venv && source .venv/bin/activate
   uv pip install "worldjen[runner]"

3. Register the runner — Before the token expires (about 10 minutes), run the command shown in the app. The command already includes --name <INSTANCE> matching the name you chose (or the randomly generated one) in the app, e.g.:

   worldjen runner register --token <YOUR_TOKEN> --name gpu-01

   --name is the local instance identifier — it's how the CLI knows which runner you mean on this machine. Use the same --name on every subsequent worldjen runner ... command. If you omit it, the CLI uses default.

   After this, the runner appears as online on the Runners page.

Running multiple runners on one machine

You can register several runners on the same host — for example one per GPU. Each instance gets its own config (runner-{name}.conf) and systemd service (worldjen-runner@{name}) while sharing the Python venv and Hugging Face model cache. Just give each one a unique --name:

worldjen runner register --token <TOKEN_1> --name gpu-0
worldjen runner register --token <TOKEN_2> --name gpu-1

List the instances registered on this machine with worldjen runner list --local. Instance names must match [a-zA-Z0-9][a-zA-Z0-9_-]{0,63}.

Starting and stopping the runner

After registration, install the systemd service and start the runner so it can accept work. Pass --name <INSTANCE> to target a specific runner (omit to use default):

worldjen runner install --name gpu-01   # installs the service (auto-start on boot)
worldjen runner start --name gpu-01      # start now

To stop or view logs:

worldjen runner stop --name gpu-01
worldjen runner logs --name gpu-01 -f

Viewing runner logs

worldjen runner logs --name <INSTANCE> shows recent logs; add -f to stream them (follow mode). Drop --name to target the default instance.

Creating a run

1. Dashboard → Click "+ New run".
2. Choose a runner — Pick an online runner or create one.
3. Configure the model — Select or add a model (e.g. Hugging Face repo); add credentials if needed.
4. Choose dimensions — Pick a preset or select individual dimensions.
5. Model Comparison — Add optional reference runs and models.
6. Launch — Start the run.

Navigating the application

• Dashboard — List of runs (status, model, timestamps). Open a run to see results.
• Runners — Add runners, copy install/register/start commands, see status.
• Models — Manage model configurations.
• Run page — Summary, Gallery (videos and scores), Logs, and actions (Cancel, Duplicate, Export).
• Settings — User and preference settings.

Running from Python (no runner daemon)

If your inference code is already in Python, you can use the SDK's worldjen.run() directly — it runs your pipeline on the local machine, uploads the videos, and waits for evals. No runner daemon or systemd service needed.

import worldjen

result = worldjen.run(
    my_pipeline,
    dimensions=[worldjen.Dimensions.SUBJECT_CONSISTENCY],
    run_name="my-eval",
    model_id="my-org/my-model",
    wait_for_evals=True,
)
print(result.run_id, result.status, result.eval_results)

See SDK and CLI for full API details.

Quick reference: runner commands

Action	Command
Install package (pip)	pip install "worldjen[runner]"
Install package (uv)	uv venv && source .venv/bin/activate && uv pip install "worldjen[runner]"
Register (one-time per runner)	worldjen runner register --token <token> --name <instance>
Install systemd service	worldjen runner install --name <instance>
Start service	worldjen runner start --name <instance>
Stop service	worldjen runner stop --name <instance>
View logs	worldjen runner logs --name <instance>
Stream logs	worldjen runner logs --name <instance> -f
List local instances	worldjen runner list --local
Print SDK version	worldjen --version

--name is optional; omit it to target the default instance (default). Pass the same --name you used at register time on every subsequent command.