Deployment Profiles

Deployment Profiles

aindy-runtime supports four deployment profiles. The profile determines which infrastructure dependencies are required, how background leadership works, and what sandbox policy applies to third-party plugins.

Profiles at a Glance

Profile	Process role	Redis	Worker	Stability
single-instance	api	optional	no	stable
distributed-api	api	required	required	stable
distributed-worker	worker	required	—	stable
hostile-third-party	api	required	required	experimental

single-instance

The default profile for development and small deployments. The API process handles all execution in-process using thread-based scheduling. Redis is optional — without it, WAIT/RESUME events are local-only and will not propagate across multiple instances.

# .env
EXECUTION_MODE=thread
# REDIS_URL optional

Suitable for: local development, single-server production, running the platform UI.

Not suitable for: high-throughput workloads that need horizontal scaling.

distributed-api

The API process in a multi-process topology. Requires Redis for the job queue and cross-instance event bus. At least one distributed-worker process must be running and heartbeating before the API will report ready.

# .env — API process
EXECUTION_MODE=distributed
REDIS_URL=redis://redis:6379/0
AINDY_DEPLOYMENT_PROFILE=distributed-api

# docker compose
docker compose --profile full up -d

The API elects a scheduler leader via a Redis lease. Only the elected leader runs background maintenance jobs (stuck-run recovery, effect record TTL cleanup).

distributed-worker

The async background worker process. Consumes jobs from the Redis queue — memory ingestion, metric writing, and any jobs submitted via sys.v1.job.submit.

# docker compose starts the worker automatically with --profile full
# Or run directly:
aindy-runtime worker

The worker participates in the same scheduler leadership election as the API.

hostile-third-party

An experimental profile for deployments that run untrusted third-party plugin code. Requires:

• strong_sandbox_vm runner
• Pinned sandbox runtime identity
• Verified host attestation at startup
• Hard resource limits enforced by the sandbox VM

This profile is not yet certified for production. It requires a Linux host with compatible strong sandbox VM support. See Security for the full sandbox policy.

AINDY_DEPLOYMENT_PROFILE=hostile-third-party
AINDY_PLUGIN_SANDBOX_RUNNER=strong_sandbox_vm
AINDY_PLUGIN_STRONG_SANDBOX_IMAGE=your-sandbox-image:pinned

Profile Auto-Detection

If AINDY_DEPLOYMENT_PROFILE is not set, the profile is inferred from EXECUTION_MODE:

• EXECUTION_MODE=thread → single-instance
• EXECUTION_MODE=distributed → distributed-api (API) or distributed-worker (worker)

Boot Modes

Independent of the deployment profile, you can control which app plugins load at boot:

AINDY_BOOT_MODE	Effect
unset	Full boot — loads all registered app plugins from aindy_plugins.json
runtime-only	Platform-only boot — no app plugins loaded; only core runtime routes

Runtime-only mode is useful when running the runtime as a standalone platform without domain apps. All core syscalls, flows, memory, and the platform UI remain available.

Scheduler Role

Within a running deployment, each process instance is assigned a scheduler role:

Role	Meaning
disabled	No background scheduler running
leader	Elected via Redis lease — runs maintenance jobs
follower	Standby — takes over if leader lease expires

In single-instance mode the API is always the leader (in-process, no lease needed).