# Installation Guide {% hint style="info" %} **Note:** The machine you install Ax on is called the [Ax Controller.](/overview/ax-controller.md) The Controller manages all aspects of Ax, including account setup, building your Packer image, spinning up and SSHing into instances, creating new images from existing instances, deleting instances and images, managing distributed scanning, and much more! {% endhint %} ## Operating Systems Supported | OS | Supported | Easy Install | Tested | | ---------- | --------- | ------------ | ------------- | | Ubuntu | Yes | Yes | Ubuntu 22.04 | | Kali | Yes | Yes | Kali 2024.2 | | Debian | Yes | Yes | Debian 12 | | Windows | Yes | Yes | WSL w/ Ubuntu | | MacOS | Yes | Yes | MacOS 14 | | Arch Linux | Yes | No | Yes | ## Docker Install This will create a docker container, initiate ax configure and ax build and then drop you out of the docker container. After a Packer image is successfully created, you will likely have to re-exec into your docker container. ``` docker exec -it $(docker run -d -it --platform linux/amd64 ubuntu:20.04) sh -c "apt update && apt install git -y && git clone https://github.com/attacksurge/ax/ ~/.axiom/ && cd && .axiom/interact/axiom-configure --run" ``` ## Easy Install As a standard user with root privileges, run this command on any [supported](#operating-systems-supported) OS. The script will prompt for sudo when root when required. ``` bash <(curl -s https://raw.githubusercontent.com/attacksurge/ax/master/interact/axiom-configure) --run ``` ## Git Clone In most cases, the easy install should work, however, if you do want to install using git clone, this guide is your friend! Ensure that `~/.axiom/` does not exist ``` rm -rf ~/.axiom/ ``` Clone the Ax repository ``` git clone https://github.com/attacksurge/ax.git ~/.axiom/ ``` Run ax configure script ``` ~/.axiom/interact/axiom-configure ``` ## Manual To install Ax on an OS that is not on our [supported](#operating-systems-supported) list, all you have to do is ensure that you have all the right dependencies and then run `ax account-setup`. Clone the Ax repository ``` git clone https://github.com/attacksurge/ax.git ~/.axiom/ ``` ### Dependencies * Cloud providers API key * SSH Keypair (without password) * git * curl * ruby * jq - 1.6 or higher * packer - Tested with v1.5.6 * the cloud providers CLI (doctl, linode, ibmcloud, az, aws) * Interlace - (created by [codingo](https://x.com/codingo_) and [sml555](https://twitter.com/sml555_)) * rsync * add `~/.axiom/interact` to your path ## **Troubleshooting Guide** If you're experiencing an error, especially one that started recently, please follow these steps to troubleshoot the issue: 1. **Run `ax update`:** Ensure that you've successfully run `ax update` before reporting any issues. This step often resolves problems by bringing your installation up to date. 2. **Checklist:** * **Build an Image:** Have you successfully built an image with `ax build`? Check all available images with `ax images ls` to confirm. * **Cloud Provider CLI:** Ensure that the cloud provider's CLI is properly installed and authenticated by running `ax account-setup`. * **Reinstall Dependencies:** Run `ax configure --run` to reinstall all necessary dependencies. * **Rebuild Image:** If the issue persists, try building a new image by running `ax build --run`. 3. **Last Resort:** * If the problem still isn't resolved, as a last resort, delete Ax by running `rm -rf ~/.axiom` and then reinstall it from scratch. This often fixes issues that occurred during the initial installation. ## FAQ #### How can I upgrade from [Axiom Classic](https://github.com/pry0cc/axiom) to the Ax Framework? Refer to [Existing Users](/overview/existing-users.md) for a detailed overview of how to upgrade. #### I can't SSH in to my instances, I get permission denied/wrong password? Be default, Ax creates an SSH key named axiom\_rsa in `~/.ssh/axiom_rsa`. The reference to the SSH key is stored in `~/.axiom/axiom.json`. You can change the `sshkey` value to another SSH key as long as its stored in `~/.ssh/`. You may need need to rebuild (`ax build --run`) with your new SSH key to use it. #### I spin up `X` instances but only `Y` provision, whats wrong? Check that you havent exceeded your instance limit. After a few billing cycles you can generally increase your instance limit via opening a support ticket with the associated cloud provider #### Will distributing my scans make me a better hacker? Probably not. The Ax Framework isn't about improving your fundamental skills or intuition; it's about enhancing your efficiency and speed. Distributing your scans will undoubtedly allow you to cover more ground in less time, but the core principles of finding vulnerabilities remain unchanged. If you struggle to identify bugs without Ax, simply adding more computational power won't necessarily lead to the discovery of higher-quality bugs. Ax accelerates the process, but it doesn't replace critical thinking, creativity, and in-depth understanding. It's a tool that enhances what you already know and can do—not a shortcut to expertise. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ax.attacksurge.com/overview/installation-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.