Skip to content

Anuva Python Server Operations

This guide covers local worker operation for Windows-first deployments that run beside the Unity video generator.

Configuration file

The worker loads YAML from --config, ANUVA_CONFIG_PATH, or the default C:\Anuva\Worker\config\worker.yaml.

Keep the config deterministic and non-secret. Use it for worker identity, local paths, bind addresses, ports, Unity mode, timeouts, retry limits, and log retention. Do not store API tokens, dashboard tokens, cookies, Authorization headers, passwords, or signed URLs in the YAML file. Instead, configure the matching *_env key and set the secret value in the environment.

Example safe skeleton:

worker:
  id: "unity-worker-01"
  root_dir: "C:\\Anuva\\Worker"

webapp:
  mode: "real"
  base_url: "https://anuva.example.com"
  api_token_env: "ANUVA_WORKER_API_TOKEN"

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

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
    admin_token_env: "ANUVA_DASHBOARD_TOKEN"

simulator:
  enabled: false
  host: "127.0.0.1"
  port: 7090

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

By default, ZeroMQ, the content server, dashboard, and simulator bind to 127.0.0.1 only. Do not expose local worker services to public networks unless a later security review explicitly approves it.

Environment variables

Required or commonly used variables:

Variable Purpose
ANUVA_CONFIG_PATH Optional path to the worker YAML config.
ANUVA_WORKER_API_TOKEN Worker-scoped Web App API token; referenced by webapp.api_token_env.
ANUVA_DASHBOARD_TOKEN Dashboard mutation token; referenced by servers.dashboard.admin_token_env.

Set secrets at the user or machine environment level for the account running the worker. Do not commit a populated secrets.env or copy secret values into generated service commands.

Unity EXE mode

Use unity.mode: "exe" when the worker launches the built Unity executable. Configure:

  • unity.executable_path
  • unity.working_directory
  • optional unity.launch_args
  • startup, heartbeat, render, shutdown, cancellation, and restart timeouts

The worker appends stable Anuva arguments for worker ID, ZeroMQ host/ports, local content server URL, and worker mode.

For a local manual smoke test against the Web App simulator, create C:\Anuva\Worker\config\manual-sim-exe.yaml with webapp.mode: "simulated", simulator.enabled: true, jobs.acquisition_mode: "manual", and unity.mode: "exe", then run:

.\scripts\start_manual_sim_exe.bat

The launcher checks that local ports 5561, 5562, 7080, 7090, and 7443 are free, then starts the simulator, content server, and dashboard. Use the Dashboard Launch Unity action first, wait for ready: true, then use manual Run for job_happy_final. In EXE mode, the manual run should reject the job before claiming it if Unity is not already ready. The Launch/Restart/Stop controls are shown only when the loaded config has unity.mode: "exe".

Unity Editor Play Mode

Use unity.mode: "editor" for local development. In this mode, the worker does not launch Unity. Start Play Mode in the Unity Editor and let the editor connect as the ZeroMQ client using the same localhost ports.

Editor mode is useful for protocol and rendering iteration, but it should still use the same job package, local asset URL, readiness, heartbeat, cancellation, and completion contracts as EXE mode.

Simulator mode

Set webapp.mode: "simulated" and simulator.enabled: true to use the local Web App simulator. The simulator defaults to 127.0.0.1:7090 and supports scenario-based development flows.

Common commands:

anuva-worker simulator run --scenario happy_path_final_render
anuva-worker simulator reset
anuva-worker simulator load-scenario happy_path_final_render
anuva-worker simulator list-scenarios

Dashboard token

The dashboard binds to 127.0.0.1 by default. Read-only routes are intended for local operator visibility. Mutation routes require the token from servers.dashboard.admin_token_env, which defaults to ANUVA_DASHBOARD_TOKEN.

Send the token as either:

  • Authorization: Bearer <token>
  • X-Anuva-Dashboard-Token: <token>

Local TLS certificates

Unity/Vuplex asset loading expects local HTTPS URLs. Generate a self-signed localhost certificate with:

anuva-worker cert generate-local --config C:\Anuva\Worker\config\worker.yaml

The generated certificate includes localhost and 127.0.0.1 subject alternative names. Keep private keys under the local worker root and out of source control.

NSSM installation helper

The CLI can print copy-pasteable NSSM commands:

anuva-worker service print-nssm-install --config C:\Anuva\Worker\config\worker.yaml

A static helper script is also available at scripts/install_nssm_service.ps1.

Important: Windows services run in Session 0 by default. Unity graphics control must run in an interactive user session, not Session 0. Use NSSM only for non-graphics worker tasks, or pair service startup with a reviewed interactive-session launcher such as a user logon scheduled task. Do not expect a Session 0 service to reliably control Unity rendering, GPU contexts, desktop interaction, or graphics device initialization.

Troubleshooting failed jobs

When a job fails, collect enough information to answer which job failed, where it failed, what Unity reported, which files were involved, and whether retry is safe.

Checklist:

  1. Inspect jobs/{jobId}/job_manifest.json for asset and output paths.
  2. Review jobs/{jobId}/logs/zmq_messages.jsonl for Unity protocol messages.
  3. Review worker logs in logging.log_dir, subject to logging.retain_days cleanup.
  4. Review unity_stdout.log and unity_stderr.log for process-level Unity errors.
  5. Check dashboard health, active job, Unity readiness, heartbeat freshness, and Web App connectivity.
  6. Confirm local content URLs are https://127.0.0.1:<port>/... and that certificates exist.
  7. Validate FFmpeg/ffprobe availability when output validation or thumbnails are involved.
  8. Verify signed upload failures without copying signed URL query strings into tickets or logs.

Logs redact API tokens, Authorization headers, cookies, secret config keys, and signed URL query strings. Avoid pasting unredacted secrets into diagnostics.