Skip to main content

Install the AlphaSwarm client

This is the Stage-3 step of institutional onboarding: after you have signed up and been made your organization's administrator, you download and install the alphaswarm-cli client, sign in, and enrol your device.

The client is distributed as a Python package, installed with pipx. It is not a .dmg/.exe installer and it is not built from a source checkout. pipx puts the alphaswarm-cli command on your PATH in its own isolated virtual environment, and gives you a first-class pipx upgrade path that the client's built-in self-update command drives.

Prerequisites​

  • Python 3.12+ and pipx (python3 -m pip install --user pipx && pipx ensurepath).
  • Access to the AlphaSwarm private package index. Your onboarding email contains either an index URL (set as ALPHASWARM_INDEX_URL) or the AWS credentials to mint a CodeArtifact authorization token. The private index upstreams to public PyPI, so a single --index-url resolves both the AlphaSwarm packages and their public dependencies in one pass.

Install​

Use the bootstrap script (recommended — it ensures pipx, obtains a token if needed, and installs against the index):

curl -fsSL https://<your-org-install-host>/install.sh | sh

Or install directly if you already have ALPHASWARM_INDEX_URL set:

pipx install "alphaswarm-cli" --index-url "$ALPHASWARM_INDEX_URL"

Verify:

alphaswarm-cli --version
# current shipped CLI: 0.1.0-alpha.1

First run​

Create your user configuration (written to ~/.config/alphaswarm/config.yaml — the client does not assume a local source checkout or a locally running control plane):

alphaswarm-cli setup init-config

Point it at your organization's hosted backend (from your onboarding email) if init-config did not already capture it.

Sign in and enrol your device​

alphaswarm-cli auth login                 # RFC 8628 device-code flow — opens a browser
alphaswarm-cli connect redeem <code>      # enrol this device with the pairing code
                                           # from your onboarding email / the admin surface

(alphaswarm-cli connect alone only prints help — connect is a sub-command group; redeem is what actually pairs the device.) Your organization administrator then approves the device from the admin surface. Once approved, the device is live and can receive the guided AWS-account and deployment flows.

Keeping the client up to date​

The client checks and applies its own updates — this is opt-in, never a background phone-home:

alphaswarm-cli self-update check      # compare installed vs latest on the index
alphaswarm-cli self-update apply      # pipx upgrade (falls back to pip -U)

Optional: the local control node​

alphaswarm-local (the self-hosted control node) installs the same way and pulls alphaswarm-cli transitively:

pipx install "alphaswarm-local" --index-url "$ALPHASWARM_INDEX_URL"

Its bundled compose/Helm assets are packaged with the wheel and resolved from the installed package — you can run it from any working directory.

Troubleshooting​

  • pipx install cannot find alphaswarm-cli — the AlphaSwarm packages must be published to the private index your --index-url points at. If you get a "no matching distribution" error, the index has not yet been seeded for your environment; contact your AlphaSwarm operator.
  • Token/endpoint errors — re-run the bootstrap install.sh, or refresh your CodeArtifact authorization token; tokens are short-lived by design.