Skip to content

setup.md

Latest commit

 

History

History
126 lines (82 loc) · 4.05 KB

setup.md

File metadata and controls

126 lines (82 loc) · 4.05 KB

Server Setup

Connect the agent to a Conductor server. Run through this once per environment.

Server resolution order

--profile > CONDUCTOR_SERVER_URL > CLI auto-detection of a local server started via conductor server start.

Most commands need no flags — the CLI finds the server automatically. Only append --profile {env} when the user mentions a named environment (dev, qa, prod, staging, uat). If unsure which profile exists, read ~/.conductor-cli/config.yaml and ask the user to confirm. Only create named profiles when the user explicitly wants to switch between multiple environments.

The Python fallback script (scripts/conductor_api.py) does not auto-detect — it requires CONDUCTOR_SERVER_URL to be set explicitly.

Step 1 — Install the CLI

Check whether conductor is already installed:

conductor --version

If not installed, check for npm/Node.js:

npm --version

If npm is also missing, install Node.js first:

# macOS
brew install node
# Linux (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs

For installing the CLI itself, two options:

  • Recommended (no global install): invoke as npx @conductor-oss/conductor-cli ... for one-off use. No system modification.
  • Global install (ask the user first): npm install -g @conductor-oss/conductor-cli. Modifies the global npm prefix — confirm before running. Once approved, verify with conductor --version.

Fallback — only after the CLI is genuinely unavailable (conductor --version fails) and Node/npm cannot be installed (restricted environment, no package manager), fall back to the bundled REST API script:

export CONDUCTOR_API="<path-to-this-skill>/scripts/conductor_api.py"

The fallback supports a subset of CLI commands — see fallback-cli.md. It does not support key/secret auth (token only), profiles, server auto-detection, taskDef CRUD, or time-range search.

Step 2 — Choose a server

Ask the user:

  • Option A — Start a local server (good for development/testing).
  • Option B — Connect to an existing remote server.

Don't assume — present both.

Option A — local server:

conductor server start
# custom port:
conductor server start --port 3000
# verify:
conductor server status

Option B — existing server:

export CONDUCTOR_SERVER_URL="http://your-server:8080/api"

Step 3 — Test connectivity and handle auth

conductor workflow list

If this succeeds, the server has no auth — go to Step 4.

If you get 401 or 403, the server requires authentication. Only then ask the user for credentials. Set them via env vars (never echo the values):

# Key + Secret (recommended for Orkes / Enterprise)
export CONDUCTOR_AUTH_KEY="<ask user>"
export CONDUCTOR_AUTH_SECRET="<ask user>"

# Or a pre-existing token
export CONDUCTOR_AUTH_TOKEN="<ask user>"

Re-test: conductor workflow list

Auth header: the REST API expects X-Authorization: <token>. The CLI handles this automatically. If using the Python fallback, only CONDUCTOR_AUTH_TOKEN is supported — key/secret exchange is not implemented.

Step 4 — Verify

conductor workflow list

Report the result to the user. Setup complete.

Optional — named profiles

For switching between multiple servers (dev / staging / prod):

conductor config save --server https://dev.example.com/api  --auth-key KEY --auth-secret SECRET --profile dev
conductor config save --server https://prod.example.com/api --auth-key KEY --auth-secret SECRET --profile prod

Then append --profile {env} on any command. Profiles live in ~/.conductor-cli/config.yaml.

Updating this skill

If the user asks to upgrade or you suspect this skill is outdated:

# macOS / Linux
curl -sSL https://conductor-oss.github.io/conductor-skills/install.sh | bash -s -- --all --upgrade

# Windows
irm https://conductor-oss.github.io/conductor-skills/install.ps1 -OutFile install.ps1; .\install.ps1 -All -Upgrade