local-env

Local environment — build and test actual-sync

Builds actual-sync from the local dev source and runs it against the local Actual Budget instance.

Paths

Every command below is written against two variables so nothing here hardcodes a machine-specific home directory. Set them once per shell:

# Where the local docker stacks live (adjust to your machine)
export LOCAL_ENV="$HOME/docker/librechat-MCP-actual"
# This repo checkout — from inside the repo, just use the git root
export REPO_ROOT="$(git rev-parse --show-toplevel)"

Environment layout

$LOCAL_ENV/
├── actual-sync/              ← builds from $REPO_ROOT
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── config/config.json   ← two servers: "Main's Budget" + "TEST BLANK"
└── Finance-actual-budget/   ← local Actual Budget server (port 5006)

The docker-compose.yml uses a build.context pointing at the local dev repo, so every docker compose up --build picks up uncommitted source changes.

Note: the repo is reachable at two paths on the dev machine (a Sync/… path and a dev-github-personal/… path). They resolve to the same checkout, not copies — readlink -f both if you need to confirm. Use $REPO_ROOT and the distinction stops mattering.

Start the local Actual Budget server (if not running)

cd "$LOCAL_ENV/Finance-actual-budget"
docker compose up -d

Actual Budget available at: http://localhost:5006

Build and start actual-sync from local source

cd "$LOCAL_ENV/actual-sync"
docker compose up --build -d

Dashboard: http://localhost:3000/dashboard Health: http://localhost:3000/health

Force a sync run (bypass scheduler)

# All servers
docker compose -f "$LOCAL_ENV/actual-sync/docker-compose.yml" \
  exec actual-sync node index.js --force-run

# One specific server
docker compose -f "$LOCAL_ENV/actual-sync/docker-compose.yml" \
  exec actual-sync node index.js --force-run --server "Main's Budget"

Validate config inside the container