Installation

Alquimia Platform is distributed as three components: the Python SDK (alquimia-core), the HTTP service (alquimia-runtime), and the web-based management interface (alquimia-studio). Choose the installation path that matches how you plan to use the platform.

Note

Public access to the source repositories is not required to use Alquimia Platform. Enterprise distributions include Docker images, tarballs, and package indexes. Contact the Alquimia team if you need access artifacts.

alquimia-core (Python SDK)

Install the SDK when you want to embed agent execution in a Python application or prototype locally.

Requirements: Python 3.12 exactly (==3.12.*).

Choose an install profile

Install command	Capabilities
pip install alquimia-core	Base install (no LLM or tool execution)
pip install "alquimia-core[core]"	Full agent runtime: LLMs, MCP tools, vector stores, Redis memory
pip install "alquimia-core[cli]"	Command-line interface
pip install "alquimia-core[core,cli,registry]"	Recommended for local development
pip install "alquimia-core[core,cli,registry,security,identity,aws,tools,leviathan]"	Everything

The [core] extra includes LangChain, Redis, Qdrant, MCP, Llama Stack, and scikit-learn. The [cli] extra adds Click, Rich, and tiktoken.

Verify the installation

alquimia --help
python -c "import alquimia.core; print('ok')"

alquimia-runtime (HTTP service)

The runtime is distributed as a Docker image. For local development, use Docker Compose to start the runtime together with Kafka, PostgreSQL, Redis, Qdrant, MinIO, Vault, and an OCI registry.

Required secrets

Before starting the runtime, set these secrets in your environment or .env file:

Secret	Purpose
API_TOKEN	Bearer token for authenticated endpoints
POSTGRES_USERNAME / POSTGRES_PASSWORD	PostgreSQL credentials
VAULT_TOKEN	Scoped Vault token for registry secret resolution
BLOB_S3_ACCESS_KEY / BLOB_S3_SECRET_KEY	S3-compatible blob storage credentials
KAFKA_SIGNING_KEY	64-character hex key shared across all runtime instances

Generate signing and encryption keys with:

python -c "import secrets; print(secrets.token_hex(32))"

Start the full local stack

docker compose up

The master listens on port 8080 by default. Workers expose only health probes on the same port and are not publicly routed.

Verify the runtime

curl http://localhost:8080/health/readiness
# → OK

Then open the interactive API documentation at http://localhost:8080/docs.

Local development overlays

Overlay	Command	Purpose
Hot-reload	docker compose -f docker-compose.yml -f docker-compose.dev.yml up	Mount source directories for live code changes
Ollama + TEI	make run-with-ollama	Run with a local LLM and embeddings
vLLM	make run-with-vllm	Run with a vLLM endpoint
Keycloak + SPIRE	docker compose -f docker-compose.yml -f docker-compose.local.yml up	Develop with Zero Trust identity

Deploy to Railway

You can also run Alquimia Platform on Railway using the official one-click template. Railway provisions the runtime and its supporting services and handles builds, networking, and persistent storage for you.

Required variables

The template prompts for the same core secrets as a local Docker Compose deployment. Set these in the Railway dashboard before the first deploy:

Secret	Purpose
API_TOKEN	Bearer token for authenticated runtime endpoints
POSTGRES_USERNAME / POSTGRES_PASSWORD	PostgreSQL credentials created by the Railway database
VAULT_TOKEN	Scoped Vault token for registry secret resolution
BLOB_S3_ACCESS_KEY / BLOB_S3_SECRET_KEY	S3-compatible blob storage credentials
KAFKA_SIGNING_KEY	64-character hex key shared across all runtime instances

Generate signing and encryption keys with:

python -c "import secrets; print(secrets.token_hex(32))"

Tip

Railway can inject environment variables from its managed PostgreSQL, Redis, and MinIO services. Reference the connection variables provided by each service (for example, ${{Postgres.DATABASE_URL}}) so you do not have to hard-code hostnames.

Verify the deployment

Once the template finishes deploying, open the public alquimia-runtime service URL and check the readiness endpoint:

curl https://<your-railway-domain>/health/readiness
# → OK

Then open the interactive API documentation at https://<your-railway-domain>/docs.

For production deployments, see the Kubernetes & OpenShift guide.

alquimia-studio (web UI)

Alquimia Studio is the visual management layer for the platform. It is a Next.js application that connects to an existing alquimia-runtime deployment and lets you design, test, publish, and operate agents through a web interface.

Prerequisites

• Node.js 18+ and Yarn
• MongoDB instance, or set DB_STRATEGY=lite to use embedded NeDB with no external database
• Keycloak instance, or set AUTH_STRATEGY=lite for self-contained authentication
• A running alquimia-runtime deployment and API key

Install and run

# Clone the repository
git clone https://github.com/Alquimia-ai/studio.git
cd studio

# Install dependencies
yarn install

# Configure environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
yarn dev

Open http://localhost:3000 to access Studio.

Required environment variables

Variable	Purpose
DB_STRATEGY	mongo (default) or lite for embedded NeDB
MONGODB_URI	MongoDB connection string when DB_STRATEGY=mongo
KEYCLOAK_ISSUER / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET	Keycloak authentication
NEXTAUTH_URL / NEXTAUTH_SECRET	NextAuth session configuration
ASSISTANT_BASEURL	URL of the alquimia-runtime service
ALQUIMIA_ASSISTANT_API_KEY	Runtime API token
NEXT_PUBLIC_DEFAULT_NAMESPACE	Default OCI namespace for publishing
KNOWLEDGE_BASE_API_URL / KNOWLEDGE_BASE_API_KEY	Knowledge base service (optional)

For the full configuration reference, telemetry options, and production build instructions, see the Studio overview.

Next steps

• Quickstart — run your first agent conversation.
• Docker Compose — run the full platform stack locally.
• Kubernetes & OpenShift — deploy to a cluster.
• Runtime configuration reference — full environment variable reference.