Git Daemon

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.

What it does

• 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)
• Open a repo in the OS file browser, terminal, or VS Code (with approvals)
• Install dependencies with safer defaults (--ignore-scripts by default)

Security model (high level)

• 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

Requirements

• Node.js (for running the daemon)
• Git (for clone/fetch/branches/status/summary)
• Optional: code CLI for VS Code, pnpm/yarn for dependency installs

Install

npm install

Run the daemon

npm run daemon

The daemon listens on http://127.0.0.1:8790 by default, and can also expose HTTPS on https://127.0.0.1:8791 when enabled.

HTTPS support

The daemon can also listen on HTTPS (with a locally-trusted certificate).

Generate a local cert/key (requires mkcert):

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):

{
  "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 sets NODE_EXTRA_CA_CERTS unless you disable it with MKCERT_AUTO_TRUST=0.

Setup workspace root

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. For development, you can also run npm run setup:dev.

Non-interactive setup (no TTY):

GIT_DAEMON_WORKSPACE_ROOT=/absolute/path npm run setup

Or:

npm run setup -- --workspace=/absolute/path

Verbose logging options:

• GIT_DAEMON_LOG_STDOUT=1 to mirror logs to stdout
• GIT_DAEMON_LOG_PRETTY=0 to disable pretty formatting when stdout is enabled
• GIT_DAEMON_LOG_LEVEL=debug to increase verbosity

Pairing flow

Pairing is required before using protected endpoints.

1. Start pairing:

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:

curl -H "Origin: https://app.example.com" \
  -H "Content-Type: application/json" \
  -d '{"step":"confirm","code":"<CODE>"}' \
  http://127.0.0.1:8790/v1/pair

The response includes accessToken to use as Authorization: Bearer <token>.

Example usage

Check meta:

curl -H "Origin: https://app.example.com" \
  http://127.0.0.1:8790/v1/meta

Clone a repo (job):

curl -X POST \
  -H "Origin: https://app.example.com" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"[email protected]:owner/repo.git","destRelative":"owner/repo"}' \
  http://127.0.0.1:8790/v1/git/clone

Stream job logs (SSE):

curl -N \
  -H "Origin: https://app.example.com" \
  -H "Authorization: Bearer <TOKEN>" \
  http://127.0.0.1:8790/v1/jobs/<JOB_ID>/stream

List branches (local + remote by default):

curl -H "Origin: https://app.example.com" \
  -H "Authorization: Bearer <TOKEN>" \
  "http://127.0.0.1:8790/v1/git/branches?repoPath=owner/repo"

Status summary (UI-friendly):

curl -H "Origin: https://app.example.com" \
  -H "Authorization: Bearer <TOKEN>" \
  "http://127.0.0.1:8790/v1/git/summary?repoPath=owner/repo"

Configuration

Config is stored in OS-specific directories:

• macOS: ~/Library/Application Support/Git Daemon
• Linux: ~/.config/git-daemon
• Windows: %APPDATA%\\Git Daemon

You can override the config directory with:

GIT_DAEMON_CONFIG_DIR=/path/to/config npm run daemon

Key settings live in config.json:

• originAllowlist: array of allowed UI origins
• workspaceRoot: absolute path to the workspace root
• deps.defaultSafer: defaults to true for --ignore-scripts
• jobs.maxConcurrent and jobs.timeoutSeconds

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.

Development

Run tests:

npm test

Lint:

npm run lint

API reference

See openapi.yaml for the full contract.

UI developer resources

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).