Octopus Deploy Documentation

Installing Octo as a Capability

Last updated

There are times when you may want to install Octo on a build agent, such as to avoid downloads, opening any firewalls and or changing proxy rules. There are a few ways in which this can be achieved. In every option presented here, you must install Octo so that it's in your current environment path. It should also be noted that the same steps can be used to register capabilities such as DotNetCore as well.

Installing Octo as a global tool will require an additional shell execution script to be in the path to delegate execution to dotnet octo. The reason for this is that the global tool install is only available via dotnet octo and doesn't
provide a way to execute Octo directly.

For example, create a script called octo.ps1 with the following content:

& dotnet octo $args

Agent Capability Scanning

Usually Azure DevOps agents scan for associated capabilities, but won't pick anything up from the PATH automatically. In order for a capability to be detected, you must also add an environment variable named Octo with the associated version.

Octo System Variable

Once Octo is in the path and the above system variable is specified, Azure DevOps will detect the capability automatically.

[Environment]::SetEnvironmentVariable("Octo", "4.39.3", "Machine")

You must restart the build agent service if making these changes while it is currently running.

Specify the Capability Manually

If you know that a build agent has Octo available on the path then you can also specify the capability manually using the Azure DevOps/TFS web interface. Although this may be rather simple, the capability would have to be specified for each agent individually which can be quite cumbersome.

Octo specify capability

Images and Automation

Microsoft provide a number of starting points to create your own build agent images which can be modified to include Octo as an added capability. This includes packer images as well as the docker images.


If you're having difficulties downloading the Octopus CLI when you run each step (perhaps due to firewalls and proxies) we also offer another helpful step: Octopus tools installer

Octopus tools installer

This step will fallback to using an embedded version of octo if the selected version cannot be successfully downloaded.

Welcome! We use cookies and data about how you use our website allow us to improve the website and your experience, and resolve technical errors. Our website uses cookies and shares some of your data with third party analytics companies for these purposes. We do not use these cookies for advertising.

If you decline, we will respect your privacy. A single cookie will be used in your browser to remember your preference.