Three paths to take the assistant to production: standalone for development, a Docker cluster with a shared network for staging, and Kubernetes with Helm for high availability.
One command per service with Docker Compose. Ideal for local development and integration testing.
02The three services on a shared soma-stack-net network. One coherent stack for staging.
03Helm charts with production-HA values to orchestrate the assistant at scale.
Common requirements
Each repository ships its own infra/standalone/docker-compose.yml with all its dependencies.
Brings up the API, PostgreSQL, Redis, etcd, MinIO and Milvus in a single command.
cd somafractalmemory # configure infra/standalone/.env: # SOMA_VAULT_TOKEN, SOMA_DB_PASSWORD, SOMA_API_TOKEN docker compose -f infra/standalone/docker-compose.yml \ --env-file infra/standalone/.env up -d curl http://localhost:10101/healthz
| Service | Image | Port | RAM |
|---|---|---|---|
| API | somafractalmemory-api | 10101 | 1 GB |
| PostgreSQL | postgres:15 | 10432 | 1.5 GB |
| Redis | redis:7 | 10379 | 512 MB |
| Milvus | milvusdb/milvus:v2.3.3 | 10530 | 6 GB |
| etcd / MinIO | etcd · minio | internal | 256 MB |
Deploys the brain with its Rust core, Kafka, OPA, Vault and observability.
cd somabrain cp infra/standalone/.env.example infra/standalone/.env # edit .env: SOMABRAIN_VAULT_TOKEN, POSTGRES_PASSWORD, # SOMABRAIN_JWT_SECRET, SOMABRAIN_MEMORY_HTTP_TOKEN docker compose -f infra/standalone/docker-compose.yml \ --env-file infra/standalone/.env up -d curl http://localhost:30101/health
The orchestrator with its own Vault. Model credentials live in Vault, managed by the service.
cd somaagent01/infra/standalone cp .env.example .env # edit .env: VAULT_TOKEN_TTL_HOURS, SA01_DEFAULT_TENANT_ID vault kv put secret/agent/api_keys groq_api_key='<your key>' docker compose up --build -d curl http://localhost:20020/api/health/
Connect the three services to the shared soma-stack-net network. Each repository includes an override that joins its stack to that network.
Create the network once and apply the override when bringing up each service. That way the orchestrator, the brain and the memory resolve each other by service name.
docker network create soma-stack-net
# In each repository (brain, memory, agent) docker compose \ -f infra/standalone/docker-compose.yml \ -f infra/standalone/docker-compose.shared-network.yml \ up -d
Or bring the whole assistant up in one command from SomaAgent01. up-cluster.sh creates the network and starts the three services in order, waiting for health between each.
./up-cluster.sh # status: ./up-cluster.sh --status # stop: ./up-cluster.sh --down
One host, local development.
The three services on soma-stack-net.
Memory 10xxx · Brain 30xxx · Orchestrator 20xxx
Each service includes a Helm chart and k8s/ manifests. Model secrets stay in Vault, inside the cluster.
helm install somafractalmemory ./helm \ -f helm/values-prod-ha.yaml \ --namespace somabrain --create-namespace
kubectl apply -f k8s/somaagent/
Model secrets
Provider credentials live in Vault, managed by the service. Cluster manifests stay clean of secrets.
vault kv put secret/agent/api_keys groq_api_key='<your key>'
docker compose -f infra/standalone/docker-compose.yml exec -T \
somafractalmemory-standalone-postgres \
pg_dump -U "${SOMA_DB_USER:-somafractalmemory}" \
"${SOMA_DB_NAME:-somafractalmemory}" > backup.sql
SOMA_API_TOKEN=$(openssl rand -hex 32)
The API is the only public endpoint. etcd and MinIO stay internal. Terminate TLS with a reverse proxy (nginx).
curl localhost:10101/healthz
# {"kv_store":true,"vector_store":true,"graph_store":true}
curl localhost:10101/readyz
curl localhost:10101/metrics
curl localhost:30101/health curl localhost:30101/stats
curl localhost:20020/api/health/ curl localhost:20020/api/
Standalone is ideal for development and integration testing. For staging and production use the cluster with a shared network or Kubernetes with Helm.
Provider keys live in Vault (secret/agent/api_keys) and are managed from the agent administration. Manifests and environment files stay clean of secrets.
768 across the three: SOMA_VECTOR_DIM in memory, EMBED_DIM in the brain and MEM_EMBED_DIM in the agent. The shared dimension keeps semantic recall precise.
Yes. Each service scales independently: memory grows with usage, the orchestrator with load. In Kubernetes, adjust replicas per chart.