@kdtix-open/sdlca-bridge

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

License: BUSL-1.1 — see the repository License Boundary Catalog.

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.

Forensic execution policy

Forensic execution is enabled by default, including when SDLCA_BRIDGE_FORENSIC_ENABLED is absent. To disable this privileged execution path for a specific bridge, add the following explicit opt-out to ~/.sdlca/bridge/.env.credentials:

SDLCA_BRIDGE_FORENSIC_ENABLED=false

Then restart and verify the bridge:

sdlca-bridge restart
sdlca-bridge status --json
sdlca-bridge health --json

Absent, empty, or true enables forensic execution. false disables it (case-insensitive). Any other value makes startup fail rather than silently leaving a mistyped policy in effect.

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.

OIDC bridge authentication

OIDC is the forward path for hosted bridge authentication. Static SDLCA_HOSTED_API_TOKEN polling still works while oidcTransition is true, but operators should verify OIDC readiness before switching a bridge or hosted control plane to strict mode.

1. Confirm the issuer discovery document resolves:

   curl -fsS https://auth.projectit.ai/.well-known/openid-configuration | jq .issuer

2. If this environment uses a different issuer, edit ~/.sdlca/bridge/config.json and set both oidc.discoveryUrl and oidc.clientId. The default client is sdlca-bridge and the default scopes are openid profile bridge:work.

3. Run the local readiness sweep:

   sdlca-bridge doctor --json | jq '.checks[] | select(.name=="oidc-discovery")'

   pass means the discovery document is reachable and contains the required device-flow, token, and JWKS endpoints. warn means discovery failed while static-token transition mode is still enabled. fail means discovery failed in strict OIDC mode or the local OIDC config is invalid.

4. Complete the device flow:

   sdlca-bridge login
   sdlca-bridge auth status --json

   Expected non-secret evidence: status is authenticated/active, scopes include bridge:work, and the bridge identity matches this host.

5. Restart and verify the bridge:

   sdlca-bridge restart
   sdlca-bridge status --json
   sdlca-bridge health --json

Do not paste tokens, refresh tokens, or credential-file contents into UAT reports. If auth.projectit.ai does not resolve, classify it as an issuer/DNS infrastructure blocker; it is not a local provider CLI failure.

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 <provider> # Verify ACP adapter launch and initialize
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

providers verify <provider> is a non-mutating ACP readiness check: it launches the provider's local ACP adapter and requires the JSON-RPC initialize handshake to complete. A detected provider CLI alone is not a passing verification, and this command does not create a provider session or send a model prompt.

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

BUSL-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/