Setup Reference

Everything on this page is optional reading — Setup covers the normal path.

Host-managed setup

Run everything directly on your host instead of inside the devcontainer. You need Git, Node.js 24, Python 3.13, and Docker (for Postgres, Redis, and MinIO).

Run the contributor bootstrap. It configures origin as your fork and upstream as eesi-ai/eesi, initializes the pipecat submodule, creates the Python venv, and copies the .env templates:

bash scripts/setup_fork.sh

.\scripts\setup_fork.ps1

Activate the virtual environment:

source venv/bin/activate

.\venv\Scripts\Activate.ps1

Install Python requirements:

bash scripts/setup_requirements.sh --dev

.\scripts\setup_requirements.ps1 -Dev

Install UI dependencies (make sure node --version reports 24, e.g. via nvm use 24):

cd ui && npm install && cd ..

Start Postgres, Redis, MinIO, Ollama, and Speaches, then the app:

make dev

Or step by step: make infra, make infra-init, make wait, make backend, make ui. See make help.

Open http://localhost:3000.

Devcontainer internals

The checked-in .devcontainer/ follows the Dev Containers specification, so it should also work in Cursor, JetBrains IDEs, and other compatible editors. Only the VS Code path is actively tested — if something breaks elsewhere, please open a GitHub issue.

What the bootstrap does

While the container starts, the devcontainer will:

Initialize the pipecat git submodule on the host through initializeCommand
Bring up postgres, redis, minio, ollama, and speaches through Docker Compose and wait for them to be healthy
Run one-shot ollama-init and speaches-init jobs to pull the default LLM, STT, and TTS models before the workspace starts
Seed the venv named volume from the image-baked Python 3.13 venv
Reinstall pipecat as editable from the bind-mounted submodule so source edits take effect
Create api/.env, api/.env.test, and ui/.env from their *.example templates if they do not already exist
Run npm ci for ui/ and api/mcp_server/ts_validator/

In the API env files, localhost for Postgres, Redis, and MinIO is rewritten to the docker network aliases postgres, redis, and minio. MINIO_PUBLIC_ENDPOINT deliberately stays on localhost because the browser on your host loads from it.

If you already had an api/.env or api/.env.test from host-managed development with localhost hosts for Postgres, Redis, or MinIO, the bootstrap leaves it untouched. Edit those URLs to the docker network aliases before starting the backend inside the devcontainer, or delete the file and let the bootstrap recreate it on the next rebuild.

When to rebuild the container

The workspace bind mount and the venv / node_modules named volumes persist across container restarts, so you rarely need to rebuild. Rebuild only when one of these changes:

.devcontainer/Dockerfile or .devcontainer/devcontainer.json
api/pyproject.toml or api/uv.lock
The pipecat/ submodule

Plain source edits, ui/package.json, and the .env.example templates do not require a rebuild. After a git pull, a quick check:

git diff HEAD@{1} HEAD -- .devcontainer api/pyproject.toml api/uv.lock pipecat

If the diff is empty, you can keep your current container.

Personal install hook

Anything you install inside the container outside the named volumes, notably under /home/vscode, is wiped on rebuild. This includes npm i -g packages and tools like the Claude or Codex CLIs. To reinstall personal tooling automatically on every rebuild, drop an executable script at .devcontainer/install.local.sh. It is gitignored and runs at the tail of the post-create bootstrap. Example:

#!/usr/bin/env bash
set -euo pipefail

command -v claude >/dev/null 2>&1 || curl -fsSL https://claude.ai/install.sh | bash
command -v codex  >/dev/null 2>&1 || npm i -g @openai/codex

Keep entries idempotent with command -v or a marker file so re-runs are cheap and safe.

Dev Container CLI

To use the devcontainer without VS Code, install the CLI once on your host (requires Node.js):

npm install -g @devcontainers/cli

Start or rebuild the container from the repository root:

devcontainer up --workspace-folder .

Open a shell in the running workspace container:

devcontainer exec --workspace-folder . bash

Run a one-off command from the host, e.g. starting the backend or the UI:

devcontainer exec --workspace-folder . bash scripts/start_services_dev.sh
devcontainer exec --workspace-folder . bash -lc 'cd ui && npm run dev -- --hostname 0.0.0.0'

Fork and upstream remotes

The contributor bootstrap (scripts/setup_fork.sh) configures two remotes:

origin: your fork, where you push
upstream: eesi-ai/eesi, where new commits land

If you cloned eesi-ai/eesi directly instead of your fork, run it once (inside the devcontainer is fine):

bash scripts/setup_fork.sh

To pull in upstream changes:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Check your remotes any time with git remote -v. You should see:

origin    https://github.com/<YOUR_HANDLE>/eesi.git (fetch/push)
upstream  https://github.com/eesi-ai/eesi.git    (fetch/push)

Always push feature branches to origin (your fork), then open a pull request against eesi-ai/eesi:main. Never push directly to upstream.

Contribution

Guides

SDKs

Deployment

Setup Reference

Host-managed setup

Devcontainer internals

What the bootstrap does

When to rebuild the container

Personal install hook

Dev Container CLI

Fork and upstream remotes

​Host-managed setup

​Devcontainer internals

​What the bootstrap does

​When to rebuild the container

​Personal install hook

​Dev Container CLI

​Fork and upstream remotes

Host-managed setup

Devcontainer internals

What the bootstrap does

When to rebuild the container

Personal install hook

Dev Container CLI

Fork and upstream remotes