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.

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.

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
Use the self-hosted control-plane CLI	Installed automatically with the service	Control-plane CLI
Run the bundled native runtime from Python or a terminal	pip install algenta	Local native runtime
Call a running Algenta API from Python	pip install algenta-sdk	Python SDK
Call a running Algenta API from TypeScript or JavaScript	npm install algenta-sdk	TypeScript SDK
Expose Algenta as MCP tools to Cursor or Claude Desktop	pipx install algenta-mcp	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.

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.

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.

1

Run the installer

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.

2

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.

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).

3

Verify the install

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

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

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

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

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
  }'

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.

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

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"

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.

Manage the stack

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

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

If you are on the standalone binary, substitute docker-compose for docker compose.

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.

export PATH="$HOME/.local/bin:$PATH"
export ALGENTA_API_KEY='<your key>'
de health
de account me --format json

algenta-sdk does not install de. See Command-line interfaces 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.

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.

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.

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,
)

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.

TypeScript SDK

Install the TypeScript SDK from npm for a clean-machine Node.js integration.

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.

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,
});

The package requires Node 18 or newer.

MCP server

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

1

Install the server

Install it as an isolated CLI with pipx:

pipx install algenta-mcp

Alternative: install with pip into the current environment

pip install algenta-mcp

2

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:

algenta-mcp --mode http --port 8001

3

Wire it into Cursor or Claude Desktop

Add this to your MCP config (Cursor ~/.cursor/mcp.json, or Claude Desktop claude_desktop_config.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.

Next steps

The install is done. Before production, walk through the operator checklist below, then continue to the quickstart for a first end-to-end decision.

• 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.

QuickstartSelf-hostingAuthentication & API keysPython SDK