Get started

Running in about a minute.

One binary, one SQLite file. No Kubernetes, no Postgres, no Redis to stand up first. The same binary grows with the team: on a Team license it runs active-active on PostgreSQL, and relay workers run inside networks the control node cannot reach. On Kubernetes, a Helm chart runs the same binary with no operator. Here's every step, from download to a live run. Or skip the install and poke at the live demo first.

  1. 1

    Install

    One line downloads the right binary for your machine, verifies it against the published checksums, and installs it:

    curl -fsSL https://switchtender.com/install.sh | sh

    On a host with wget and no curl, wget -qO- https://switchtender.com/install.sh | sh does the same.

    Prefer not to pipe to a shell? Every release ships cosign-signed checksums and SBOMs: verify them with cosign, then run the binary you checked. The in-browser verifier checks a LoomSeal evidence bundle, which is a different artifact.

    Or grab a prebuilt binary yourself. No toolchain required. Every release ships macOS, Linux, and Windows builds you can download and run.

    Download the latest release All releases

    Pick the build for your platform: the .dmg or a darwin tarball on macOS, a linux tarball on Linux, or the windows zip. Verify it against the SHA256SUMS file on the same release. On macOS the app in the .dmg is signed and notarized. The binary in the tarball is not yet, so if you downloaded it through a browser, clear the quarantine flag before running it: xattr -d com.apple.quarantine ./switchtender.

    Prefer to build from source? With the Go toolchain installed:

    go install github.com/kordloom/switchtender@latest

    Ansible runs need ansible-core, which the binary does not carry. If ansible-playbook is not already on the box, one command installs a pinned ansible-core beside the database, checking every file against a hash the binary carries. Run it in the directory you will start the server in, as the account that will run the server. It needs a python3 from 3.12 to 3.14 with its venv module. On Python 3.11 add --version 2.19, and on 3.10 --version 2.17. The python3 macOS ships is 3.9, so install a newer one there first, and the install does not run on Windows. The managed Ansible runtime page covers offline installs, workers, and the desktop app.

    switchtender ansible install

    The other tools come from the PATH: terraform, tofu, python3, pwsh (PowerShell 7), or go. Bash runs use the shell macOS and Linux already have. The container image carries Ansible, Python, Terraform, and OpenTofu. PowerShell and Go bring their own, on the host or in a pinned container image.

  2. 2

    Serve

    Start the server. SQLite is the default. Point --db at a Postgres DSN when you want more than one instance. Creating a new PostgreSQL schema needs a Team license; opening one that already exists is never gated, in any license state. Set the encryption pair if you plan to store credentials. On a public address with no tokens yet, serve mints your initial admin token and prints it once, so the API requires auth from its very first request; only loopback and --read-only may run open, and it says so.

    # needed for stored secrets and for the addresses and callback keys an import seals, so keep both values
export SWITCHTENDER_ENCRYPTION_KEY=$(openssl rand -hex 32)
export SWITCHTENDER_ENCRYPTION_SALT=$(openssl rand -hex 16)

switchtender serve --addr :8080 --db switchtender.db
  3. 3

    Open the UI

    The whole interface lives at /ui/. Sign in with the admin token serve just printed: pick Use an API token instead on the login page and paste it. This is where you launch runs and read them as a live host-by-task matrix.

    open http://localhost:8080/ui/
  4. 4

    Launch your first run

    Click Launch run in the UI, or fire one over the API with the token from step 2. No Ansible required for this one. It's a plain Bash run you can watch stream live.

    # the admin token serve printed at startup
export ST_TOKEN=paste-it-here

curl -s -X POST localhost:8080/v1/runs \
  -H "authorization: Bearer $ST_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"tool":"bash","command":"echo hello from switchtender"}'
  5. 5

    Name your tokens

    Unless you start it with --read-only for a public demo, the server never runs open on a network interface: step 2 already minted your initial admin token. Now mint named tokens for each person and each CI job, send them as bearer tokens, and retire the initial one so every credential in the audit trail names its owner.

    switchtender token new --name admin --db switchtender.db
switchtender token revoke <initial-token-id> --db switchtender.db

On Kubernetes? The Helm chart in the repository runs the same binary as an ordinary Deployment, with no operator: one server on SQLite with the whole install on a persistent volume, or on a Team license, active-active servers on PostgreSQL with dedicated workers. Write the keys to a file first and keep it, because every stored credential is sealed against them, and pass the same file to every upgrade:

git clone https://github.com/kordloom/switchtender
cd switchtender
printf 'encryptionKey: "%s"\nencryptionSalt: "%s"\nauditKey: "%s"\n' \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 16)" \
  "$(openssl rand -hex 32)" > switchtender-secrets.yaml
chmod 600 switchtender-secrets.yaml
helm install switchtender ./deploy/helm/switchtender \
  -f switchtender-secrets.yaml --set fullnameOverride=switchtender
Kubernetes guide

Moving from another controller? Start with switchtender assess awx export.json, which reads the estate and says what comes across, what does not, and which templates nobody currently has to approve, before anything is written. Then each source imports in one command. AWX and Semaphore bring projects, inventories, credential shells, templates, surveys, and schedules. Rundeck and Jenkins bring jobs as templates and their triggers as schedules. Chef and Puppet bring the node list as an inventory, and nothing else: a cookbook or a manifest is a program in another language, and a partial translation would look right and do something else. The command is the same shape for all of them: a preview that writes nothing, then the same command with --apply. Ansible Automation Platform, Tower, and Ascender share the AWX export format, and even a crontab imports into governed schedules.

Migration guide

Where to next

ConceptsRuns, inventories, pipelines, and the control plane. Run a jobA guided first playbook, end to end. Multi-toolAnsible, Terraform, OpenTofu, Bash, PowerShell, Python, and Go in one engine. SecretsSeal, source, and mask credentials. vs AWX & SemaphoreThe honest head-to-head. HTTP APIEvery endpoint the server exposes. Try the demoSeeded, read-only, zero setup: run switchtender demo.

Run your first job.

Structured runs, balanced splits, fleet memory, and a tamper-evident audit trail, from one binary.

★ Star on GitHub Read the docs