> 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/getting-started/install.md).

# Install

This page gets Algenta onto your machine. It covers every install path: the self-hosted service (one command, Docker), the local runtime package, the HTTP SDKs for Python and TypeScript, and the MCP server for agent tools. Each section ends with a verification step so you know the install worked. Pick the path that matches what you are building; you do not need all of them.

{% hint style="info" %}
To make a first call against the self-hosted service, you do not need to install any SDK or Python package. The installer prints a ready-to-run `curl` command. Reach for an SDK only when you want typed responses and retries inside your application code.
{% endhint %}

## Choose an install path

| You want to...                                                                       | Install                       | Section                                         |
| ------------------------------------------------------------------------------------ | ----------------------------- | ----------------------------------------------- |
| Run the full Algenta service (API, worker, database, storage) locally or on a server | `curl ... install.sh \| bash` | [Self-hosted service](#self-hosted-service)     |
| Embed the deterministic runtime in a Python process                                  | `pip install algenta-core`    | [Local runtime package](#local-runtime-package) |
| Call a running Algenta API from Python                                               | `pip install algenta-sdk`     | [Python SDK](#python-sdk)                       |
| Call a running Algenta API from TypeScript or JavaScript                             | `npm install algenta-sdk`     | [TypeScript SDK](#typescript-sdk)               |
| Expose Algenta as MCP tools to Cursor or Claude Desktop                              | `pipx install algenta-mcp`    | [MCP server](#mcp-server)                       |

## Self-hosted service

The self-hosted service is the complete Algenta deployment: the API, the worker, Postgres, Redis, and MinIO object storage, wired together with Docker Compose. One command installs and starts everything.

{% hint style="info" %}
The compiled **Mojo engine ships inside the image** — the installer brings it up automatically. To confirm it's running on the fast worker pool (and to fix the build/startup issues you're most likely to hit), see [Run the Mojo engine](/run-the-engine/mojo-sidecar.md).
{% endhint %}

{% hint style="info" %}
**Prerequisites.** Docker, with the daemon running, plus Docker Compose. Either the Compose v2 plugin (`docker compose`) or the standalone `docker-compose` binary works; the installer detects whichever is present.
{% endhint %}

{% stepper %}
{% step %}

### Run the installer

```bash
curl -sSL https://algenta.ai/install.sh | bash
```

The installer:

1. Checks for Docker and Docker Compose and confirms the daemon is reachable.
2. Resolves a pinned release and writes the Compose bundle to `$HOME/.algenta`.
3. Generates a `.env` with stable secrets (kept owner-only at mode `600`).
4. Pulls the `ghcr.io/algenta/decision-engine` image and starts the stack.
5. Waits for the API, runs database migrations, and bootstraps an owner plus an API key.
   {% endstep %}

{% step %}

### Save the bootstrap key

When it finishes, the installer prints your API endpoint, your bootstrap API key, and a ready-to-run `curl` command. Save the API key.

{% hint style="warning" %}
The bootstrap API key is shown once. Copy it before you close the terminal. To recover from a lost key, rotate it (see [Next steps](#next-steps)).
{% endhint %}
{% endstep %}

{% step %}

### Verify the install

The liveness endpoint returns `{"status":"ok"}`:

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

```json
{ "status": "ok", "timestamp": "2026-06-20T00:00:00Z" }
```

Then run your first decision with the bootstrap key the installer printed.

```bash
export ALGENTA_API_KEY='<paste the bootstrap key>'

curl -X POST http://localhost:8000/v1/simulate \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "auto",
    "scenario": {
      "variables": {
        "revenue": { "low": 80000, "high": 200000 },
        "cost": { "low": 30000, "high": 90000 }
      },
      "objective": "maximize_net_value"
    },
    "runs": 10000,
    "seed": 42
  }'
```

{% hint style="success" %}
**Expected result** — the health check returns `{"status":"ok"}` and the simulate call returns a decision envelope (a `decision` plus a `summary`). Your engine is live.
{% endhint %}
{% endstep %}
{% endstepper %}

### Configure the install with environment variables

Set these before running the installer to control where it installs, which port it binds, and which image it pins.

| Variable                  | Default                           | Purpose                                                          |
| ------------------------- | --------------------------------- | ---------------------------------------------------------------- |
| `ALGENTA_DIR`             | `$HOME/.algenta`                  | Install directory. Holds `docker-compose.yml` and `.env`.        |
| `ALGENTA_API_PORT`        | `8000`                            | Host port the API binds to.                                      |
| `ALGENTA_VERSION`         | latest `main`                     | Release ref to pin. A git SHA or a release tag.                  |
| `ALGENTA_IMAGE_TAG`       | derived from the ref              | Exact image tag to pull.                                         |
| `ALGENTA_IMAGE_REGISTRY`  | `ghcr.io/algenta/decision-engine` | Image registry and repository.                                   |
| `ALGENTA_SKIP_IMAGE_PULL` | `0`                               | Set to `1` to skip `compose pull` (use an already-pulled image). |

{% hint style="danger" %}
The generated `.env` contains `ALGENTA_CONFIG_ENCRYPTION_KEY`, which encrypts every stored per-tenant provider key at rest. Back it up. If you reinstall over an existing database with a different key, the previously stored keys become undecryptable. Restore your prior key into `.env` before starting.
{% endhint %}

### Manage the stack

The installer prints these too. Run them from your install directory.

```bash
cd ~/.algenta && docker compose ps
cd ~/.algenta && docker compose logs -f api
cd ~/.algenta && docker compose pull && docker compose up -d   # upgrade
cd ~/.algenta && docker compose stop
```

{% hint style="info" %}
If you are on the standalone binary, substitute `docker-compose` for `docker compose`.
{% endhint %}

## Local runtime package

`algenta-core` is the Algenta runtime as a Python package. Use it to run deterministic resolve and query flows in-process, or to drive a remote API through one `Runtime` object.

{% tabs %}
{% tab title="Local only" %}

```bash
pip install algenta-core
```

This installs `algenta-core` with no external dependencies. It is enough for `Runtime(mode="local")` and the local Mojo libraries.
{% endtab %}

{% tab title="API-backed" %}
`Runtime(mode="api")` and `Runtime(mode="self_hosted")` fail closed unless `algenta-sdk` is installed. Add it with the `cloud` extra:

```bash
pip install "algenta-core[cloud]"
```

Or install the SDK directly:

```bash
pip install algenta-sdk
```

{% endtab %}
{% endtabs %}

### Verify the runtime package

`algenta-core` ships an `algenta` CLI. Confirm the install and inspect capabilities:

```bash
algenta version
```

Run the built-in demo:

```bash
algenta demo
```

Drive a remote engine from Python:

```python
import os
from algenta import Runtime

rt = Runtime(mode="api", api_key=os.environ["ALGENTA_API_KEY"])
plan = rt.resolve({"source_name": "orders", "metric": "revenue", "group_by": "product_line"})
result = rt.query(plan)
```

{% hint style="info" %}
Use Cloud Managed base URLs only with `Runtime(mode="api")`. For self-hosted deployments use `Runtime(mode="self_hosted")` with an explicit `base_url` and the API key your operator provisioned.
{% endhint %}

## Python SDK

`algenta-sdk` is the HTTP client for a running Algenta API. The installed import package is `decision_engine`.

```bash
pip install algenta-sdk
```

### Verify the Python SDK

The client reads `ALGENTA_API_KEY` from the environment and accepts a `base_url` for self-hosted deployments. `AlgentaClient` is the preferred name; `DecisionEngineClient` remains as a compatibility alias.

```python
import os
from decision_engine import AlgentaClient

client = AlgentaClient(
    api_key=os.environ["ALGENTA_API_KEY"],
    base_url="http://localhost:8000",
)

print(client.health())   # {'status': 'ok', 'timestamp': '...'}
print(client.version())  # {'api_version': '1.0.0', 'engine_version': '...', 'environment': '...'}

envelope = client.simulate(
    scenario={
        "variables": {
            "revenue": {"low": 80000, "high": 200000},
            "cost": {"low": 30000, "high": 90000},
        },
        "objective": "maximize_net_value",
    },
    runs=10000,
    seed=42,
)
```

{% hint style="warning" %}
If you call `AlgentaClient()` with no `api_key` and no `ALGENTA_API_KEY` set, construction raises immediately with a message telling you which environment variable to set. The legacy `DE_API_KEY` is also accepted.
{% endhint %}

## TypeScript SDK

The TypeScript SDK is published under the same name on npm.

```bash
npm install algenta-sdk
```

### Verify the TypeScript SDK

The client reads `ALGENTA_API_KEY` in Node, and takes `apiKey` and `baseUrl` in its config. `AlgentaClient` and `DecisionEngineClient` are both exported.

```typescript
import { AlgentaClient } from 'algenta-sdk';

const client = new AlgentaClient({
  apiKey: process.env.ALGENTA_API_KEY,
  baseUrl: 'http://localhost:8000',
});

console.log(await client.health());   // { status: 'ok', timestamp: '...' }
console.log(await client.version());  // { api_version: '1.0.0', engine_version: '...', environment: '...' }

const envelope = await client.simulate({
  mode: 'auto',
  scenario: {
    variables: {
      revenue: { low: 80000, high: 200000 },
      cost: { low: 30000, high: 90000 },
    },
    objective: 'maximize_net_value',
  },
  runs: 10000,
  seed: 42,
});
```

{% hint style="info" %}
The package requires Node 18 or newer.
{% endhint %}

## MCP server

`algenta-mcp` exposes the Algenta API as Model Context Protocol tools for Cursor, Claude Desktop, and other MCP clients.

{% stepper %}
{% step %}

### Install the server

Install it as an isolated CLI with `pipx`:

```bash
pipx install algenta-mcp
```

{% endstep %}

{% step %}

### Choose a transport

Point it at your deployment with `ALGENTA_BASE_URL` and `ALGENTA_API_KEY`. It runs the stdio transport by default. For HTTP/SSE clients, run it as a server:

```bash
algenta-mcp --mode http --port 8001
```

{% endstep %}

{% step %}

### Wire it into Cursor or Claude Desktop

Add this to your MCP config (Cursor `~/.cursor/mcp.json`, or Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "algenta": {
      "command": "algenta-mcp",
      "env": {
        "ALGENTA_BASE_URL": "http://localhost:8000",
        "ALGENTA_API_KEY": "de_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

The server connects your agent to governed dataset discovery, exact queries, deterministic utility-model routes, product helpers, simulations, and persisted agent runs.
{% endstep %}
{% endstepper %}

## Next steps

{% hint style="success" %}
The install is done. Before production, walk through the operator checklist below, then continue to the quickstart for a first end-to-end decision.
{% endhint %}

* Self-hosted operators: review `~/.algenta/.env` before production, set `ANTHROPIC_API_KEY` for the agentic repository flow, and put TLS in front of the API port.
* Rotate the bootstrap key with `POST /v1/api-keys` and a bounded `expires_at`, then store the returned `raw_key` (shown once) before revoking the bootstrap key.

{% content-ref url="/pages/bx4Gl5he2wFYtNEG4rAq" %}
[Quickstart](/getting-started/quickstart.md)
{% endcontent-ref %}

{% content-ref url="/pages/tWtESdNlxR5ZqT7F3czC" %}
[Self-hosting](/deploy-and-operate/self-hosting.md)
{% endcontent-ref %}

{% content-ref url="/pages/UvGGKnKB6EqDONoxZRyB" %}
[Authentication & API keys](/getting-started/authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/9i6iZAg7l3UEawtf7i4b" %}
[Python SDK](/sdks/python.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/getting-started/install.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.