Install & prerequisites

This page gets the local stack running. By the end you have the orchestrator, worker, Postgres, and Redis up under Docker, ready for the sessions in the following steps.

Prerequisites

• Docker with the docker compose plugin (or docker-compose v2). The stack runs entirely in containers.
• just — the operator command runner the stack uses. On macOS: brew install just.

Clone the repo

git clone https://github.com/descoped/apomesh.git
cd apomesh

Every command below runs from the repo root unless stated otherwise.

How local config is split

apomesh keeps local configuration in two homes, split by one question — is this value the same for every developer, or specific to your machine?

• deploy/local/ (tracked in the repo) holds the fixed, same-for-everyone config: the Docker Compose stack, the daemon config profile, and the provider skeleton. No secrets.
• ~/.apomesh/env (outside the repo) holds your per-operator values — provider credentials and machine-specific knobs. The stack loads this file into both daemons automatically; you never export secrets into your shell.

You don’t create ~/.apomesh/env yet — the first session needs no credentials. The local stack guide covers this split in depth.

Materialize local config

The tracked config lives as neutral *.example skeletons. just bootstrap copies each one to its real, git-ignored counterpart — the daemon config profile, the provider profile, and the per-tenant provider files — without clobbering any edits you’ve made:

just bootstrap

just bootstrap is idempotent and runs automatically as part of just up, so you rarely call it directly. It’s shown here so you know what the next step materializes.

Bring the stack up

just build-images   # build the orchestrator + worker images
just up             # start the stack (detached)

just build-images compiles the orchestrator and worker into Docker images. Run it before your first just up, and again whenever you change orchestrator or worker code — bringing the stack up does not rebuild stale images on its own.

just up bootstraps config, then starts Postgres (with pgvector), Redis, one orchestrator, and one worker. The orchestrator listens on 127.0.0.1:50051 for gRPC and 127.0.0.1:50052 for REST.

Tail the logs to watch it come up:

just logs orchestrator

To stop the stack (keeping data) run just down; to stop and wipe the Postgres and Redis volumes run just nuke.

Note

With no provider credential configured, the stack comes up healthy but can’t run a live LLM session yet — that’s the real-provider step. The next step needs no stack and no keys at all.

Next

Run your first session with no API keys.