Docker Quickstart

Docker Quickstart

The fastest way to see Biomata running is with Docker. One command starts the engine, the engine-owned simulation, and the WebSocket server. No Ollama, no API keys, no Unity required.

Prerequisites

Docker Desktop (or Docker Engine + Compose plugin). That's it.

Run it

bash
git clone https://github.com/smithd36/biomata-engine.git
cd biomata-engine
docker compose up

This starts two services:

ServiceWhat it doesPort
ws-server Biomata Engine + WebSocket server exposing the engine-owned simulation over Protocol v1 8765
sample-client Minimal Python client that connects, ticks the simulation, and prints agent decisions —

Within a few seconds you should see agent decisions streaming in the terminal:

text
Tick 1 | Aldric | patrol → gate_post    | holding position at gate
Tick 1 | Berna  | patrol → gate_post    | holding position at gate
Tick 1 | Silas  | trade  → market_stall | idle at market stall
Tick 2 | Aldric | patrol → gate_post    | holding position at gate
...

All three agents are running a deterministic brain — no LLM, no network calls, fully reproducible.

What's running

The Docker compose stack uses the engine-owned simulation with IdleBrain — a deterministic brain that follows scripted patterns. This is intentional: the quickstart should work for everyone regardless of hardware or network access.

The compose file (docker-compose.yml at the repo root) looks like this:

yaml
services:
  ws-server:
    build: .
    command: >
      biomata-ws
      --config examples/engine_owned/sim.yaml
      --port 8765
      --mode autonomous
    ports:
      - "8765:8765"

  sample-client:
    build: .
    command: python examples/engine_owned/docker_client.py
    depends_on:
      - ws-server
    environment:
      - BIOMATA_HOST=ws-server
      - BIOMATA_PORT=8765

Connect Unity to the running server

With the WebSocket server running at ws://localhost:8765, you can connect the Unity SDK directly — no Python setup required on the Unity side.

  1. Import the Biomata Unity package into your Unity 6 project (see Unity SDK)
  2. Add BiomataManager to your scene and set Host = localhost, Port = 8765
  3. Press Play — your Unity agents will receive decisions from the running Python server

Swap in an LLM brain (optional)

If you have Ollama running locally, you can swap the deterministic brain for LLM-driven cognition by editing examples/engine_owned/sim.yaml:

yaml
agents:
  - id: gate_guard_left
    name: Aldric
    capabilities: [patrol, authority]
    brain:
      # Change this line:
      class: src.plugins.builtin.idle_brain.brain.IdleBrain
      # To this:
      # class: src.plugins.builtin.ollama.brain.OllamaLLMBrain
      # personality:
      #   traits: [vigilant, loyal]
      #   goals: [protect the gate, report threats]

Then rebuild and restart:

bash
docker compose down
docker compose up --build
Ollama network access

When running inside Docker, the engine container needs to reach Ollama on your host machine. Use host.docker.internal as the Ollama base URL in the YAML config, or pass --add-host host.docker.internal:host-gateway to the Docker run command.

Next steps