> 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 Install the published Algenta clients or run the self-hosted engine. Pick your path, install in one command where a public package exists, and verify it. This page covers the supported public install paths: the self-hosted service, Python HTTP SDK, TypeScript SDK, and MCP server. 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) | | Use the self-hosted control-plane CLI | Installed automatically with the service | [Control-plane CLI](#control-plane-cli) | | Run the bundled native runtime from Python or a terminal | `pip install algenta` | [Local native runtime](#local-native-runtime) | | 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** and its lifecycle is part of Algenta. To confirm the integrated runtime is healthy, see [Verify the bundled engine](/engine-runtime/bundled-runtime.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 pinned Algenta images from `ghcr.io/thyn-ai/algenta` 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='' 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/thyn-ai/algenta` | Image registry and repository. | | `ALGENTA_SKIP_IMAGE_PULL` | `0` | Set to `1` to skip `compose pull` (use an already-pulled image). | ### Pin a specific build and bind a non-default port ```bash ALGENTA_VERSION=v1.0.0 \ ALGENTA_IMAGE_TAG=v1.0.0 \ ALGENTA_API_PORT=8080 \ bash -c "curl -sSL https://algenta.ai/install.sh | bash" ``` {% 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 %} ## Control-plane CLI The self-hosted installer creates `$HOME/.algenta/bin/de` and links it at `$HOME/.local/bin/de`. It forwards your API key into the existing API container; there is no second Python or engine installation. ```bash export PATH="$HOME/.local/bin:$PATH" export ALGENTA_API_KEY='' de health de account me --format json ``` `algenta-sdk` does not install `de`. See [Command-line interfaces](/sdks/cli.md) for the exact ownership boundary. ## Local native runtime `pip install algenta` installs the CLI, the Python SDK and the native runtime together on Python 3.12 or newer. Do not install `algenta-runtime-native` directly. The runtime carries its own Python, so it runs the same under any supported interpreter. | Platform | Requirements | Acceleration | | ---------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | | macOS on Apple silicon | macOS 13 or newer | Metal on macOS 26 or newer | | Linux x86-64 | glibc 2.34+ (e.g. Ubuntu 22.04+, Debian 12+, RHEL 9, Amazon Linux 2023), x86-64-v3 CPU (AVX2) | NVIDIA CUDA: T4, A100, L4, H100/H200 | | Linux arm64 | glibc 2.34+, Armv8.2 CPU (Neoverse N1 or newer) | CPU only | There is no fallback build: on any other platform (Windows, Intel Macs, macOS before 13, musl-based Linux such as Alpine, glibc older than 2.34) `pip install algenta` fails at install time. pip cannot check the CPU floor, so `algenta runtime doctor` runs a real kernel and names the installed runtime wheel with its floors. ```bash python3 -m venv .venv source .venv/bin/activate pip install algenta algenta runtime doctor algenta simulate algenta benchmark ``` The first execution includes process startup. Subsequent executions reuse one private Unix-domain worker; no TCP service or separately managed daemon is required. ## 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 Install the TypeScript SDK from npm for a clean-machine Node.js integration. ```bash npm install algenta-sdk ``` Repository contributors can still build from source with `pnpm install` and `pnpm --filter algenta-sdk build`. ### Verify the TypeScript SDK In a workspace build, 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 ``` ### Alternative: install with pip into the current environment ```bash pip 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 Streamable HTTP 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/getting-started/install.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.