 [](https://www.npmjs.com/package/git-daemon)
npm install git-daemon!Git Daemon logo

Git Daemon is a local Node.js service that exposes a small, authenticated HTTP API for a trusted web UI to perform Git and developer convenience actions on your machine. It is designed to run on 127.0.0.1 only, enforce a strict Origin allowlist, and sandbox all filesystem access to a configured workspace root.
- Clone, fetch, list branches, and read Git status using your system Git credentials
- Provide a status summary for UI badges/tooltips
- Stream long-running job logs via Server-Sent Events (SSE)
- Run user-defined healthchecks and return normalized results
- Open a repo in the OS file browser, terminal, or VS Code (with approvals)
- Install dependencies with safer defaults (--ignore-scripts by default)
Healthchecks are user-supplied executables/scripts stored in local suites (which can be
private repos). The daemon runs them as jobs, streams logs over SSE, and returns a
normalized status (na, failed, pass-partial, pass-full) plus details. Suites are
configured via local paths, and each check has a healthcheck.json manifest. For a
quick demo, set healthchecks.demo: true in config to auto-enable the bundled example
suite (when present).
- Loopback-only: binds to 127.0.0.1
- Origin allowlist: every request must include a matching Origin
- DNS rebinding protections: verifies Host and remote loopback address
- Pairing token: required for all non-public endpoints
- Workspace sandbox: all paths must resolve inside the configured root
- Capability approvals: required for open-terminal/open-vscode/deps install
- Node.js (for running the daemon)
- Git (for clone/fetch/branches/status/summary)
- Optional: code CLI for VS Code, pnpm/yarn for dependency installs
``bash`
npm install
`bash`
npm run daemon
The daemon listens on http://127.0.0.1:8790 by default, and can also exposehttps://127.0.0.1:8791
HTTPS on when enabled.
The daemon can also listen on HTTPS (with a locally-trusted certificate).
Generate a local cert/key (requires mkcert):
`bash`
npm run cert:local
This writes certs under your daemon config directory (e.g. ~/Library/Preferences/Git Daemon/certs on macOS).
Then update your config (example):
`json`
{
"server": {
"host": "127.0.0.1",
"port": 8790,
"https": {
"enabled": true,
"port": 8791,
"keyPath": "/absolute/path/to/certs/localhost-key.pem",
"certPath": "/absolute/path/to/certs/localhost.pem"
}
}
}
For HTTPS test clones, npm run test:clone auto-detects mkcert and setsNODE_EXTRA_CA_CERTS unless you disable it with MKCERT_AUTO_TRUST=0.
`bash`
npm run setup
This prompts for an absolute workspace root path and saves it to your config. The prompt reads from the terminal directly (via /dev/tty on macOS/Linux) so it still works in many IDE run configurations.npm run setup:dev
For development, you can also run .
Non-interactive setup (no TTY):
`bash`
GIT_DAEMON_WORKSPACE_ROOT=/absolute/path npm run setup
Or:
`bash`
npm run setup -- --workspace=/absolute/path
Verbose logging options:
- GIT_DAEMON_LOG_STDOUT=1 to mirror logs to stdoutGIT_DAEMON_LOG_PRETTY=0
- to disable pretty formatting when stdout is enabledGIT_DAEMON_LOG_LEVEL=debug
- to increase verbosity
Pairing is required before using protected endpoints.
1. Start pairing:
`bash`
curl -H "Origin: https://app.example.com" \
-H "Content-Type: application/json" \
-d '{"step":"start"}' \
http://127.0.0.1:8790/v1/pair
2. Confirm pairing with the code:
`bash
curl -H "Origin: https://app.example.com" \
-H "Content-Type: application/json" \
-d '{"step":"confirm","code":""}' \`
http://127.0.0.1:8790/v1/pair
The response includes accessToken to use as Authorization: Bearer .
Check meta:
`bash`
curl -H "Origin: https://app.example.com" \
http://127.0.0.1:8790/v1/meta
Clone a repo (job):
`bash`
curl -X POST \
-H "Origin: https://app.example.com" \
-H "Authorization: Bearer
-H "Content-Type: application/json" \
-d '{"repoUrl":"git@github.com:owner/repo.git","destRelative":"owner/repo"}' \
http://127.0.0.1:8790/v1/git/clone
Stream job logs (SSE):
`bash`
curl -N \
-H "Origin: https://app.example.com" \
-H "Authorization: Bearer
http://127.0.0.1:8790/v1/jobs/
List branches (local + remote by default):
`bash`
curl -H "Origin: https://app.example.com" \
-H "Authorization: Bearer
"http://127.0.0.1:8790/v1/git/branches?repoPath=owner/repo"
Status summary (UI-friendly):
`bash`
curl -H "Origin: https://app.example.com" \
-H "Authorization: Bearer
"http://127.0.0.1:8790/v1/git/summary?repoPath=owner/repo"
Run healthchecks (job):
`bash`
curl -X POST \
-H "Origin: https://app.example.com" \
-H "Authorization: Bearer
-H "Content-Type: application/json" \
-d '{"repoPath":"owner/repo","checks":[{"suiteId":"team-default","checkId":"lint","config":{"strict":true}}]}' \
http://127.0.0.1:8790/v1/healthchecks/run
Fetch healthcheck results:
`bash`
curl -H "Origin: https://app.example.com" \
-H "Authorization: Bearer
http://127.0.0.1:8790/v1/healthchecks/jobs/
List healthchecks (flat):
`bash`
curl -H "Origin: https://app.example.com" \
-H "Authorization: Bearer
"http://127.0.0.1:8790/v1/healthchecks?flat=true"
Config is stored in OS-specific directories:
- macOS: ~/Library/Application Support/Git Daemon~/.config/git-daemon
- Linux: %APPDATA%\\Git Daemon
- Windows:
You can override the config directory with:
`bash`
GIT_DAEMON_CONFIG_DIR=/path/to/config npm run daemon
Key settings live in config.json:
- originAllowlist: array of allowed UI originsworkspaceRoot
- : absolute path to the workspace rootdeps.defaultSafer
- : defaults to true for --ignore-scriptsjobs.maxConcurrent
- and jobs.timeoutSecondshealthchecks.suites
- : array of absolute or config-relative suite pathshealthchecks.demo
- : enable bundled example healthchecks if present
Tokens are stored (hashed) in tokens.json. Logs are written under the configured logging.directory with rotation.
Approvals can be scoped per repo or origin-wide. To allow a capability for all repos
from an origin, set "repoPath": null in an approvals entry. When a TTY is
available, the daemon will prompt for approval on first use.
Run tests:
`bash`
npm test
Lint:
`bash`
npm run lint
See openapi.yaml for the full contract.
This repo already includes the artifacts needed to build or test a UI client:
- openapi.yaml: full HTTP contract (routes, schemas, error codes).design.md
- : security model, runtime decisions, and behavior expectations.config.schema.json`: shape of the daemon config (useful for tooling or UI settings screens).
-