Installing a self-hosted agent#

Available on: Free & OS Startup Scaleup

The Semaphore agent is open source and can be found here. Before installing it on your machine, you need to make sure the following requirements are also available:

  • git
  • bash (Linux/MacOS) or PowerShell (Windows)
  • docker - manageable without sudo (Linux/MacOS)
  • docker-compose (Linux/MacOS)

Please, follow the installation instructions for your operating system of choice below.

Installing the agent on Ubuntu/Debian#

1. Prepare your machine:

sudo mkdir -p /opt/semaphore/agent
sudo chown $USER:$USER /opt/semaphore/agent/
cd /opt/semaphore/agent

2. Download the agent:

curl -L https://github.com/semaphoreci/agent/releases/download/v2.2.4/agent_Linux_x86_64.tar.gz -o agent.tar.gz
tar -xf agent.tar.gz

3. Install the agent:

sudo ./install.sh

The script asks for your Semaphore organization name, the agent type registration token, the Linux user used to run the service, and does the following:

  • downloads and installs the Semaphore toolbox
  • creates a systemd service for the agent
  • creates an initial config.yaml file in the installation directory for you to manage agent configuration

Note that any changes in the agent configuration file require a restart of the systemd service.

Installing the agent on generic Linux#

1. Prepare your machine:

sudo mkdir -p /opt/semaphore/agent
sudo chown $USER:$USER /opt/semaphore/agent/
cd /opt/semaphore/agent

2. Download the agent:

curl -L https://github.com/semaphoreci/agent/releases/download/v2.2.4/agent_Linux_x86_64.tar.gz -o agent.tar.gz
tar -xf agent.tar.gz

3. Create the agent configuration file:

cat > config.yaml <<EOF
endpoint: "[your-organization-name].semaphoreci.com"
token: "[token]"
EOF

4. Download and install the toolbox:

curl -L "https://github.com/semaphoreci/toolbox/releases/latest/download/self-hosted-linux.tar" -o toolbox.tar
tar -xf toolbox.tar
mv toolbox ~/.toolbox
bash ~/.toolbox/install-toolbox
source ~/.toolbox/toolbox
echo "source ~/.toolbox/toolbox" >> ~/.bash_profile

5. Run the agent:

agent start --config-file config.yaml

Installing the agent on MacOS#

1. Prepare your machine:

sudo mkdir -p /opt/semaphore/agent
sudo chown $USER /opt/semaphore/agent/
cd /opt/semaphore/agent

2. Download the agent:

curl -L https://github.com/semaphoreci/agent/releases/download/v2.2.4/agent_Darwin_x86_64.tar.gz -o agent.tar.gz
tar -xf agent.tar.gz

3. Install the agent:

sudo ./install.sh

The script asks for your Semaphore organization name, the agent type registration token, the macOS user used to run the agent, and does the following:

  • downloads and installs the Semaphore toolbox
  • creates a launchd daemon for the agent
  • creates an initial config.yaml file in the installation directory for you to manage agent configuration

Note that any changes in the agent configuration file require a restart of the launchd daemon.

Installing the agent on MacOS using Homebrew#

1. Install the agent using Homebrew:

brew install semaphoreci/tap/agent

2. Download and install the toolbox:

When installing the agent using Homebrew, the toolbox isn't installed. You need to manually install it:

curl -L "https://github.com/semaphoreci/toolbox/releases/latest/download/self-hosted-darwin.tar" -o toolbox.tar
tar -xf toolbox.tar
mv toolbox ~/.toolbox
bash ~/.toolbox/install-toolbox
source ~/.toolbox/toolbox
echo "source ~/.toolbox/toolbox" >> ~/.bash_profile

3. Start the agent:

agent start --endpoint semaphore.semaphoreci.com --token [token]

Installing the agent on Windows#

1. Prepare your machine:

New-Item -ItemType Directory -Path C:\semaphore-agent
Set-Location C:\semaphore-agent

2. Download the agent:

Invoke-WebRequest "https://github.com/semaphoreci/agent/releases/download/v2.2.4/agent_Windows_x86_64.tar.gz" -OutFile agent.tar.gz
tar.exe xvf agent.tar.gz

3. Install the agent:

$env:SemaphoreEndpoint = "<your-organization>.semaphoreci.com"
$env:SemaphoreRegistrationToken = "<your-agent-type-registration-token>"
.\install.ps1