> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Download and install Trace on your macOS, Windows, or Linux machine.

## Download

Download the latest version of Trace from the official website:

[buildwithtrace.com/download](https://buildwithtrace.com/download)

## macOS Installation

<Steps>
  <Step title="Download the .dmg file">
    Download the `.dmg` file for macOS from the link above.
  </Step>

  <Step title="Open and install">
    Open the downloaded file and drag Trace to your Applications folder.
  </Step>

  <Step title="Launch Trace">
    Open Trace from Applications. Trace is signed and notarized — no Gatekeeper workarounds needed, even on macOS Sequoia (15+).
  </Step>
</Steps>

<Info>
  **Smooth installs on Sequoia** — Starting with v1.2, Trace passes Apple's Gatekeeper checks out of the box. All binary paths are relative, the CLI is properly named, and the `Info.plist` metadata is correct. No `xattr` commands or "Open Anyway" steps required.
</Info>

## Windows Installation

<Steps>
  <Step title="Download the installer">
    Download the `.exe` installer for Windows.
  </Step>

  <Step title="Run the installer">
    Run the installer and follow the prompts.
  </Step>

  <Step title="Launch Trace">
    Launch Trace from the Start menu or desktop shortcut.
  </Step>
</Steps>

## Linux Installation

<Steps>
  <Step title="Download the AppImage">
    Download the `.AppImage` file for Linux from the link above.
  </Step>

  <Step title="Make it executable">
    Open a terminal and run:

    ```bash theme={null}
    chmod +x trace-*-linux-x86_64.AppImage
    ```
  </Step>

  <Step title="Run Trace">
    Double-click the AppImage or run it from the terminal:

    ```bash theme={null}
    ./trace-*-linux-x86_64.AppImage
    ```
  </Step>
</Steps>

<Info>
  **AppImage dependencies** — Trace's AppImage uses a modern DwarFS-based runtime that does **not** require FUSE. If the AppImage won't start, try extracting and running directly: `URUNTIME_EXTRACT=1 ./trace-*-linux-x86_64.AppImage --appimage-extract && ./squashfs-root/AppRun`. Trace requires `libsecret` and `webkit2gtk` for authentication and the chat UI — these are usually preinstalled on GNOME and KDE desktops.
</Info>

## Open from the Command Line

You can launch Trace from your terminal and open a project directory or file directly — similar to how `cursor .` or `code .` works.

<Tabs>
  <Tab title="macOS">
    Open the current directory in Trace:

    ```bash theme={null}
    open -a Trace .
    ```

    Open a specific project file:

    ```bash theme={null}
    open -a Trace ./my-project.kicad_pro
    ```

    **Optional: create a `trace` shell command**

    Add this to your `~/.zshrc` (or `~/.bashrc`):

    ```bash theme={null}
    trace() {
      open -a Trace "${@:-.}"
    }
    ```

    Then restart your terminal. Now you can use:

    ```bash theme={null}
    trace .
    trace ~/Projects/my-board/my-board.kicad_pro
    trace  # no argument opens Trace with no project
    ```
  </Tab>

  <Tab title="Windows">
    The Windows installer adds Trace to your PATH. Open a project from Command Prompt or PowerShell:

    ```bash theme={null}
    trace .
    ```

    Open a specific project file:

    ```bash theme={null}
    trace my-project.kicad_pro
    ```
  </Tab>

  <Tab title="Linux">
    Run the AppImage with a path argument:

    ```bash theme={null}
    ./trace-*-linux-x86_64.AppImage .
    ```

    **Optional: create a `trace` command**

    Symlink the AppImage to a location on your PATH:

    ```bash theme={null}
    sudo ln -s /path/to/trace-*-linux-x86_64.AppImage /usr/local/bin/trace
    ```

    Then you can use:

    ```bash theme={null}
    trace .
    trace ./my-project.kicad_pro
    ```
  </Tab>
</Tabs>

<Tip>
  Passing `.` opens the current working directory as a project. You can also pass a `.kicad_pro`, `.kicad_sch`, or `.kicad_pcb` file directly.
</Tip>

## Signing In

After installation, launch Trace and sign in with your account. You can create an account at [buildwithtrace.com/signup](https://buildwithtrace.com/signup) if you don't have one.

Authentication is handled via OAuth. Click "Sign In" in the application, and you'll be redirected to complete authentication in your browser.

## Verifying Installation

Once signed in, you should see the Trace dashboard with options to create a new project or open an existing one. If you encounter any issues, check the [Troubleshooting](/resources/troubleshooting) guide.

<Warning>
  **Important — Do Not Trust AI 100%:** Trace is an AI-powered tool designed to assist your PCB design workflow, not replace your engineering judgment. AI can and will make mistakes. Always review and verify all designs, schematics, component selections, routing, and manufacturing outputs before fabrication. Make sure you understand everything on your board — every trace, every component, every connection. Do not send designs to manufacturing without thorough inspection and validation. When in doubt, consult with experienced engineers or use professional design review services.
</Warning>