Installing and using the Zendesk apps tools

Have more questions? Submit a request


  • Craig Hamm
    Comment actions Permalink

    Is it possible to pass the parameters in the "zat server" command, or even better, could the server be configured to read from an config file?

  • Olaf Kwant
    Comment actions Permalink

    Yes. From version 1.20.0 it will automatically read from a settings.yml file in your current working directory. Or you pass it a file with the -c option.

  • Mzhu
    Comment actions Permalink

    When I'm running zat server, is it also supposed to stop me from affecting the zendesk tickets themselves? For example, say my app has a button that changes the ticket status to "pending" and add a "we'll get back to you" canned comment. If I click that button while ?zat=true, then will it change that ticket in real life?

  • Angelica Coleman
    Comment actions Permalink

    Hi Mzhu,

    Any changes made while '?zat=true' runs will be changed just like in real life. We recommend making a test account, populating it with test data, and experimenting on that. If you have any questions about how to set up a testing account, just let me know. Also, what are you making?


  • Thomas Verschoren
    Comment actions Permalink

    To use the gem install macOS Mojave requires installing the XCode tools:

    xcode-select --install

    You might want to add that to the install steps/

  • William Lauze
    Comment actions Permalink

    If you are familiar with docker, you can use the following docker image that simplifies the setup: 

    "zat": "docker run --rm -v `pwd`:/data --publish 4567:4567 bertrandgressier/zat-docker serve --unattended --bind="

  • David Fulgham
    Comment actions Permalink

    Had a horrible time with installing this on MacOS the trick is to install with the following:

    sudo gem install zendesk_apps_tools -- --use-system-libraries

    the documentation on this page should add those options switches.

  • Jason Humphrey
    Comment actions Permalink

    Here are the things I had to do to get ZAT working on Windows using Ubuntu and Ruby 2.5.1+

    1. sudo apt update
    2. sudo apt-get install ruby-full
    3. sudo gem install rake
    4. sudo apt-get install build-essential dh-autoreconf
    5. sudo apt-get install libpng-dev
    6. sudo apt-get install zlib1g-dev
    7. sudo apt-get install software-properties-common
    8. sudo apt install nodejs npm
    9. sudo gem install zendesk_apps_tools

    After all that success!

  • Kevin Kitchens
    Comment actions Permalink

    Developing our ZenDesk application in Windows 10, ASP.NET.  Is it possible to still test this using ZAT, which would run the emulator "host", but still have the application running pages on the Windows 10 box?  Need access to real tickets while developing and developing a full featured app in Linux is not realistic for our needs.

    So... can ZAT run in the Ubuntu shell, but access a site on the actual Windows 10 machine?

  • Joey
    Comment actions Permalink

    Hi Kevin-

    Check out this post on how to open a browser in your host system from the Linux subsystem.

  • Michael Morar
    Comment actions Permalink

    I've successfully created a test app and I am able to view it in my zendesk subdomain. How does my Zendesk instance know where to find the iframe ? If I were to run ZAT server on another machine, how do I configure Zendesk to look for the iframe from that server? 

  • Bryan - Community Manager
    Comment actions Permalink

    Hi Michael. 'zat server' is for development only. It allows you to quickly change an app's source on a specific development machine and try out those changes from that same machine. This avoids having to re-upload the app to your test instance every time there's a source code change (nice when you're changing and trying things out quickly).

    When it's ready for production, you would run 'zat package' and go into your account's Admin > Apps/Manage page and select 'Upload private app' (and select the .zip file from the app project's ./tmp folder).

    For non-private/public marketplace apps, there's another process for that:

    Hope this helps clarify things a bit.

  • Jorge Merino
    Comment actions Permalink

    This was a fresh install on Windows 10, It gave me errors when running

    gem install zendesk_apps_tools
    ERROR: Error installing zendesk_apps_tools:
    ERROR: Failed to build gem native extension.

    current directory: /var/lib/gems/2.5.0/gems/eventmachine-1.2.7/ext
    /usr/bin/ruby2.5 -r ./siteconf20200206-83-1fsln3i.rb extconf.rb
    mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

    extconf failed, exit code 1

    I executed

    sudo apt-get install ruby`ruby -e 'puts RUBY_VERSION[/\d+\.\d+/]'`-dev

    problem was solved.

  • Argyris Gerogiannis
    Comment actions Permalink

    I was trying to install zendesk_apps_tools in windows 10 linux subsystem with errors concerning missing packages...

    After some reading to my logs and installing the below it worked like a charm:

    1. ruby-dev
    2. gcc
    3. make
    4. g++
    5. zlibc
    6. zlib1g

    The packages were missing from my default installation in ubuntu windows

  • Todd Holtmann
    Comment actions Permalink

    Hi. Newbie to ZAT and struggling to get my browser/chrome to pickup my local app.

    ZAT (3.7.1) is running and web server started/listening

    Ruby (2.5.1p57) installed and running

    chome security settings set


    But when I run our sandbox zendesk site with "?zat=true" my app never gets displayed.

    I'm able to manually install and run it without issue.

    Any advice?


  • Bryan - Community Manager
    Comment actions Permalink

    Hi Todd Holtmann -- Chrome changed relatively recently on how it handles "insecure" content. Since when running 'zat server' content is being pulled from a locally running server, you'll need to "Allow insecure content".

    You can quickly set what's needed by going to:

    1. chrome://settings/content/insecureContent

    2. Then using adding under "Allow": [*.] to cover all subdomains (if you're developing under more than one)

    See this community thread, which has more details:


  • Drew Williams
    Comment actions Permalink

    Adding to what Argyris Gerogiannis said, it now seems you also have to install zlib1g-dev to get it to work on Ubuntu. Its taken me hours to find this out, hopefully ZenDesk will update the documentation.

  • César Chas
    Comment actions Permalink

    Charles Nadeau,

    I can´t install ZAT on MacOs (Big Sur). I am getting this error:

    Building native extensions. This could take a while...

    ERROR:  Error installing zendesk_apps_tools:

    ERROR: Failed to build gem native extension.

    current directory: /Library/Ruby/Gems/2.6.0/gems/thin-1.7.2/ext/thin_parser

    /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby -I /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0 -r ./siteconf20201127-3041-15b0xeb.rb extconf.rb

    /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/universal-darwin20/rbconfig.rb:229: warning: Insecure world writable dir /Applications/XAMPP/xamppfiles in PATH, mode 040777

    checking for main() in -lc... yes

    creating Makefile


    I tried this: 

    sudo gem install thin -- --with-cflags="-Wno-error=implicit-function-declaration"

    But it didn´t work.

    Do you know how to fix it? I have been Googling it for a while, and could not find anything useful.

    Thanks a lot :)

  • Bryan - Community Manager
    Comment actions Permalink

    Hi Cesar. Try this modified command, which contains a specific version number for the "thin" gem:

    gem install thin -v 1.7.2 -- --with-cflags="-Wno-error=implicit-function-declaration"

    And just for reference, while this other post references Catalina, some here in the community have said it got them working:

    Fix for ZAT Tools not running under macOS Catalina

    On a side note, for my Ruby environment, I used rbenv to manage my different Ruby versions. The instructions here for setting up an environment that uses rbenv should still work on Big Sur: System prep for app developers

  • Chris Stock
    Comment actions Permalink

    Hi Gary Kester I know this doesn't help with your Ruby woes, but you might like to try the new node.js based CLI -

    I found it much easier to get going on Windows. It's still in beta I think, but it seems to work pretty well.

  • Gary Kester
    Comment actions Permalink

    Hi @.... I managed to get it all up and running using ZCLI instead of ZAT which I installed on a separate pc.

    I had to figure a few things but got there eventually. 

    Some points to note:

    • to run a local server it uses zcli apps:server which I just ran from the same folder where the manifest.json file was instead of specifying the directory when running it.
    • I didn't have to use Ubuntu or Ruby and npm and yarn were all I needed so much easier to get up and running as a windows user,
    • The images I added into assets weren't uploaded in the package so I just changed the href to images saved in Zendesk,

    At this point, I've managed to create a custom application and load it into Zendesk that my support team is busy testing.



  • Marci Abraham
    Comment actions Permalink

    I'm running into a brick wall with instaling ZAT tools on a Mac (Catalina 10.15.7 (19H2)). I have Ruby installed (ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]) but when I try to install zat, I keep getting a makefile error. I have reviewed the log, installed XCode and Homebrew (based on advice from various forums)...and generally I have been down rabbit holes all over the web trying to resolve this, but so far no joy. I would appreciate any help! I am feeling quite stuck.

  • Bryan - Community Manager
    Comment actions Permalink

    Gary Kester that's great to hear. I'll forward this to the product team with your earlier issue, just to keep them up-to-date.


    Marci Abraham — This has come up recently with some other users and looks like it has to do with Big Sur/XCode changes. Try the below (but as mentioned in a previous comment above, the 'zcli' option is the better long term approach as this will be the only tool available after 'zat' is end-of-lifed down the road).

    OPTION 1:
    Does a line appear after the above output look like this? Have you looked into this file and it says something about openssl? This is a compile-time issue. There's a dependency that isn't being met with the current macOS and/or openssl features installed.

    To see why this extension failed to compile, please check the mkmf.log which can be found here:  

    It's not clear what exactly is missing at this point in your environment, but if you can resolve the dependencies mentioned in the mkmf.log, that may get things working.

    OPTION 2:
    Relying on the macOS, natively installed version of Ruby limits your ability to change versions easily. I don't know if you use package manager "Homebrew" and Ruby version manager "rbenv", but they can make setup and changes a lot easier. To see an alternative environment setup approach that uses these tools, see System prep for app developers.

    Part of those steps are installing and using Homebrew and rbenv. These will let you move away from the default version of Ruby that comes with macOS (2.6, which is a couple of years old) and move to a newer version easily, such as 2.7.2. Using this environment may also end up resolving these build dependencies.

    OPTION 3:
    As mentioned above, 'zat' is going to be deprecated and at some point and end-of-lifed (possibly within the next year). If you want to get ahead of the curve, you can switch to 'zcli' — the new command line tool to build ZAF apps. See

    Despite it being "beta", it is close to a shipping state (i.e. stable) and will probably be generally available in Q1 of 2021. It's set of dependencies are different than the 'zat' tool's and will avoid errors such as the one you're running into.

    So those are a few things to consider. If any of them *do* get you going, please post back here and share what worked!

  • Omer Kedar Costo
    Comment actions Permalink

    Using ububtu for windows 10 I got various errors relating to building native extensions when running:

    gem install zendesk_apps_tools

    Apparently ubuntu for windows 10 comes barebones with respect to dev tools:

    I had to install the following as root:

    apt-get install gcc

    apt-get install g++

    apt-get install make

    apt-get install ruby-dev

    apt-get install zlib1g-dev

    Then and only then did I manage to install the ZAT gem.

  • Brett Bowser
    Comment actions Permalink

    Hey Omer,

    I see this is your first post so I wanted to say Welcome to the Zendesk Community :)

    Appreciate you taking the time to share this information with everyone as I'm sure others have run into a similar issue.

    Let us know if you have any other questions!

  • PA-eps
    Comment actions Permalink

    I'm running into an issue with installing the ZAT. I'm getting the following error:

    Fetching zendesk_apps_tools-3.8.1.gem
    Fetching zendesk_apps_support-4.29.7.gem
    Building native extensions. This could take a while...
    ERROR: Error installing zendesk_apps_tools:
    ERROR: Failed to build gem native extension.

    current directory: /Users/me/.rbenv/versions/3.0.1/lib/ruby/gems/3.0.0/gems/mimemagic-0.3.10/ext/mimemagic
    /Users/me/.rbenv/versions/3.0.1/bin/ruby -I/Users/me/.rbenv/versions/3.0.1/lib/ruby/3.0.0 -rrubygems /Users/me/.rbenv/versions/3.0.1/lib/ruby/gems/3.0.0/gems/rake-13.0.3/exe/rake RUBYARCHDIR\=/Users/me/.rbenv/versions/3.0.1/lib/ruby/gems/3.0.0/extensions/x86_64-darwin-19/3.0.0/mimemagic-0.3.10 RUBYLIBDIR\=/Users/me/.rbenv/versions/3.0.1/lib/ruby/gems/3.0.0/extensions/x86_64-darwin-19/3.0.0/mimemagic-0.3.10
    rake aborted!
    Could not find MIME type database in the following locations: ["/usr/local/share/mime/packages/", "/opt/homebrew/share/mime/packages/", "/opt/local/share/mime/packages/", "/usr/share/mime/packages/"]

    Ensure you have either installed the shared-mime-info package for your distribution, or
    obtain a version of and set FREEDESKTOP_MIME_TYPES_PATH to the location
    of that file.

    This gem might be installed as a dependency of some bigger package, such as rails, activestorage,
    axlsx or cucumber. While most of these packages use the functionality of this gem, some gems have
    included this gem by accident. Set USE_FREEDESKTOP_PLACEHOLDER=true if you are certain that you
    do not need this gem, and wish to skip the inclusion of

    The FREEDESKTOP_PLACEHOLDER option is meant as a transitional feature, and will be deprecated in
    the next release.

    Tasks: TOP => default
    (See full trace by running task with --trace)

    rake failed, exit code 1

    It seems ZAT or its dependency (zendesk_apps_support) depends on a version of `mimemagic` that is no longer available.

    Unfortunately I don't know how to work-around this.


  • Jamal Westfield
    Comment actions Permalink

    I am facing the same issue as above

  • PA-eps
    Comment actions Permalink

    Brett Bowser - I apologize for tagging you directly. I see you're from the "Community Team" that recently looked into this documentation. Would you be able to help getting in touch with whoever maintains the following tools?

    Unfortunately I'm blocked from updating my theme with some new code/requirements because of the issue mentioned above.




Please sign in to leave a comment.

Powered by Zendesk