Skip to main content

Local setup

This page walks through bringing up Clone end-to-end on one machine. Each surface uses the package manager already in its directory — npm for the JS surfaces, uv for the Python server.

1. Clone​

git clone https://github.com/cloneisyou/clone.git
cd clone
cp .env.example .env
# Fill in ANTHROPIC_API_KEY, ELEVENLABS_API_KEY, etc.

2. Server​

cd apps/server
uv sync
uv run python manage.py migrate
uv run python manage.py createsuperuser     # optional
uv run python manage.py runserver 0.0.0.0:8001

The dev server uses SQLite by default (db.sqlite3). Production uses Postgres via DATABASE_URL.

3. Web​

cd apps/web
npm install
npm run dev    # http://localhost:5173/

Vite proxies /api to localhost:8001 (see apps/web/vite.config.ts); do not change that target without coordinating with the server side.

4. MCP​

cd apps/mcp
npm install

# Either issue an API key from the running server, or grab a JWT from POST /api/auth/login/
export CLONE_API_URL=http://localhost:8001
export CLONE_API_TOKEN=<dev key or JWT>

npm run dev      # stdio (matches Claude Code launch)
# OR
MCP_TRANSPORT=http PORT=3000 npm run dev   # http (matches production)

To hook the local MCP into Claude Code:

claude mcp add clone-dev -- node $(pwd)/apps/mcp/dist/index.js \
  -e CLONE_API_URL=http://localhost:8001 \
  -e CLONE_API_TOKEN=<dev key or JWT>

Run npm run build after editing MCP source so the dist bundle is fresh.

5. Desktop​

cd apps/desktop
git submodule update --init --recursive
uv venv --python 3.13
uv pip install -e ".[windows]"   # or .[macos] depending on platform
uv run python -m desktop          # tray loads
uv run python -m pytest tests/    # unit + 5 MB byte-equal mock-server loopback

6. Docs (this site)​

cd apps/docs
npm install
npm run dev      # http://localhost:3000/docs/
npm run build    # writes to apps/docs/build/

End-to-end smoke test​

With the server running on localhost:8001 and an API key exported as CLONE_API_TOKEN:

# Record an event.
curl -sS -X POST http://localhost:8001/api/recording/events/ \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" -H "Content-Type: application/json" \
  -d '[{"id":"evt-smoke","session_id":"smoke","occurred_at":"2026-05-05T12:00:00Z","source":"agent","source_detail":"claude-code","type":"agent.prompt","agent":"Claude Code","prompt":"hello"}]'

# Predict.
curl -sS -X POST http://localhost:8001/api/predictions/predict/ \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"agent":"Claude Code","agent_input":"hello","k":3,"threshold":0.8}'

Both calls should return 200/201 with sensible JSON.