Self Hosted

Self-Hosted — the endpoint model

Every example, default, and piece of documentation in this repository resolves its Algenta endpoint from your own self-hosted engine — over its public HTTP/MCP APIs. Nothing here defaults to, or silently falls back to, an Algenta-hosted cloud endpoint. Where you run the engine — your laptop, your datacenter, your cloud account — is your choice; the packages only require that it is reachable over the network.

Endpoint resolution order

Every package resolves the endpoint the same way, in this order:

1. base_url= passed explicitly to the constructor/factory,
2. the ALGENTA_BASE_URL environment variable,
3. a localhost fallback for a local self-hosted engine.

Package kind	Fallback	Note
MCP-based packages (LangChain, LlamaIndex, Pydantic AI, MAF, Haystack, Vercel AI SDK)	http://localhost:8000/mcp	The full MCP endpoint URL.
vllm-algenta	http://localhost:8000	The engine's bare HTTP origin — the package appends /v1 itself. Do not copy a /mcp-suffixed value into its environment.
n8n-nodes-algenta	http://localhost:8000	Set as Base URL on the credential; the node appends /mcp.
ray-serve-algenta	http://localhost:8000/mcp	Set ALGENTA_BASE_URL explicitly — serve run binds Ray Serve's own proxy to localhost:8000, so an unset variable makes the proxy forward every request to itself.
litellm-algenta	none baked in	Generated configs resolve ALGENTA_MCP_URL / ALGENTA_MCP_TOKEN from the gateway's environment at litellm startup via os.environ/... — never literal values in a file.

litellm-algenta's linter additionally flags any URL that looks Algenta-hosted (algenta.ai), even in a hand-written config.

Why there is no hosted fallback

This is a deliberate difference from the algenta-sdk client these packages build on, whose AlgentaClient defaults to the hosted https://api.algenta.ai for a zero-config quickstart. These integrations never use that default: the endpoint resolves from base_url= / ALGENTA_BASE_URL (with the localhost fallback above), full stop. algenta-tools (Vercel AI SDK) goes so far as to define its own DEFAULT_ALGENTA_BASE_URL = "http://localhost:8000/mcp" rather than import the SDK's hosted constants — reusing them would silently point every unconfigured caller at Algenta's cloud. The same reasoning is why several packages declare no algenta-sdk dependency at all.

Two surfaces: MCP and HTTP

A self-hosted engine exposes two public surfaces; which one a package uses depends on its job.

• MCP — http://<engine>/mcp (stateless Streamable HTTP). The governed tool surface: get_contract … execute_decision. Every tool-calling integration talks here. Statelessness is what makes horizontal scale-out safe (see RayServe): no session is pinned to the connection that created it, so any replica can serve any request.
• OpenAI-compatible HTTP — http://<engine>/v1/chat/completions and /v1/responses. The engine's own LLM API, used by vLLM and any standard openai client. Every route requires an authenticated, org-bound caller identity — vllm-algenta treats ALGENTA_API_KEY as required (no fallback, a clear error if unset) rather than sending a placeholder that would 401 deep inside an HTTP call.

For the MCP surface, whether your engine requires a bearer credential depends on your deployment; the packages forward whatever auth you configure. litellm-algenta's README documents the gateway-side auth types (bearer_token, oauth2, true_passthrough, …) and their token-expiry behavior in detail.

Enforcement stays on the engine

Profile boundaries are enforced client-side by the in-process packages (the model never sees a tool outside its profile), and gateway-side by LiteLLM's allowed_tools / allowed_params — but the execute profile's real gates (operator enablement, role check, logged decision_id, the three named policy gates) are enforced by the engine, server-side, in every case. See Tool Contract.

The engine and its kernels

The Algenta engine is closed source and lives in a separate, private repository; its compute kernels are proprietary Mojo, distributed with the engine as signed wheels. None of that code is in this repository — the integrations are ordinary Python and TypeScript, Apache-2.0, talking to the engine only through the public surfaces above. See also thyn-ai/algenta-sdk (the client SDK) and thyn-ai/mojo-kernels (clean-room Mojo kernels for popular Python/TS libraries).