Deploy Physics Agent Docker

Deploy Physics Agent Service with Docker Compose

Deploy the physics-agent-service and the bundled OVRTX rendering API locally using Docker Compose. The physics service is CPU-only; the rendering sidecar uses the GPU.

When to Use

• Use when the user wants to run physics-agent-service locally with Docker Compose.
• Use when the user needs the bundled OVRTX rendering sidecar for physics classification.
• Use when the user wants to configure VLM provider credentials or run local smoke requests with optimizer flags.
• Use quickstart for a shorter first local POC, and use deploy-collection when running multiple Content Agents together.

Limitations

• The default stack owns host ports 8000 and 8001. Stop overlapping Material, Physics, Texture, or standalone OVRTX stacks before startup.
• The main service waits on OVRTX readiness; OVRTX is ready only when /health reports gpu_initialized: true.
• First build and first render are long-running operations. Return logs and health commands rather than holding an agent session open indefinitely.
• Keep secrets out of chat and commits. Tell the user to edit .env; do not ask them to paste keys.

Prerequisites

Check before deploying:

1. Docker Compose v2.24+: docker compose version -- required for env_file: required: false long-form syntax
2. NVIDIA GPU with ~16 GB+ VRAM: nvidia-smi
3. NVIDIA Container Toolkit installed: docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
4. VLM provider API key (at least one): NVIDIA NIM, OpenAI, Anthropic, or Gemini

Instructions

1. Confirm Docker, Compose, GPU, NVIDIA Container Toolkit, and port availability before starting the stack.
2. Create or update the repo-root .env with exactly the VLM provider credentials the selected backend needs.
3. Start the Physics Agent compose stack from the repo root.
4. Wait for both the main service and OVRTX readiness checks before reporting the service ready.
5. For optimizer-sensitive smoke assets, use the optimizer form fields below.
6. Return service URLs, health state, log commands, and stop commands using the output format below.

Set VLM API Key

Create .env at the repo root (the compose file reads it via env_file: ../../.env):

# Pick ONE provider:
echo 'NVIDIA_API_KEY=nvapi-...' > .env
# OR
echo 'OPENAI_API_KEY=sk-...' > .env
# OR
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
# OR
echo 'GOOGLE_API_KEY=...' > .env

Start Services

docker compose -f apps/physics_agent_service/docker-compose.yml up --build

This starts:

• physics-agent-service on port 8000 (REST API)
• ovrtx-rendering-api on port 8001 (GPU rendering, built from source)

First build takes ~10 minutes. First render takes ~5 minutes (shader compilation; cached after).

Access

• Health: http://localhost:8000/health
• API Docs: http://localhost:8000/docs (Swagger UI)
• OpenAPI spec: apps/physics_agent_service/openapi.yaml

Services

The main service depends_on the rendering API's health check passing (which flips gpu_initialized to true). On cold start expect the physics-agent container to sit in "waiting" state for ~5 minutes before it comes up.

Operations

View Logs

# All services
docker compose -f apps/physics_agent_service/docker-compose.yml logs -f

# Specific service
docker logs physics-agent-service
docker logs physics-ovrtx-rendering-api

Stop

# Stop all services
docker compose -f apps/physics_agent_service/docker-compose.yml down

# Stop and remove session data
docker compose -f apps/physics_agent_service/docker-compose.yml down -v

Rebuild After Code Changes

docker compose -f apps/physics_agent_service/docker-compose.yml up --build

# Force full rebuild (no cache)
docker compose -f apps/physics_agent_service/docker-compose.yml build --no-cache
docker compose -f apps/physics_agent_service/docker-compose.yml up

Check Health

curl http://localhost:8000/health   # main service
python - <<'PY'
import json
from urllib.request import urlopen

try:
    with urlopen("http://localhost:8001/health", timeout=10) as response:
        health = json.load(response)
except Exception as exc:
    print(f"rendering API unreachable: {exc}")
    raise SystemExit(1)

print(json.dumps(health))
if health.get("status") == "unhealthy":
    print("rendering API unhealthy")
    raise SystemExit(1)
if health.get("gpu_initialized") is True:
    print("rendering API ready")
else:
    print("rendering API warming")
PY

REST Smoke with Optimizer Flags

For ordinary smoke assets, run the pipeline without optimizer flags. For instanced USDs, assets that fail apply_physics with an instance-proxy authoring error, or one combined mesh that needs split-by-component predictions, pass the optimizer form fields to POST /pipeline:

# Instance-proxy authoring fix.
curl -X POST "http://localhost:8000/pipeline" \
  -F "usd_file=@scene.usd" \
  -F "optimize_usd=true" \
  -F "enable_deinstance=true"

# Also split one combined disjoint mesh into separate component predictions.
curl -X POST "http://localhost:8000/pipeline" \
  -F "usd_file=@scene.usd" \
  -F "optimize_usd=true" \
  -F "enable_deinstance=true" \
  -F "enable_split=true"

Use enable_deduplicate=true only when repeated identical geometry should be collapsed. At least one optimizer operation must be enabled when optimize_usd=true.

Resource Requirements

Environment Variables

Configurable via .env at the repo root. Key settings:

GPU Configuration

To assign specific GPUs to the rendering API, edit apps/physics_agent_service/docker-compose.yml:

ovrtx-rendering-api:
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1          # number of GPUs
            capabilities: [gpu]

Or pin a specific GPU ID:

            device_ids: ['0']

Output Format

When handing control back to the user, report:

• SERVICE_URL: http://localhost:8000
• DOCS_URL: http://localhost:8000/docs
• SERVICE_HEALTH: healthy, starting, or unhealthy
• OVRTX_HEALTH: healthy only when /health contains "gpu_initialized":true; otherwise warming or unhealthy
• LOGS: docker compose -f apps/physics_agent_service/docker-compose.yml logs -f
• STOP: docker compose -f apps/physics_agent_service/docker-compose.yml down
• Any missing credentials, port conflicts, GPU/toolkit blockers, or optimizer flags used for smoke validation.

Troubleshooting

OVRTX rendering API not starting

Check GPU access:

docker logs physics-ovrtx-rendering-api
docker exec physics-ovrtx-rendering-api nvidia-smi

Shader compilation on first boot takes ~5 minutes; wait it out.

Main service unhealthy before rendering API ready

The main service depends_on the rendering API's health check. If rendering takes long to start, the physics-agent-service container will stay in "waiting" state. Check docker compose ps to see which container is blocking.

503 / VLM failures under load

PA_MAX_ACTIVE_SESSIONS defaults to 1 because rendering plus a VLM call per prim is the main throughput bottleneck. Raising this requires headroom on both CPU memory and VLM provider quota.

Source: NVIDIA-Omniverse/content-agents — distributed by TomeVault.