Clone the three services, set their variables and bring the whole assistant up with one command. In Standalone mode it runs complete on your machine with Docker Compose.
Engine 24+
v2
3.12
2.40+
The integrated startup connects the three services over a shared Docker network (soma-stack-net) and resolves them by relative path. Clone them into the same parent directory:
mkdir soma && cd soma git clone https://github.com/somatechlat/somafractalmemory git clone https://github.com/somatechlat/somabrain git clone https://github.com/somatechlat/somaagent01
SomaFractalMemory runs on its own. Starting it first makes the persistence endpoint ready for the other services.
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
Vector memory and the brain share 768 dimensions. Set the vector in SomaFractalMemory; set the default tenant in SomaAgent01.
SOMA_VECTOR_DIM=768 SOMA_DB_USER=somafractalmemory SOMA_DB_NAME=somafractalmemory SOMA_API_TOKEN=<generated-token>
SomaBrain reaches the memory by its service name on the network and publishes health on port 30101.
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
SomaAgent01 exposes the API and the WebUI. The model key lives in Vault at secret/agent/api_keys and the service resolves it at runtime.
cd somaagent01/infra/standalone cp .env.example .env # edit .env: VAULT_TOKEN_TTL_HOURS and 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/
Shortcut · the whole assistant in one command
With the three repositories as siblings and their .env configured, up-cluster.sh creates the shared network, brings up memory → brain → orchestrator and waits until all three are healthy:
./up-cluster.sh # status: ./up-cluster.sh --status # stop: ./up-cluster.sh --down
If the three endpoints respond, your assistant is running.
curl localhost:10101/healthz curl localhost:10101/readyz
curl localhost:30101/health curl localhost:30101/stats
curl localhost:20020/api/health/ curl localhost:20020/api/
It is almost always an embedding-dimension mismatch. Check that the three services share 768 (MEM_EMBED_DIM · EMBED_DIM · SOMA_VECTOR_DIM) and restart.
Confirm that the three repositories are in the same parent directory and that SomaBrain and SomaFractalMemory are healthy before starting the orchestrator. Check docker compose logs and the soma-stack-net network.
The token (SOMA_API_TOKEN) and the tenant (X-Soma-Tenant) must match between SomaBrain and SomaFractalMemory. Check that the --env-file is loaded in both.
The assistant is up but the model is not receiving the retrieved context. Check the model key in Vault (secret/agent/api_keys) and that orchestration is calling working memory.