Deploying Locally

This guide takes you from a fresh clone to a running Cosmos platform on your machine, using Docker Compose through the ./manage.sh CLI.

Prerequisites

• Docker Desktop, or Docker Engine with the Compose plugin, with at least 8 GB of RAM allocated
• Git
• bash (Git Bash on Windows, or use manage.bat)
• Node.js and npm, only if you work on the frontend outside Docker. The frontend needs Node.js 22.13 or later.

Step 1: Clone and bootstrap

git clone https://github.com/ey-org/cosmos-platform.git
cd cosmos-platform
./scripts/bootstrap.sh

The bootstrap script:

• makes sure Git uses HTTPS GitHub URLs,
• checks out the service repositories for the selected profiles,
• installs the shared git hooks, and
• runs npm install for the frontend when its dependencies are missing or out of date.

Bootstrap profiles

The default profile is core. Add profiles with --profile (repeatable):

./scripts/bootstrap.sh --profile all
./scripts/bootstrap.sh --profile knowledge --profile observability
./scripts/bootstrap.sh --list-profiles

Other options: --hooks-only, --submodules-only, --skip-url-config, and --quiet.

Step 2: Handle a corporate proxy (if needed)

If your network inspects SSL traffic, Docker builds fail with certificate errors. Run once:

./scripts/setup-certs.sh

This copies your corporate CA certificates into local-dev/certs/, which the Dockerfiles install during builds. If the script finds nothing, ask IT for the .crt file and place it in local-dev/certs/ yourself. The directory is not committed.

Step 3: Create the environment file

./manage.sh dev setup-env

This creates .env.dev from .env.example and replaces each replace-me value with a random local secret. It never changes an existing .env.dev. manage.sh also creates the file if start, setup, watch, reset, restart or build finds none.

For the Azure or GCP stack, run ./manage.sh azure setup-env (or gcp). It copies .env.azure.example (or .env.gcp.example) once and lists the replace-me values you still need to set. For Azure, set AZURITE_ACCOUNT_KEY to the published Azurite account key. ./manage.sh <env> setup stops while any of those values remain.

manage.sh loads .env.<env> before it calls Docker Compose. In the dev environment it also loads .env.dev.local if present, which is a good place for personal overrides. Keep real secrets and generated tokens out of version control.

Step 4: Choose an environment

All environments use the same local ports.

Step 5: Start the services

./manage.sh dev start

⚠️ The first run builds every image and can take 10–15 minutes.

This starts the default groups:

Check that they are healthy:

./manage.sh dev check     # health check
./manage.sh dev status    # running services and ports

Step 6: Run first-time setup

./manage.sh dev setup

Setup loads the default permissions, creates the default users and organization, syncs connector definitions (when tools-server and configurator-web are running), and generates the service tokens. Then restart the services that use the new tokens:

./manage.sh dev restart configurator-web tools-server adk

Check the tokens:

./manage.sh dev verify-tokens

To regenerate tokens later, run ./manage.sh dev setup-tokens and restart the same services.

Step 7: Open the platform

Sign in with the default admin user:

Run ./manage.sh dev credentials to see all default users and the default organization ID. For a tour of the UI, see Getting Started with Cosmos.

Step 8: Call the APIs

Get an access token:

curl -s -X POST http://localhost:8101/api/v1/users/login/ \
    -H 'Content-Type: application/json' \
    -d '{"email":"admin@cosmos.dev","password":"admin123"}' | jq -r '.access_token'

./manage.sh dev get-token [EMAIL] does the same from the CLI.

Every API request except health checks needs both Authorization: Bearer <token> and X-Org-Id: <uuid>:

export TOKEN="<paste token here>"
export ORG_ID="87654321-4321-8765-4321-876543218765"   # default dev organization

# Health checks
curl -s http://localhost:8101/health/   # User Service
curl -s http://localhost:8100/health/   # Configurator
curl -s http://localhost:8102/health    # MCP Tools Server
curl -s http://localhost:8103/health    # ADK

# List tools through Configurator
curl -s http://localhost:8100/api/v1/tools/ \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Org-Id: $ORG_ID" | jq '.count'

# List tools through MCP
curl -s http://localhost:8102/tools/list/ \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Org-Id: $ORG_ID" | jq '.tools | length'

Starting Optional Services

Optional services are not started by default. Name them explicitly:

./manage.sh dev start voice                                # Voice
./manage.sh dev start knowledge                            # RAGFlow services
./manage.sh dev start observer-webserver observer-worker   # Observer
./manage.sh dev start pii-redactor                         # PII Redactor

./manage.sh dev start all starts the default groups only (infra, core, and ai).

The Frontend and In-App Docs

The frontend container runs the Next.js dev server (npm run dev) with hot reload on port 3000. The local cosmos-docs/ folder is mounted read-only into the container, so documentation edits appear in the in-app docs without a rebuild. See Frontend.

Hot Reload

./manage.sh dev watch   # sync file changes into containers

Day-to-Day Commands

./manage.sh dev restart adk                 # recreate a container (reloads env vars)
./manage.sh dev build adk                   # rebuild an image
./manage.sh dev logs adk tools-server       # follow logs
./manage.sh dev config -q                   # validate the compose model
./manage.sh dev shell tools-server          # open a shell in a container
./manage.sh dev stop                        # stop everything
./manage.sh dev reset                       # stop, remove volumes, start (destructive)

When to rebuild and when to restart:

• Environment or compose changes (variables, ports, mounts): validate with ./manage.sh dev config -q, then ./manage.sh dev restart <service>.
• Source changes in mounted code: rely on hot reload or watch mode.
• Dockerfile, dependency manifest, or lockfile changes: ./manage.sh dev build <service>, then ./manage.sh dev restart <service>.

⚠️ Always use ./manage.sh instead of docker compose directly. It loads .env.<env> and uses --force-recreate on restart. A plain docker restart does not reload environment variables.

See the manage.sh Reference for every command.

Troubleshooting

A service will not start, or authentication fails

./manage.sh dev setup-tokens
./manage.sh dev restart configurator-web tools-server adk
./manage.sh dev verify-tokens

Port conflict

lsof -i :8100
./manage.sh dev stop

Docker build SSL errors

./scripts/setup-certs.sh
./manage.sh dev build <service>

A service repository is missing

./scripts/bootstrap.sh --profile <profile>

Key gotchas

1. docker restart does not reload environment variables. Use ./manage.sh <env> restart.
2. Kafka address. Inside Docker, Kafka is kafka:9092. From your machine, use localhost:19092.
3. The frontend is the only UI path. Make sure the frontend container is running before you open http://localhost:3000.
4. Python dependencies live in the image. Each Python service builds its own virtual environment inside the image, and the compose files hide any host .venv. After a dependency change, rebuild the image with ./manage.sh dev build <service>.