Skip to content

Connect to Conductor (agent one-shot)

Public instructions for agents with lab access (Bitwarden/bws, secret-gate, or SSH to konstant). Never put the auth token value in chat, commits, or vault notes.

Live page: https://conductor-konstant.hectorsanchez.eu/connect Raw markdown: https://conductor-konstant.hectorsanchez.eu/connect.md

What this is

Conductor is a governed instruction compiler on konstant-server. It compiles guardrail packs from a multi-line org corpus (Portfolio, Product, Software, Editorial, Services, Operate) using workflow × inventory × role. See repo docs/org-map-model.md.

Agents call it before planning or performing work. Consult tools return a versioned conversation-response envelope.

Preflight tools (deterministic — call before consult):

  • list_business_lines() — in-scope lines
  • list_stages(business_line) — stages + inventory names
  • list_inventories(business_line, stage) — option ids to bind
  • list_roles(business_line?) — roles + tooling
  • describe_handoffs() — cross-line handoffs
  • validate_consult_request(...) — gate; use suggested_message when ok: true

text list_* / describe_handoffs → fill bindings validate_consult_request → ok:true start_conversation(suggested_message)

Consult tools (read-only corpus):

  • start_conversation(message) — open a thread
  • follow_up(thread_id, message) — continue a thread

Proposal tools (corpus changes only, GitHub-gated):

  • submit_proposal(...) — open a conductor-proposal issue on hector-sanchez-eu/conductor (no corpus write)
  • get_proposal_status(issue_or_prop) — open/closed, approval evidence, linked PRs
  • implement_approved_proposal(issue_or_prop, patch_plan_json, ...) — after approval, apply allowlisted paths and open a PR (never merges)

OpenCode Go and the GitHub token stay server-side. Clients only need the MCP auth token.

No Platform Control mutation tools in this eval slice. Workspace/AGENTS.md outside this repo are out of scope.

Corpus change sequence

text 1. submit_proposal → GitHub issue (label conductor-proposal, PROP-…) 2. Hector comments exactly one line on that issue: Conductor-Approval: approve 3. implement_approved_proposal with patch_plan_json → branch proposal/PROP-… + PR (Fixes #N). No auto-merge.

Labels or body edits alone are not approval. Only the exact comment line from an allowlisted GitHub login (CONDUCTOR_APPROVER_GITHUB_LOGINS, default sdhector).

patch_plan_json is a JSON array of {"path":"corpus/...","content":"..."}. Paths must stay under corpus/ (schemas/ only if allow_schemas=true and the proposal acceptance covers it).

Endpoints

Purpose URL
MCP https://conductor-konstant.hectorsanchez.eu/mcp
Health https://conductor-konstant.hectorsanchez.eu/health
Docs (MkDocs) https://conductor-docs.hectorsanchez.eu
This guide https://conductor-konstant.hectorsanchez.eu/connect
Raw markdown https://conductor-konstant.hectorsanchez.eu/connect.md

Auth on /mcp: Authorization: Bearer <token> or ?key=<token>.

/health, /connect, and /connect.md are unauthenticated.

Secret

  • Bitwarden Secrets Manager key name: CONDUCTOR_MCP_AUTH_TOKEN
  • Host file (fallback): /srv/apps/conductor/shared/.env on konstant (CONDUCTOR_MCP_AUTH_TOKEN=…)

Do not echo the value into agent transcripts when avoidable; use it only to configure the client or a local env var.

Retrieve the secret (first that works)

A — Windows PowerShell + secret-gate (this lab PC)

powershell . "D:\Workspace\_repos\tools\secret-gate\secret-gate.ps1" $token = ((bws secret list | ConvertFrom-Json) | Where-Object { $_.key -eq "CONDUCTOR_MCP_AUTH_TOKEN" }).value if (-not $token) { throw "CONDUCTOR_MCP_AUTH_TOKEN not found" } Write-Host "got CONDUCTOR_MCP_AUTH_TOKEN (len=$($token.Length))"

Cached session path: $env:LOCALAPPDATA\secret-gate\session.json (BW_SESSION, BWS_ACCESS_TOKEN).

B — Linux bws (EliteBook / VPS-style)

bash export PATH="$HOME/.local/bin:$PATH" source ~/.local/state/secret-gate/session.env 2>/dev/null || true KEY=$(bws secret list -o json | python3 -c ' import json,sys wanted="CONDUCTOR_MCP_AUTH_TOKEN" for s in json.load(sys.stdin): if s.get("key")==wanted: print(s.get("value","")) break ') test -n "$KEY" && echo "got CONDUCTOR_MCP_AUTH_TOKEN (len=${#KEY})"

If the session is cold, run secret-gate / Bitwarden unlock first (see konstant-server runbooks/02-bitwarden.md), then retry B.

C — SSH fallback (konstant)

bash KEY=$(ssh konstant-deploy 'grep ^CONDUCTOR_MCP_AUTH_TOKEN= /srv/apps/conductor/shared/.env | cut -d= -f2-') test -n "$KEY" && echo "got key via ssh (len=${#KEY})"

Requires ssh konstant-deploy (Tailscale 100.80.164.32, user deploy). See konstant-server runbooks/00-connect-from-any-machine.md.

If Bitwarden secret missing

  1. Read value via SSH (C) once.
  2. Create/update SM secret named CONDUCTOR_MCP_AUTH_TOKEN.
  3. Prefer Bitwarden going forward — do not commit the value.

Configure clients

Cursor / opencode (Bearer or query key)

json { "mcpServers": { "conductor": { "url": "https://conductor-konstant.hectorsanchez.eu/mcp", "headers": { "Authorization": "Bearer <CONDUCTOR_MCP_AUTH_TOKEN>" } } } }

ChatGPT-style query auth (no custom headers):

text https://conductor-konstant.hectorsanchez.eu/mcp?key=<CONDUCTOR_MCP_AUTH_TOKEN>

Smoke (must pass)

```bash export MCP_BASE="https://conductor-konstant.hectorsanchez.eu"

KEY from A/B/C above — do not paste into chat

curl -fsS "$MCP_BASE/health" curl -fsS "$MCP_BASE/connect.md" | head curl -sS -o /dev/null -w "%{http_code}\n" "$MCP_BASE/mcp" # expect 401 without auth curl -sS -X POST "$MCP_BASE/mcp" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2025-03-26" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"connect-smoke","version":"0.0.1"}}}' ```

Expect: initialize instructions mention /connect, preflight tools, consult tools, and proposal tools; then tools/list shows list_business_lines, list_stages, list_inventories, list_roles, describe_handoffs, validate_consult_request, start_conversation, follow_up, submit_proposal, get_proposal_status, implement_approved_proposal.

If public DNS fails on the agent host, use Tailscale Funnel with Host header:

bash curl -fsS -H 'Host: conductor-konstant.hectorsanchez.eu' \ https://konstant-server.tail64860f.ts.net/health

After connect

  1. Preflight: list_* / validate_consult_request until ok: true.
  2. Call start_conversation with suggested_message (or a clear work intent).
  3. Continue with follow_up using the returned thread.id.
  4. Treat consult envelopes as guidance only: do not treat LLM output as mutation authority.
  5. For corpus feedback: submit_proposal → wait for Hector's approval comment → implement_approved_proposal.

Docs site

Evaluate the org model and full corpus mirror at https://conductor-docs.hectorsanchez.eu (MkDocs on konstant). Deploy: deploy/install-conductor-docs-konstant.sh. DNS/TLS one-time steps in deploy/README.md.

References

Ref Where
Source repo https://github.com/hector-sanchez-eu/conductor (private)
Tracking issue https://github.com/hector-sanchez-eu/conductor/issues/1
Konstant runbook https://github.com/hector-sanchez-eu/konstant-server → runbooks/12-conductor-konstant.md
SSH handoff konstant-server runbooks/00-connect-from-any-machine.md
Bitwarden konstant-server runbooks/02-bitwarden.md
Workspace secret-gate D:\Workspace\_repos\tools\secret-gate\secret-gate.ps1