@kdtix-open/sdlca-bridge

npx-ready installer for the sdlca-bridge local execution bridge.

The local execution bridge connects the hosted SDLC Automated orchestrator at dev.projectit.ai to AI provider CLIs (claude, codex, copilot, cursor) running on your machine.

Quick start (fresh machine)

npx @kdtix-open/sdlca-bridge install

This single command:

1. Creates ~/.sdlca/bridge/ with credentials and config
2. Registers a launchd agent (macOS) or systemd-user service (Linux/WSL2)
3. Starts the bridge so the orchestrator can reach your local AI providers

Generated setup files

install creates these files under ~/.sdlca/bridge/ without overwriting operator edits:

| File | Purpose | |---|---| | ~/.sdlca/bridge/.env.credentials | Real local credentials. The installer creates or preserves SDLCA_LOCAL_EXECUTION_BRIDGE_TOKEN for loopback bridge and MCP auth. | | ~/.sdlca/bridge/.env.credentials.example | Commented copy/paste reference for provider keys, GitHub role tokens, and hosted polling credentials. | | ~/.sdlca/bridge/config.json | Active bridge runtime config. Fresh installs keep static-token transition mode enabled while OIDC rollout is in progress. | | ~/.sdlca/bridge/config.json.example | Copy/paste reference for Mac/WSL bridge identity and hosted polling settings. | | ~/.sdlca/bridge/SETUP.md | Local first-install checklist and token separation notes. |

To generate a replacement local bridge token from bash or zsh:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

Keep SDLCA_HOSTED_API_TOKEN separate from SDLCA_LOCAL_EXECUTION_BRIDGE_TOKEN. The local token is only for loopback bridge/MCP calls and must not be reused for hosted work-claim polling.

Hosted work-claim token

SDLCA_HOSTED_API_TOKEN is not generated by sdlca-bridge install. It is a hosted repo-orchestrator ingress secret created by the platform/operator. Each bridge host gets one token in its own ~/.sdlca/bridge/.env.credentials; the hosted Docker app authorizes all current bridge-host tokens through SDLCA_HOSTED_API_TOKENS in the repo-root .env.credentials file.

Generate one high-entropy value per hosted environment:

node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))"

Provisioning flow:

1. Set all authorized hosted bridge tokens on the hosted app/container environment as a comma-separated SDLCA_HOSTED_API_TOKENS list.
2. Set non-secret hosted bridge routing knobs such as SDLCA_HOSTED_BRIDGE_EXECUTION and SDLCA_HOSTED_BRIDGE_ALLOW_CONCURRENT in the hosted app's .env.settings/.env.docker.
3. Redeploy or recreate the hosted control plane so env changes are loaded.
4. Add one authorized value to the greenlit bridge host's ~/.sdlca/bridge/.env.credentials.
5. Set SDLCA_HOSTED_CONTROL_PLANE_URL=https://dev.projectit.ai/tools/repo-orchestrator and SDLCA_HOSTED_WORK_CLAIM_POLLING=true on that bridge host.
6. Restart that bridge and confirm hosted polling logs appear.

For split Mac/WSL UAT, give each bridge a unique SDLCA_BRIDGE_ID or config.json bridgeId such as mac-local and wsl-ubuntu-26-04. The hosted orchestrator routes by targetBridgeId; the bridge only needs to poll with its own id and token.

Use one polling bridge at a time during UAT unless distinct identities and claim ownership have already been proven.

One-line installer script

npx is the supported install path today. A ProjectIT-hosted shell installer is a good future convenience path for fresh WSL/macOS machines, with this shape:

curl -fsSL https://dev.projectit.ai/install/sdlca-bridge | bash

Do not pipe the bridge installer to sudo bash. The bridge is a per-user service that writes ~/.sdlca/bridge/; running the whole installer as root can create root-owned credentials and the wrong supervisor registration. If a script needs root for prerequisites, it should call sudo only for those package-manager steps and keep bridge install/configuration under the target user.

For safer review before execution:

curl -fsSL https://dev.projectit.ai/install/sdlca-bridge -o /tmp/sdlca-bridge-install.sh
less /tmp/sdlca-bridge-install.sh
bash /tmp/sdlca-bridge-install.sh

Requirements

| | | |---|---| | Node | ≥ 20 | | macOS | 12 Monterey + (launchd) | | Linux/WSL2 | systemd-user available |

All commands

npx @kdtix-open/sdlca-bridge install       # Install + register bridge with OS supervisor
npx @kdtix-open/sdlca-bridge start         # Start bridge via OS supervisor
npx @kdtix-open/sdlca-bridge stop          # Stop bridge
npx @kdtix-open/sdlca-bridge restart       # Restart bridge
npx @kdtix-open/sdlca-bridge status        # Show lifecycle status (supervisor + health)
npx @kdtix-open/sdlca-bridge status --json # Machine-readable status
npx @kdtix-open/sdlca-bridge uninstall     # Remove bridge from OS supervisor
npx @kdtix-open/sdlca-bridge login         # Authenticate via OIDC device flow
npx @kdtix-open/sdlca-bridge logout        # Revoke authentication
npx @kdtix-open/sdlca-bridge auth status   # Show authentication state
npx @kdtix-open/sdlca-bridge providers list  # List detected AI providers
npx @kdtix-open/sdlca-bridge providers verify # Verify provider CLI availability
npx @kdtix-open/sdlca-bridge verify pipeline --allow-live-providers # Run live full-matrix verification
npx @kdtix-open/sdlca-bridge verify pipeline --allow-live-providers --allow-copilot # Include Copilot intentionally
npx @kdtix-open/sdlca-bridge mcp serve --detach # Register the MCP server; detached mode defaults read-only
npx @kdtix-open/sdlca-bridge doctor        # Local-environment sanity sweep
npx @kdtix-open/sdlca-bridge health        # Probe bridge /health endpoint
npx @kdtix-open/sdlca-bridge --version     # Print installed version
npx @kdtix-open/sdlca-bridge --help        # Show full usage

Version-pinning with npx

To run a specific version without globally installing:

npx @kdtix-open/[email protected] install

This always uses the exact pinned version regardless of any global install.

Global install (optional)

If you prefer a persistent global install:

npm install -g @kdtix-open/sdlca-bridge
sdlca-bridge install

WSL2 notes

WSL2 does not run a full systemd session by default. Enable it by adding to /etc/wsl.conf inside your distro and restarting WSL:

[boot]
systemd=true

wsl --shutdown

Then run the installer as normal. Also enable linger so the bridge stays alive after your last WSL terminal closes:

loginctl enable-linger "$USER"

Helpful WSL Ubuntu provider setup references used during UAT:

| Tool | Reference | |---|---| | Node.js / npm prerequisite | https://linuxcapable.com/how-to-install-node-js-on-ubuntu-linux/ | | GitHub CLI (gh) | https://linuxcapable.com/how-to-install-github-cli-on-ubuntu-linux/ | | Codex CLI | https://linuxcapable.com/how-to-install-codex-cli-on-ubuntu-linux/ | | Claude Code | https://linuxcapable.com/how-to-install-claude-code-on-ubuntu-linux/ | | Cursor and Cursor Agent | https://linuxcapable.com/how-to-install-cursor-on-ubuntu-linux/ | | GitHub Copilot CLI | https://linuxcapable.com/how-to-install-github-copilot-cli-on-ubuntu-linux/ |

How it works

@kdtix-open/sdlca-bridge is a thin CLI whose install verb:

1. Detects the host platform (macOS/Linux/WSL2)
2. Generates a unique bridge token and writes it to ~/.sdlca/bridge/
3. Renders the appropriate service template (launchd plist or systemd unit)
4. Registers and starts the background service
5. Polls localhost:4318/health until the bridge reports healthy

The bridge itself is a local HTTP server (port 4318) that the orchestrator contacts over a secure tunnel to run AI provider CLI commands on your behalf. Copilot runs in a bridge-managed per-repo COPILOT_HOME; the bridge seeds that home from the dedicated Copilot auth token instead of invoking the deprecated copilot --config-dir flag.

Security

• The bridge token is stored only in ~/.sdlca/bridge/ with mode 600
• No secrets are committed to source control
• Detached MCP runs read-only unless SDLCA_BRIDGE_READ_ONLY=false is set intentionally
• Full pipeline verification requires --allow-live-providers; Copilot additionally requires --allow-copilot
• Pipeline progress forwarding is restricted to the configured SDLCA_HOSTED_CONTROL_PLANE_URL origin
• OIDC authentication is required for strict hosted work-claim mode; transition mode supports static local tokens during rollout

License

BSL-1.1 — see LICENSE

Source & issues

• Repository: https://github.com/kdtix-open/agent-project-queue
• Issues: https://github.com/kdtix-open/agent-project-queue/issues
• Package directory: packaging/sdlca-bridge-npm/