Skip to content

Anuva Python Server User Guide

This guide covers local manual render-job smoke tests against the implemented Anuva Web App at http://localhost:3000, plus the existing simulator launchers for development-only flows.

Before You Start

For real Web App testing, confirm all of these first:

  1. The Anuva Web App is running at http://localhost:3000.
  2. The Web App has ANUVA_WORKER_API_TOKEN configured.
  3. The Web App database migrations required by the worker API have been applied.
  4. S3 signing is configured in the Web App, because the worker uses the signed upload flow.
  5. At least one video_generation_jobs record is queued.
  6. The worker machine uses the same ANUVA_WORKER_API_TOKEN value as the Web App. The new Web App launchers default this to anuva-worker-api-token if it is not already set.
  7. The repo-local .venv exists and dependencies are installed.

Useful environment setup from PowerShell:

$env:ANUVA_WORKER_API_TOKEN = "anuva-worker-api-token"
$env:ANUVA_DASHBOARD_TOKEN = "local-dev-dashboard-token"

The worker expects Unity/Vuplex assets to be served locally over HTTPS, so generate the localhost certificate before the first run:

.\.venv\Scripts\python.exe -m anuva_python_server.cli cert generate-local --config C:/Anuva/Worker/config/manual-webapp-editor.yaml

Manual Web App + Unity Editor Test

Use this flow when the Anuva Web App is the job source and Unity runs in Editor Play Mode.

Config

Save this as C:/Anuva/Worker/config/manual-webapp-editor.yaml:

worker:
  id: "unity-editor-worker-01"
  root_dir: "C:/Anuva/Worker"

jobs:
  acquisition_mode: "manual"
  list_available_limit: 25
  allow_manual_claim_when_busy: false

webapp:
  mode: "real"
  base_url: "http://localhost:3000"
  api_token_env: "ANUVA_WORKER_API_TOKEN"
  timeout_sec: 30

simulator:
  enabled: false

unity:
  mode: "editor"
  require_existing_connection: true
  startup_timeout_sec: 120
  heartbeat_timeout_sec: 30
  render_timeout_sec: 1800

zmq:
  host: "127.0.0.1"
  command_port: 5560
  status_port: 5561
  heartbeat_port: 5562
  receive_timeout_ms: 2000

servers:
  content:
    host: "127.0.0.1"
    port: 7443
    https: true
    cert_file: "C:/Anuva/Worker/certs/localhost.crt"
    key_file: "C:/Anuva/Worker/certs/localhost.key"
  dashboard:
    host: "127.0.0.1"
    port: 7080
    https: false
    admin_token_env: "ANUVA_DASHBOARD_TOKEN"

upload:
  strategy: "signed_s3"

logging:
  level: "INFO"
  json_logs: true
  log_dir: "C:/Anuva/Worker/logs"
  retain_days: 14

One-Command Server Startup

Run this from the repository root:

.\scripts\start_manual_webapp_editor.bat

The launcher will:

  1. Default ANUVA_WORKER_API_TOKEN to anuva-worker-api-token if it is not already set.
  2. Validate C:/Anuva/Worker/config/manual-webapp-editor.yaml.
  3. Check that local worker ports 5561, 5562, 7080, and 7443 are free.
  4. Generate the localhost HTTPS certificate if needed.
  5. Start the content server in a new Command Prompt window.
  6. Start the dashboard in a new Command Prompt window.

Then open:

http://127.0.0.1:7080

The default dashboard token is:

local-dev-dashboard-token

To use a different config path:

.\scripts\start_manual_webapp_editor.bat C:/Anuva/Worker/config/manual-webapp-editor.yaml

Manual Server Startup

Use these commands only when you want to start each process yourself:

$config = "C:/Anuva/Worker/config/manual-webapp-editor.yaml"

.\.venv\Scripts\python.exe -m anuva_python_server.cli validate-config --config $config
.\.venv\Scripts\python.exe -m anuva_python_server.cli cert generate-local --if-missing --config $config

Start-Process powershell -ArgumentList '-NoExit', '-Command', ".\.venv\Scripts\python.exe -m anuva_python_server.cli content --config $config"
Start-Process powershell -ArgumentList '-NoExit', '-Command', ".\.venv\Scripts\python.exe -m anuva_python_server.cli dashboard --config $config"

Unity Editor Setup

In Unity Editor Play Mode, use the same localhost ZeroMQ topology:

Command REP bind:       tcp://127.0.0.1:5560
Status PUSH connect:    tcp://127.0.0.1:5561
Heartbeat PUSH connect: tcp://127.0.0.1:5562
Content base URL:       https://127.0.0.1:7443

Do not press Play too early if Unity only emits unity.ready once at startup. Start the manual run first, then press Play so the worker is already waiting for readiness.

Running A Manual Job

  1. Open the dashboard.
  2. Enter local-dev-dashboard-token in the token field.
  3. Confirm the queued job appears in Available Web App Jobs.
  4. Select Run for that job.
  5. When the Dashboard shows the run waiting for Unity readiness, press Play in Unity Editor.

The worker will:

  1. Atomically claim the selected Web App job.
  2. Download the render package from /api/worker/v1/jobs/{jobId}/package.
  3. Download and rewrite assets into the local workspace.
  4. Send render.start to Unity.
  5. Forward progress to the Web App with PATCH /api/worker/v1/jobs/{jobId}/status.
  6. Validate final.mp4.
  7. Generate a thumbnail.
  8. Request a signed S3 upload target.
  9. Upload the MP4 to S3.
  10. Confirm the upload with the Web App.
  11. Complete the job in the Web App.

You can run the same lifecycle from the CLI:

.\.venv\Scripts\python.exe -m anuva_python_server.cli run-manual-job --config $config --job-id <queued-job-id>

When using the CLI in editor mode, press Play after the command begins waiting for Unity readiness.

Expected Local Workspace

The job workspace should look like:

C:/Anuva/Worker/jobs/<job-id>/presentation_config.local.json
C:/Anuva/Worker/jobs/<job-id>/job_manifest.json
C:/Anuva/Worker/jobs/<job-id>/assets/...
C:/Anuva/Worker/jobs/<job-id>/output/

Manual Web App + Unity EXE Test

Use this flow when the Anuva Web App is the job source and the Python worker launches or connects to the built Unity player.

Config

Save this as C:/Anuva/Worker/config/manual-webapp-exe.yaml, then update unity.executable_path and unity.working_directory:

worker:
  id: "unity-exe-worker-01"
  root_dir: "C:/Anuva/Worker"

jobs:
  acquisition_mode: "manual"
  list_available_limit: 25
  allow_manual_claim_when_busy: false

webapp:
  mode: "real"
  base_url: "http://localhost:3000"
  api_token_env: "ANUVA_WORKER_API_TOKEN"
  timeout_sec: 30

simulator:
  enabled: false

unity:
  mode: "exe"
  executable_path: "C:/Anuva/Unity/AnuvaVideoGenerator.exe"
  working_directory: "C:/Anuva/Unity"
  launch_args: []
  startup_timeout_sec: 120
  heartbeat_timeout_sec: 30
  render_timeout_sec: 1800

zmq:
  host: "127.0.0.1"
  command_port: 5560
  status_port: 5561
  heartbeat_port: 5562
  receive_timeout_ms: 2000

servers:
  content:
    host: "127.0.0.1"
    port: 7443
    https: true
    cert_file: "C:/Anuva/Worker/certs/localhost.crt"
    key_file: "C:/Anuva/Worker/certs/localhost.key"
  dashboard:
    host: "127.0.0.1"
    port: 7080
    https: false
    admin_token_env: "ANUVA_DASHBOARD_TOKEN"

upload:
  strategy: "signed_s3"

logging:
  level: "INFO"
  json_logs: true
  log_dir: "C:/Anuva/Worker/logs"
  retain_days: 14

One-Command Server Startup

Run this from the repository root:

.\scripts\start_manual_webapp_exe.bat

To use a different config path:

.\scripts\start_manual_webapp_exe.bat C:/Anuva/Worker/config/manual-webapp-exe.yaml

The launcher starts the content server and dashboard only. The Anuva Web App must already be running separately at http://localhost:3000.

Open:

http://127.0.0.1:7080

Running A Manual Job

In the Dashboard:

  1. Select Launch Unity.
  2. Wait for the Unity panel to show ready: true.
  3. Select Run for a queued Web App job.

In EXE mode, the worker refuses the run before claim if Unity is not already ready. That keeps the Web App job queued instead of claiming it too early.

The Unity panel should show mode: exe. The Launch Unity, Restart, and Stop controls are visible only in EXE mode.

The worker appends these arguments to the Unity command line:

--anuva-worker-id
--anuva-zmq-host
--anuva-zmq-command-port
--anuva-zmq-status-port
--anuva-zmq-heartbeat-port
--anuva-local-server
--anuva-mode worker

The Unity EXE should use those values to emit unity.ready, accept render.start, and report progress over the same localhost ZeroMQ ports used by editor mode.

You can also run the full lifecycle from the CLI:

$config = "C:/Anuva/Worker/config/manual-webapp-exe.yaml"
.\.venv\Scripts\python.exe -m anuva_python_server.cli run-manual-job --config $config --job-id <queued-job-id>

Diagnostics

For real Web App runs, inspect:

C:/Anuva/Worker/jobs/<job-id>/job_manifest.json
C:/Anuva/Worker/jobs/<job-id>/logs/zmq_messages.jsonl
C:/Anuva/Worker/jobs/<job-id>/diagnostics/system_snapshot_start.json
C:/Anuva/Worker/jobs/<job-id>/diagnostics/system_snapshot_end.json
C:/Anuva/Worker/logs

For EXE mode, also inspect:

C:/Anuva/Worker/logs/unity_stdout.log
C:/Anuva/Worker/logs/unity_stderr.log

If a job is visible in the Web App but not in the Dashboard, check:

  1. The job is still in queued.
  2. ANUVA_WORKER_API_TOKEN matches the Web App token. The Web App launchers default it to anuva-worker-api-token, so the Web App should use that same value unless you intentionally override it.
  3. GET /api/worker/v1/jobs/available is enabled and reachable.
  4. The Web App worker collections and migrations are present.

Simulator Launchers Still Available

The simulator launchers are still useful when you want a fully local worker + fake Web App flow:

.\scripts\start_manual_sim_editor.bat
.\scripts\start_manual_sim_exe.bat

Those launchers start the simulator on http://127.0.0.1:7090, seed happy_path_final_render, and keep the old development-only workflow available without the real Web App.