> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/run-the-engine/mojo-sidecar.md).

# Run the Mojo engine

The **Mojo engine** is the compiled binary (`mojo_build/simulate`) that runs Algenta's simulations. In production the API talks to a **pool of long-lived Mojo workers** over local sockets — the "sidecar" — instead of forking a process per request. Getting that pool up and confirmed-healthy is the single most important step in a self-hosted deployment, and the one most likely to trip you up. This page gets you there.

{% hint style="info" %}
Most users never build the binary: the Docker image **ships it pre-compiled**, so `./install.sh` just works. Build from source only for local engine development or a custom module set — see [Filtered & selective install](/run-the-engine/filtered-install.md).
{% endhint %}

## Prerequisites

* A self-hosted deployment (see [Self-hosting](/deploy-and-operate/self-hosting.md)), or a local checkout for building from source.
* For source builds: the Mojo toolchain via `pixi` (installed by `make setup-mojo`), `clang`/LLVM, and **plenty of RAM/disk** — a full build is large (see the OOM note below).

## Get the pool running

{% tabs %}
{% tab title="Docker (recommended)" %}
The compiled binary is baked into the image at `/app/mojo_build/simulate`; `MOJO_BINARY_PATH` already points at it. The pool starts with the API — you don't build anything.

```bash
# the standard self-hosted install brings the API up with the engine pool
curl -sSL https://algenta.ai/install.sh | bash
```

Then jump to **Confirm it's on the fast path** below.
{% endtab %}

{% tab title="Build from source" %}
For a local engine or a custom module set:

```bash
make setup-mojo     # one-time: install the Mojo toolchain (pixi) into mojo_env/
make build-mojo     # compile mojo/engine → mojo_build/simulate
make test-mojo      # smoke test: runs a simulation, prints engine=<ver> mean=<value>
```

Point the API at the binary and start it:

```bash
export MOJO_BINARY_PATH="$PWD/mojo_build/simulate"
# start the API (Docker Compose, or your dev server) — the pool spins up on boot
```

{% endtab %}
{% endtabs %}

The pool size defaults to `cpu_count - 1`; set `MOJO_POOL_SIZE` to pin it. On startup the API runs a **server-mode probe** (it computes a known payload and checks the result is correct, not just that a socket opened), then logs `mojo_runtime_mode="pool"` when the real engine is live.

## Confirm it's on the fast path

{% stepper %}
{% step %}

### Check the engine status

```bash
curl http://localhost:8000/v1/infrastructure
```

Look at `engine_mode`. **`pool`** means the warm Mojo pool is serving requests (what you want). `subprocess_fallback` means it degraded to per-request processes; `unavailable` means no engine.
{% endstep %}

{% step %}

### Run a real simulation and read the mode

```bash
curl -X POST http://localhost:8000/v1/simulate \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"auto","scenario":{"variables":{"x":{"low":50,"high":150}},"objective":"maximize_net_value"},"runs":100,"seed":42}'
```

The response reports `engine_mode`; the result must carry real statistics (a non-zero `summary.mean`).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Expected result** — `/v1/infrastructure` shows `engine_mode: pool`, the simulate call returns a decision envelope with real stats, and the API logs include `mojo_pool_started` + `mojo_runtime_mode="pool"`. The sidecar engine is live. Full verification options are on [Engine health & verification](/run-the-engine/health.md).
{% endhint %}

## Fallback policy — fail fast in production

Whether the API may leave the pool is governed by **`RUNTIME_FALLBACK_MODE`**:

| Value   | Behavior                                                              | Use for           |
| ------- | --------------------------------------------------------------------- | ----------------- |
| `deny`  | Hard-fail at startup if the pool can't start — never silently degrade | **Production**    |
| `allow` | Permit the slower subprocess path when the pool is unavailable        | Self-hosted dev   |
| `auto`  | Fallback allowed only in development                                  | Local development |

`MOJO_ALLOW_SUBPROCESS_FALLBACK=false` additionally forbids the per-request subprocess path. For production, set both so a broken engine surfaces immediately instead of running slow:

```bash
RUNTIME_FALLBACK_MODE=deny
MOJO_ALLOW_SUBPROCESS_FALLBACK=false
MOJO_BINARY_PATH=/app/mojo_build/simulate
MOJO_POOL_SIZE=4
```

## Fix what's most likely to break

## Next

{% content-ref url="/pages/l0L6fUVZOMtx6UivtoX2" %}
[Engine health & verification](/run-the-engine/health.md)
{% endcontent-ref %}

{% content-ref url="/pages/TlbRNJamu0V9gxrwgIF7" %}
[Filtered & selective install](/run-the-engine/filtered-install.md)
{% endcontent-ref %}

{% content-ref url="/pages/WxWxFc47iyZNfwK18Gl7" %}
[How the engine works](/run-the-engine/engine.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.algenta.ai/run-the-engine/mojo-sidecar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.