> For the complete documentation index, see [llms.txt](https://animotive.gitbook.io/animotive-kimodo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://animotive.gitbook.io/animotive-kimodo/setup/docker-local.md).

# Docker (Local) Backend

The Local (Docker) backend runs the Kimodo motion model on your own workstation through Docker Desktop. The plugin runs the Docker binary **you point it at** (via the **Docker Executable Path** setting) with `compose exec` to invoke `kimodo_gen` inside a container that you operate. Generation results are written to a shared host folder that the plugin watches and imports automatically.

This page covers backend-specific setup for the Local (Docker) path. The general plugin install lives in [Quick Start](/animotive-kimodo/getting-started/quick-start.md); authoring a generation in Sequencer lives in [Prompting with Animotive Kimodo](/animotive-kimodo/getting-started/prompting-with-animotive-kimodo.md). The [First-Run Setup popup](/animotive-kimodo/setup/first-run-setup.md) covers the same Docker fields documented here in a focused form, and is the fastest path through initial configuration.

## When to use Local (Docker)

The Local (Docker) backend is the right choice when you have an NVIDIA GPU in the same machine as the Unreal Editor and you want to iterate without a network round trip. Generation latency is bounded by your local hardware rather than by a shared queue or by upload/download time.

| Trade-off         | Local (Docker)                          | Self-Hosted (HTTP)         |
| ----------------- | --------------------------------------- | -------------------------- |
| Hardware required | Local NVIDIA GPU                        | None on the editor machine |
| Iteration latency | Lowest                                  | Network-bound              |
| Setup effort      | Docker Desktop + NVIDIA's compose stack | Reachable URL + model name |
| Concurrency       | One generation per workstation          | Whatever the server admits |
| Offline           | Yes, after first image pull             | No                         |

If you do not have a local GPU but your team operates a Kimodo server, see [Self-Hosted (HTTP) Backend](/animotive-kimodo/setup/remote-backend.md). A managed cloud option, **Animotive Kimodo hosted service**, is planned for a future release.

## Prerequisites

Before configuring the plugin, confirm the following on the workstation that runs the Unreal Editor:

1. **Docker Desktop** is installed and running on a current release. On Windows, Docker Desktop must be configured with the **WSL 2** backend.
2. **GPU support for Docker** is enabled.
   * **Windows:** an up-to-date NVIDIA driver and WSL 2. Docker Desktop's GPU passthrough goes through WSL 2 — verify with `docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi` in a terminal.
   * **Linux:** the **NVIDIA Container Toolkit** is installed and the `nvidia` runtime is registered with Docker.
3. **NVIDIA GPU.** The Kimodo model targets the current NVIDIA CUDA generation; consult NVIDIA's repository for the minimum compute capability and VRAM footprint of the model build you intend to run.
4. **Unreal Engine 5.7** and **Animotive Kimodo** are installed per [Quick Start](/animotive-kimodo/getting-started/quick-start.md).

If `nvidia-smi` inside a CUDA container does not list your GPU, fix that first — the plugin cannot recover from a container that has no visible GPU.

## Get the Kimodo compose stack

The container images and `docker-compose.yml` for Kimodo are published by NVIDIA, not by Animotive. The Animotive Kimodo plugin does not bundle them.

1. Clone NVIDIA's repository: <https://github.com/nv-tlabs/kimodo>.
2. Follow NVIDIA's setup instructions for image pull and model-weight download. The relevant services in their `docker-compose.yml` are:
   * **`kimodo_gen`** — the generation CLI the plugin invokes.
   * **`kimodo_demo`** — an optional `localhost:7860` web UI. Not used by the plugin; useful for sanity-checking the model.
   * **`kimodo_textencoder`** — an optional background text-embedding service that speeds up repeat requests.
3. Bring the stack up at least once (`docker compose up`) and confirm the services come up healthy before pointing the plugin at the project directory.

Do not duplicate NVIDIA's runtime documentation in your project. The plugin treats the compose stack as an opaque dependency: it only needs to know where the compose file lives, which service name to exec into, and which host folder is mounted into the container.

## Configure plugin settings

All Local (Docker) settings live in **Edit → Project Settings → Plugins → Kimodo Exporter** under the **Kimodo Docker** category. The category is visible only when **Active Backend** is set to **Docker (Local)**.

Set **Active Backend** to **Docker (Local)** first, then fill in the fields below:

| Setting                        | Default              | What to enter                                                                                                                                                                                                                                                                                             |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Docker Executable Path**     | (empty)              | Absolute path to the Docker binary on your machine — the `docker` program inside your Docker Desktop `resources/bin` folder. **Required:** the plugin ships no built-in reference to Docker and runs only the exact file you point it at here. If this is empty the Local (Docker) backend cannot launch. |
| **Docker Compose Project Dir** | (empty)              | Absolute path to the folder that contains the Kimodo `docker-compose.yml`. The plugin uses this as the working directory for `docker compose exec`. No default — you must set this.                                                                                                                       |
| **Docker Service Name**        | `demo`               | Name of the compose service that runs `kimodo_gen`. Match the service key in your `docker-compose.yml`. NVIDIA's reference stack uses `demo` for the generation service.                                                                                                                                  |
| **Docker Kimodo Model**        | `Kimodo-SOMA-RP-v1`  | Value passed to `kimodo_gen --model`. The Docker build tag uses title case (`Kimodo-SOMA-RP-v1`), which differs from the lowercase form expected by the Self-Hosted backend (`kimodo-soma-rp`).                                                                                                           |
| **Host Export Dir**            | (empty)              | Absolute path on the host to a folder the plugin owns. The constraints JSON is written here on export, and the returned BVH is expected back here. This folder must be mounted into the container at **Container Export Dir**. No default — you must set this.                                            |
| **Container Export Dir**       | `/workspace/exports` | POSIX path inside the container that corresponds to **Host Export Dir**. Must match a volume mount in your `docker-compose.yml`.                                                                                                                                                                          |
| **Auto-Trigger On Export**     | `true`               | When `true`, clicking **Generate with Kimodo** writes the constraints JSON and then immediately runs `docker compose exec ... kimodo_gen`. Set to `false` if you want to write constraints only and invoke the CLI yourself.                                                                              |

The settings panel header reads **Kimodo Importer**; the section path under **Project Settings → Plugins** is **Kimodo Exporter**. Both refer to the same panel.

### Mount example

A minimal volume mount in NVIDIA's compose file, edited to match the plugin defaults:

```yaml
services:
  demo:
    # ...image / runtime config from NVIDIA's repo...
    volumes:
      - "D:/KimodoExports:/workspace/exports"
```

With this mount, **Host Export Dir** is `D:/KimodoExports` and **Container Export Dir** is `/workspace/exports`. The two paths must reference the same physical folder from each side of the container boundary.

## First-run checklist

Before clicking **Generate with Kimodo** for the first time on the Local (Docker) backend, walk through this checklist in a terminal on the host:

1. **Docker Desktop is running.** Open Docker Desktop and confirm the engine is started.
2. **The compose stack is up.** From the **Docker Compose Project Dir**, run `docker compose up -d` and confirm the service named in **Docker Service Name** is in the `running` state.
3. **The GPU is visible inside the container.** `docker compose exec <service> nvidia-smi` should list the GPU. If it does not, the container will fail at generation time with a CUDA error, not at startup.
4. **`kimodo_gen` is on the container `PATH`.** `docker compose exec <service> kimodo_gen --help` should print the CLI usage. If the command is not found, you are pointed at the wrong service or the wrong image.
5. **The export folder is mounted.** Create a sentinel file on the host (`echo test > <HostExportDir>/_probe.txt`) and confirm it appears at `<ContainerExportDir>/_probe.txt` inside the container.
6. **The model name resolves.** Run a quick sanity invocation: `docker compose exec <service> kimodo_gen "test" --model Kimodo-SOMA-RP-v1 --duration 1.0 --output /workspace/exports/_probe`. A successful run writes a result file under the export folder; a failure prints the model-resolution error directly.

Only proceed once each step passes. Most first-run failures from the plugin trace back to one of these six checks.

## Trigger a generation

With **Auto-Trigger On Export** at its default of `true`, the loop from Sequencer to imported animation is:

1. Click **Generate with Kimodo** in the Sequencer toolbar.
2. The plugin writes the constraints JSON to **Host Export Dir**.
3. The plugin runs `docker compose exec <service> kimodo_gen ...` immediately afterwards.
4. The container writes a BVH back into **Host Export Dir**.
5. The plugin auto-imports the BVH, retargets it onto your character, and injects the result into Sequencer.
6. The **Animotive Kimodo Monitor** panel (**Tools → Animotive Kimodo → Monitor**) tracks the lifecycle: `Queued → Processing → Downloading → Retargeting → Completed`.

If **Auto-Trigger On Export** is `false`, step 3 is skipped. The plugin writes the constraints JSON and stops; you are expected to invoke `kimodo_gen` yourself and place the resulting BVH back in **Host Export Dir** for the import side of the pipeline to pick up.

For the full authoring walkthrough, see [Prompting with Animotive Kimodo](/animotive-kimodo/getting-started/prompting-with-animotive-kimodo.md).

## Common Docker-specific issues

The categories below are the failure modes that are specific to the Local (Docker) backend. Generic networking and server errors that surface in the monitor (`NetworkUnreachable`, `RemoteServerError`) belong to the Self-Hosted backend, not this one.

| Symptom                                                                    | Likely cause                                                                      | Fix                                                                                                                                                                                                      |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Export hangs immediately; nothing reaches the monitor's `Processing` state | Docker Desktop is not running, or its engine is paused                            | Start Docker Desktop; wait for the whale icon to stop animating before retrying                                                                                                                          |
| `docker compose exec` reports the service is not running                   | Compose stack is down                                                             | `docker compose up -d` from **Docker Compose Project Dir**; confirm `docker compose ps` shows the service `running`                                                                                      |
| `kimodo_gen: command not found` in the monitor log                         | Wrong **Docker Service Name**, or the image does not include the `kimodo_gen` CLI | Verify the service name matches the one in NVIDIA's `docker-compose.yml`; re-pull the image if the CLI is genuinely missing                                                                              |
| Container starts but generation fails with a CUDA error                    | GPU is not visible to the container                                               | Re-run `docker compose exec <service> nvidia-smi`; on Windows, confirm WSL 2 is the Docker Desktop backend and the NVIDIA driver is current; on Linux, confirm the NVIDIA Container Toolkit is installed |
| Constraints JSON written but no BVH returns                                | **Host Export Dir** and **Container Export Dir** are not the same folder          | Confirm the volume mount in `docker-compose.yml` matches both fields; use the `_probe.txt` sentinel from the first-run checklist                                                                         |
| Generation fails with a model-name error from `kimodo_gen`                 | **Docker Kimodo Model** does not match a model the image can resolve              | Use the title-case Docker form (`Kimodo-SOMA-RP-v1`), not the Self-Hosted lowercase form (`kimodo-soma-rp`); verify with `kimodo_gen --help`                                                             |
| Toolbar export completes with no Docker invocation at all                  | **Auto-Trigger On Export** is `false`                                             | Either flip it back to `true`, or run `kimodo_gen` yourself with the constraints JSON the plugin wrote                                                                                                   |

When the underlying `docker compose` invocation fails, the monitor row terminates with the friendly message `Kimodo couldn't solve this animation. Try simplifying the prompt or adjusting key poses.` — open the row's log to see the raw stderr from `kimodo_gen` before assuming the cause is prompt-related.

## Switching to Self-Hosted

The **Active Backend** dropdown can be flipped between **Docker (Local)** and **Remote Server** at any time. There is one gotcha worth flagging:

* The model-name field is **not** shared across backends.
* **Local (Docker)** reads **Docker Kimodo Model** (default `Kimodo-SOMA-RP-v1`).
* **Self-Hosted (HTTP)** reads **Remote Kimodo Model** (default `kimodo-soma-rp`).

If you switch backends and the next generation fails with a model-resolution error, check the model field on the backend you switched **to**, not the one you switched from. Full Self-Hosted setup is on [Self-Hosted (HTTP) Backend](/animotive-kimodo/setup/remote-backend.md).