App Store

To share your app with the world, you can submit it to the App Store.

To ensure maximum quality, submitting to the App Store comes with some extra requirements. Athom must approve your app before your app is visible to other users.


To check if all requirements are met, run the following command prior to submission.

$ athom app validate --level publish

App images

The App Store needs images to display your app. There are two sizes. Make sure it is a beautiful photo, or a stylish design.

  • Large 500 x 350 px /assets/images/large.png
  • Small 250 x 175 px /assets/images/small.png

Images must be provided in either .jpg or .png format.

large.jpg large.jpg

Driver images

If you have a driver, you should supply driver images. A driver image should have a white background and fill most of the image.

  • Large 500 x 500 px /drivers/<driver_id>/assets/images/large.png
  • Small 75 x 75 px /drivers/<driver_id>/assets/images/small.png

Images must be provided in either .jpg or .png format.

large small

Providing a README

It is useful for users to read a little bit about your app. What does it do, what doesn't work yet, etc. Your app's file is rendered in the App Store. This file is a markdown file.

Optionally, if a file named exists, then that file is shown in the App Store instead of the, which allows for a less-technical message.


# Hello World

This app adds support for FooBar lights to Homey.

What works:

* Connecting lights
* Connecting accessories


To make your app better searchable, add a translated array of tags to your App's json.


	"id": "com.nest",
	"name": {
		"en": "Nest"
	"tags": {
		"en": [ "learning thermostat" ]

Mention contributors

It is generally a good idea to give contributors credit. Because only one user can publish to the App Store, you can add multiple authors in your App's json.


	"id": "com.athom.example",
	"contributors": {
		"developers": [
				"name": "Alice the Wild",
				"email": ""
		"translators": [
				"name": "Klemens Kohlmann"

Environment variables

Sometimes your app must contain information that should not be public. While it is generally a bad idea to embed this in such an application, external services often don't provide a good alternative (for example OAuth2).

It is possible to add environment variables to a Homey app, by placing a /env.json in your app's root, and add it to your .gitignore.


	"CLIENT_ID": "12345abcde",
	"CLIENT_SECRET": "182hr2389r824ilikepie1302r0832"

The variables are available under Homey.env.CLIENT_ID, Homey.env.CLIENT_SECRET, etc. Make sure they are uppercase, and that their value is a string.

When submitting your app, you can enter the variables during the submission process.

These variables are stored on Homey, and in theory should not be readable by anyone. But keep in mind that no security is 100% safe, ever.

Node.js modules

If you are using Node.js modules, check them into your repository in a folder /node_modules. You could add an additional /package.json file to keep track of them.

The reason to check those modules in, is to speed up the app installation process. If Homey has to run a npm install every time an app is installed, this will make it really slow. Additionally, you ensure that the dependencies always stay the same.

Submission process

Anyone can submit an app for free. To submit your App, go to Submission usually will take a few days, depending on the size of your app.

Published apps must be open-source, and hosted in a Git repository. Publishing apps without disclosing the source is possible by contacting

After a version update, your app will have to be reviewed again.

Submission guidelines

A few guidelines have been established to keep the community working together in unison.

App License

  • Adding a LICENSE file helps other developers understand if they can copy your app, modify it, etc.
  • As a rule of thumb, Athom will look at the submission process and if an app has been forked or is a duplicate, the license file of the original repository will be leading.

One Homey App per brand

  • As a community developer, you are part of a community where we are working towards the common goal of making home automation accessible to everyone. This means we must keep things simple, so ideally there is only one app per brand. We encourage developers to work together by sending Pull Requests to the original author and give credit where due.
  • In the event where a similar app submission is absolutely necessary, please elaborate in your submission why, and make sure it is clear to the end-user.


  • A donate button is only allowed as a field in the App Manifest.
  • A donate button is not allowed when an app is based on a fork.

Explicit content

  • Apps with adult content (e.g. pornography) are not allowed.

Athom holds the right to make the final descicion if an app will be approved.