octo-tools configuration

The OctoMesh developer PowerShell uses a per-developer config file for everything that depends on your environment — the OctoMesh installations you talk to, your container registry, your Rancher / Vault / Semaphore / AI bastion endpoints, the Telerik Kendo UI license. These values are not shipped in the octo-tools repo; they live in ~/.config/octo-tools/installations.json outside of git.

The PowerShell profile sources the file at startup. Cmdlets that need a value throw a clear, actionable error if the file is missing or the requested entry isn't defined.

1. Create the config

Copy the example file from the repo:

mkdir -p ~/.config/octo-tools
cp <your octo-tools checkout>/installations.example.json ~/.config/octo-tools/installations.json

Or override the location with $env:OCTO_TOOLS_CONFIG if you want to keep the file somewhere else (CI / shared dotfiles repo / etc.).

2. Edit the installations[] block

Register-OctoCliContext -Installation <name> looks the installation up by its name in this list. Each entry has a services map with URL templates. The {0} placeholder is replaced with -$UriSuffix if you pass -UriSuffix, or with the empty string otherwise — that's how a single template covers preview sub-environments.

Minimum useful content for a host-process local dev loop:

{
  "installations": [
    {
      "name": "local",
      "services": {
        "assets":        "https://localhost:5001/",
        "identity":      "https://localhost:5003/",
        "bots":          "https://localhost:5009/",
        "communication": "https://localhost:5015/",
        "reporting":     "https://localhost:5007/",
        "ai":            "https://localhost:5019/"
      }
    }
  ]
}

Add a remote cluster the same way:

{
  "name": "example-test",
  "services": {
    "assets":        "https://assets{0}.test.example.com/",
    "identity":      "https://connect{0}.test.example.com/",
    "bots":          "https://bots{0}.test.example.com/",
    "communication": "https://communication{0}.test.example.com/",
    "reporting":     "https://reporting{0}.test.example.com/",
    "ai":            "https://ai{0}.test.example.com/"
  }
}

Now Register-OctoCliContext -Installation example-test -TenantId mytenant -UriSuffix pr123 resolves to https://assets-pr123.test.example.com/, etc.

3. (Optional) Add other endpoints

The same file collects every environment-specific endpoint the tooling needs:

{
  "registry":  { "url": "your-dev-registry.example.com" },
  "rancher":   { "url": "https://rancher.example.com" },
  "vault":     { "addr": "https://vault.example.com" },
  "semaphore": {
    "url": "https://semaphore.example.com",
    "breakGlassProjectId":  1,
    "breakGlassTemplateId": 1
  },
  "aiBastion": { "url": "https://ai.example.com" }
}

Every top-level block is optional. Cmdlets only fail if the specific block they need is missing. profile.ps1 exports RANCHER_URL, VAULT_ADDR, SEMAPHORE_URL, SEMAPHORE_BREAKGLASS_PROJECT_ID and SEMAPHORE_BREAKGLASS_TEMPLATE_ID from these blocks at startup; cmdlets that read those env vars work unchanged.

Full schema reference: docs/installations-config.md in the octo-tools repo.

4. Private profile for personal credentials

Anything that's personal to you (your Telerik Kendo UI license, your Rancher API token, your AI-bastion octo-cli token) goes in a private PowerShell profile that the octo-tools profile sources at the end of its bootstrap.

OS	Path
macOS / Linux	~/.config/powershell/Microsoft.PowerShell_profile_private.ps1
Windows	~/.pwsh/profile.ps1

Typical content:

# Telerik Kendo UI license JWT. Get it from
# https://www.telerik.com/account/your-licenses
$env:TELERIK_LICENSE   = "<your Kendo UI license JWT>"

# Rancher API token. Create at:
# <your Rancher URL>/dashboard/account/index → "Account & API Keys" → "Create API Key"
# Format: token-xxxxx:secret. Choose "No Scope" and an explicit expiry.
$env:RANCHER_API_TOKEN = "token-xxxxx:secret"

Values set here override what the shared config file set — useful when you want to keep the config in a dotfiles repo but still vary one of the env vars per machine.

5. Verify

Open a fresh pwsh (so profile.ps1 runs), then:

Get-OctoToolsConfig | Format-List
Get-OctoInstallation -Name local
$env:RANCHER_URL
$env:VAULT_ADDR

If you edit the JSON file after the shell is already running, pick up the change without restarting with:

Get-OctoToolsConfig -Force

6. Troubleshooting

• octo-tools config not found at ... — ~/.config/octo-tools/installations.json doesn't exist. Create it from the example file (step 1).
• Installation '<name>' is not defined in your octo-tools config — add an entry for that name under installations[]. The error message also lists the names you do have configured.
• Installation '<name>' does not define a '<service>' service URL — add the missing key under services. Required keys are assets, identity, bots, communication. reporting and ai are only required when you call Register-OctoCliContext -IncludeReporting or -IncludeAi.