Skip to main content

INSTALL SWAMP

This guide shows you how to install the Swamp CLI on macOS, Linux or Windows and verify it works.

Install on macOS or Linux

Open your terminal and run:

$ curl -fsSL https://swamp-club.com/install.sh | sh

Install on Windows

Open PowerShell and run:

PS> irm https://swamp-club.com/install.ps1 | iex

Where Swamp lands depends on how you opened PowerShell:

PowerShell Install directory PATH updated
Run as administrator C:\Program Files\swamp System PATH
Normal (no admin rights) %LOCALAPPDATA%\swamp Your user PATH

If the SWAMP_HOME environment variable is set, Swamp installs into %SWAMP_HOME%\bin instead, whichever way you opened PowerShell.

swamp works straight away in the PowerShell window you installed from. Restart any other open terminals so they pick up the new PATH.

To install into a different directory or pin a version, download the script and run it with parameters:

PS> irm https://swamp-club.com/install.ps1 -OutFile install.ps1
PS> powershell -ExecutionPolicy Bypass -File .\install.ps1 -Destination C:\Tools\swamp

-Version takes a release version such as 20250218.210911.0-sha.bda1ce6ea and defaults to stable. A script run this way updates PATH for new windows only, so open a new terminal before running swamp.

If your organisation only lets programs run from certain folders, see Fix "An unauthorized application was blocked" on Windows.

Verify the installation

Run:

$ swamp version

You should see output like:

2026-07-27T23:29:40.649Z [INF] version: swamp "20260727.150514.0-sha...."

If the command is not found, see Fix "command not found" on macOS or Linux or Fix "swamp is not recognized" on Windows.

Start a task

On a desktop, run swamp start. It signs you in, sets up a workspace, and hands your first task to an AI agent:

$ swamp start

See Start a task with swamp start. For CI, containers, or a repo you set up yourself, see Sign in.

Fix "command not found" on macOS or Linux

If your shell cannot find swamp, restart it:

$ exec $SHELL

If the command is still not found, add ~/.local/bin to your PATH. Add one of these lines to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

# bash / zsh
export PATH="$HOME/.local/bin:$PATH"

# fish
fish_add_path ~/.local/bin

Then restart your shell and run swamp version again.

Fix "swamp is not recognized" on Windows

Close every PowerShell and terminal window, open a new one, and run swamp version again. Windows only reads PATH changes into new windows.

If it is still not recognized, check that the install directory from the table above is on your PATH:

PS> $env:Path -split ";" | Select-String swamp

If nothing prints, re-run the installer.

Fix "An unauthorized application was blocked" on Windows

Application control policies (AppLocker, WDAC, endpoint protection) often only let programs run from approved folders. Besides swamp.exe, Swamp unpacks and downloads programs into its home directory, C:\Users\<you>\.swamp: the Deno runtime (deno.exe), esbuild for building extensions (esbuild-win32-x64.exe), and Litestream for datastores that use it (litestream.exe). A blocked one fails a command such as swamp extension pull with a message like:

An unauthorized application was blocked on <computer> as it may put your device and personal information at risk.

Application: ESBUILD-WIN32-X64.EXE
Location: C:\USERS\<YOU>\.SWAMP\DENO-CACHE\DL\ESBUILD-0.25.5-1

Set the SWAMP_HOME environment variable to move Swamp's whole home directory into a folder the policy allows. This example uses C:\Sources\Repo; replace it with your allowed folder.

  1. Save SWAMP_HOME as a user environment variable, so every new terminal uses it, and set it in this window too, so the installer sees it:

    PS> [Environment]::SetEnvironmentVariable("SWAMP_HOME", "C:\Sources\Repo\.swamp", "User")
PS> $env:SWAMP_HOME = "C:\Sources\Repo\.swamp"

  2. Optional: to keep your existing workspaces and caches, copy the old home directory across before the installer creates the new one:

    PS> Copy-Item -Recurse "$env:USERPROFILE\.swamp" "C:\Sources\Repo\.swamp"

  3. Install Swamp in the same window. With SWAMP_HOME set, the installer puts swamp.exe in C:\Sources\Repo\.swamp\bin and adds that folder to your PATH:

    PS> irm https://swamp-club.com/install.ps1 | iex

  4. Check that Swamp runs from the allowed folder:

    PS> (Get-Command swamp).Source
C:\Sources\Repo\.swamp\bin\swamp.exe

  5. Sign in again. SWAMP_HOME also moves your login, to C:\Sources\Repo\.swamp\config:

    PS> swamp auth login

Swamp now runs and unpacks its own files under C:\Sources\Repo\.swamp. After your next swamp extension pull it contains bin, deno and deno-cache, and nothing new appears in C:\Users\<you>\.swamp. Other terminals pick up the new PATH and SWAMP_HOME once you open them again.

Your AI agent's skills are the exception. swamp repo init and swamp update keep them in each agent's own skills folder under your user profile, such as %USERPROFILE%\.agents\skills, %USERPROFILE%\.claude\skills or %USERPROFILE%\.kiro\skills, because that is where the agent reads them. They are Markdown files, not programs, so application control does not block them.

To go back to the default home directory, remove the variable and open a new terminal. swamp.exe stays in C:\Sources\Repo\.swamp\bin on your PATH until you reinstall or remove it:

PS> [Environment]::SetEnvironmentVariable("SWAMP_HOME", $null, "User")

SWAMP_HOME works the same way on macOS and Linux: with export SWAMP_HOME=/opt/swamp-home in your shell profile, install.sh installs into /opt/swamp-home/bin and links it into /usr/local/bin when that folder is not on your PATH. Agent skills stay in each agent's skills folder in your home directory, such as ~/.agents/skills or ~/.claude/skills.

Sign in

To use Swamp without swamp start, sign in first. Every Swamp command other than swamp start, swamp version, swamp help, swamp completions and swamp update needs a swamp-club.com account:

$ swamp auth login

For CI and containers, use a collective token instead — see Authenticate with API keys. For what the requirement enforces, see Swamp Account Requirement.

Next steps

  • Build your first automation — a guided tutorial from a fresh install to a working health-check workflow
  • To set up a repository yourself instead of with swamp start, initialize it with swamp repo init (per-agent setup), then ask your agent to "get started with Swamp" — the swamp-getting-started skill walks you through building a first behavior around your own goal
  • Set up shell completions for tab completion of subcommands, flags, and behavior names in bash, zsh, fish or PowerShell 7
  • Set up background autoupdating to keep the CLI current without manual intervention
  • Swamp collects usage telemetry; turn off usage telemetry to opt out
← PreviousRemote ExecutionNext →Start a Task with swamp start