Setup

IntraCord is a Next.js UI (ui/), a FastAPI backend (api/), and a Pipecat-based voice pipeline (pipecat/, a git submodule), backed by Postgres, Redis, and MinIO.

✓

Using Claude Code or Codex? Install the IntraCord setup skill (/plugin marketplace add IntraCord-hq/IntraCord-plugins, then /plugin install IntraCord@IntraCord) and ask your agent to "set up IntraCord for development" — it runs the steps below for you and verifies the stack is healthy.

Set up

You need Git, a local Docker engine (such as Docker Desktop), and VS Code with the Dev Containers extension.

1. Fork IntraCord-hq/IntraCord and clone your fork:

git clone https://github.com/<YOUR_HANDLE>/IntraCord
cd IntraCord

2. Open the folder in VS Code and run Dev Containers: Reopen in Container. The first build takes several minutes — it starts Postgres, Redis, and MinIO, seeds the Python venv, creates the .env files, and installs UI dependencies. Later opens are fast.

3. Start the backend from a terminal inside the container. The script waits for the health check and prints a status summary, so when it exits successfully the backend is up:

bash scripts/start_services_dev.sh

4. Start the UI from a second terminal inside the container:

cd ui && npm run dev -- --hostname 0.0.0.0

5. Open the app at http://localhost:3000.

If these steps do not work for you, please open an issue on GitHub.

Cloned IntraCord-hq/IntraCord directly instead of your fork?

Run bash scripts/setup_fork.sh once. It prompts for your fork URL, points origin at it, and adds upstream as IntraCord-hq/IntraCord. See Fork and upstream remotes.

No VS Code? No devcontainer at all?

The devcontainer also runs headless via the Dev Container CLI, or you can run everything directly on your host.

Daily workflow

What	How
Restart the backend	Re-run bash scripts/start_services_dev.sh — it stops the old processes first
Stop the backend	bash scripts/stop_services.sh
Backend logs	tail -f logs/latest/*.log
Code reload	Edits under api/ auto-reload; ari_manager, campaign_orchestrator, and arq need a backend restart
Rebuild the container	Only when .devcontainer/, api/requirements*.txt, or pipecat/ change — plain source edits never need it
Sync the pipecat submodule	git submodule update --init --recursive after pulling a submodule bump

Debugging

The repo ships debug configurations in .vscode/launch.json for every backend service and for pytest. To run under the debugger instead of the start script:

1. Stop the script-managed backend if it is running, so the ports are free:

bash scripts/stop_services.sh

2. In VS Code's Run and Debug panel, pick a configuration and press F5:

Configuration	What it runs
API: Uvicorn (reload)	The FastAPI backend, with auto-reload (port from UVICORN_PORT in api/.env, default 8000)
API: Arq worker (watch) / API: Campaign orchestrator / API: ARI manager	The other backend services — launch them alongside Uvicorn as needed
Tests: API (pytest, full suite / current file)	pytest under the debugger, against api/.env.test
Tests: Pipecat (pytest, current file) / Python: Current file	Debug a pipecat test or any standalone script

All configurations load api/.env (test configs use api/.env.test) and set justMyCode: false, so you can step into FastAPI and pipecat code — breakpoints in the pipecat/ submodule work because it is installed editable. Inside the devcontainer the Python interpreter is preselected; on a host-managed setup, pick ./venv/bin/python via Python: Select Interpreter first.

Repository layout

Path	What's there
ui/	Next.js frontend — the workflow builder, dashboard, and agent editor
api/	FastAPI backend — REST API, campaign orchestration, telephony, ARQ background workers
pipecat/	Git submodule for the voice pipeline (STT → LLM → TTS)
docs/	This Docusaurus documentation site, written in MDX, previewed with npm start
sdk/	Python/TypeScript SDKs for driving IntraCord programmatically
scripts/	Setup, deployment, and update scripts
deploy/	nginx and coturn config templates used by remote deployment

Contributing a change

1. Create a branch and make your change.
2. Push to your fork (origin) and open a pull request against IntraCord-hq/IntraCord:main.
3. A maintainer reviews and merges.

Bug reports and feature ideas go through GitHub Issues and Ideas. Issues tagged good first issue are a good place to start. For questions while you're working, use the IntraCord Community Slack.

Deploying your own build instead of contributing upstream? See Deployments instead.