Build An Edge App

🧠 What Are Edge Apps?

Edge apps are a type of application that runs on Phygrid-connected devices without a graphical user interface. These apps execute locally in the field as fully managed Phygrid containers, providing compute power and logic right where it's needed — at the edge.

Edge apps run on PhyOS-enabled devices. Just like screen apps, edge apps are:

• Published and managed via your Phygrid tenant
• Deployed and configured using the Console
• Integrated with platform features, including:
  • App versioning
  • Settings schemas
  • Centralized configuration and content management
  • Real-time event collection via Signals

🔧 Common Use Cases for Edge Apps

Edge apps are ideal for tasks that require local processing or interaction with hardware. Typical scenarios include:

• Running AI/ML models at the edge (e.g., object detection, people counting)
• Managing peripheral hardware not directly connected to the platform (e.g., doors, printers, sensors)
• Performing real-time data processing before syncing with the cloud

⚙️ How Edge Apps Work

• Runtime: Powered by Docker — each edge app runs inside an isolated container on the device.
• Language Flexibility: You can build edge apps in any language that runs in a Docker container.

Whether you're building hardware integrations, deploying AI workloads, or processing data locally, edge apps give you full control at the device level — all while being securely managed by the Phygrid platform.

🧰 Prerequisites

Official Phygrid templates and examples use Node with TypeScript, offering modern tooling, strong typing, and native SDK support. This is the stack we'll be working with throughout this tutorial.

Before you begin, make sure the following are set up and ready to go:

✅ A Phygrid Tenant

You'll need access to a Phygrid tenant. If you don't yet have one, please refer to the Tenant Setup guide.

✅ Local Development Environment with PhyCLI Installed and Configured

If you haven't set up CLI on your machine yet, refer to the Dev Environment Setup guide.

✅ A Docker Hub Account

For the purpose of this tutorial, you'll need a Docker.io account to publish your app as a container image.

Important: You'll need two sets of credentials:

• Push credentials (with read/write access): used locally for publishing your app image
• Pull credentials (read-only): embedded in your app and used by devices to fetch the image

✅ Docker Installed & Configured

Ensure you have Docker Desktop installed and configured for Phygrid.

You must enable the containerd image store, a requirement for proper edge apps image handling with Phygrid.

If you haven't set this up yet, refer to the Docker configuration section in the Dev Environment Setup guide.

🛠 Step-by-Step: Creating and Publishing an Edge App

Once your environment is ready, you can create and publish your first edge app. This process involves generating a starter project, configuring your Docker registry, building and pushing the app image, and finally uploading the app to your tenant.

1. Scaffold the Edge App project

Run the following command to begin:

phy app create

You'll be prompted to provide a name for your application. If you don't specify one via CLI args, you'll be asked interactively.

Then you'll select the app type - choose ❯ Edge Application

This tells the CLI to scaffold a non-GUI containerized edge application.

2. Set Up Your Container Registry

Next, you'll configure the container registry where your app image will be published.

• You'll be asked to enter a container registry — in this example, we will use docker.io (you can confirm the default value)
• Then, provide your Docker Hub username or organization name
• Finally, specify a unique image name for your app (or confirm the default name)

This registry configuration will be saved in your project's metadata so future builds and deployments know where to push the image.

3. Authenticate: Push Credentials (Read/Write)

The CLI will now attempt to push a test image to the registry to ensure everything is set up correctly.

You will be prompted to enter your Docker Hub username and a Personal Access Token (PAT) with read/write access.

This token is used locally to push the app image during development — it is not stored in the final app.

🔐 Tip: Never share these credentials with your team or include them in version control. They grant write access to your Docker registry.

4. Authenticate: Pull Credentials (Read-Only)

Once the push test succeeds, you'll be prompted for a second set of credentials — these are the pull credentials.

These are important because they will be:

• Stored in the app metadata
• Deployed to devices so they can download the container image

Use a read-only Docker PAT here to limit risk in case of compromise.

🚫 Never reuse your push token here — devices should never have write access to your registry.

These credentials are securely stored and reused for future builds to the same registry.

5. Build, Push & Register the App

With both sets of credentials in place, the CLI will now:

1. Pull the edge app boilerplate to your local machine
2. Build the app image using Docker
3. Push the image to your container registry
4. Create and upload the app to your Phygrid tenant

Once complete, your app will be available in the Phygrid Console, ready to be installed and deployed to any edge capable device. We will cover this part later in the tutorial.

You can explore your newly created project. In the directory with the project, you will find a containerized Node TypeScript application, including:

• Dockerfile for multi-arch build
• src/ directory with:
  • schema.ts – settings schema for your application with example settings (to learn more about settings schemas, check this how-to guide)
  • app.ts – application entry point with simple example code that performs basic logging to standard output
• Other files commonly found in Node projects, like package.json containing useful scripts, .nvmrc, tsconfig.json, and more

The app.ts file demonstrates the usage of @phygrid/hub-client package for platform integration.

The example code retrieves app settings through the Hub Client and logs them to the console.

✅ Checkpoint

After completing this process, you'll have:

• An edge app project on your local machine
• A Docker image published to your registry
• A new app available in your tenant for installation

🚀 Deploying the App to a PhyOS Device or VM

Now that your app is ready, the next step is to create an installation and deploy it to a PhyOS VM or a physical PhyOS device.

📦 Create an Installation

1. Log in to console.phygrid.com
2. Navigate to Apps > Developer and locate your app in the list
3. Press the Install button and provide a name for your new installation
4. After confirmation, you will be redirected to the Installation page
5. A build of your app will be created automatically as part of the installation

🔌 Connect a PhyOS Device

In this step, you can connect an edge-compatible PhyOS device (virtual or physical) to your installation.

For an overview of supported device types, refer to our Device Setup guide.

If you don't have a physical or virtual device ready now, skip to the Connect a PhyVM section.

1. Navigate to the Devices tab on your Installation page
2. Press the Connect a device button
3. In the modal that appears, click Setup a new device
4. Choose your device type from the available options
5. Follow the setup instructions displayed on the right side of the modal
6. Enter:
   • A name for the device
   • The serial number or provisioning code shown on your PhyOS device's screen
7. Confirm by pressing the Connect device button

For additional details on connecting devices to installations, check out this guide.

Once the device is successfully connected, you should see:

• The device name appear on the device screen
• The connection status update on the screen of the device
• Your app will be automatically downloaded and started

To verify deployment from your computer, run:

phy dev shell <device-name>

Replace <device-name> with the name used during setup (also shown on the device screen).

Once connected, select the Shell option from the menu and confirm.

Run the following to check if your app is running:

docker ps

You should see a container running, with a name matching your app's image.

To inspect logs, use:

docker logs <container-id> -f

The <container-id> is displayed as the first column in the docker ps output.

If everything is working correctly, you'll see output similar to:

Hello, world! 10
Settings: {
  "testSetting": "Default value"
}

If you run into issues at this stage, refer to the Troubleshoot & Debug article of the documentation.

💻 Connect a PhyVM

PhyVMs are a great option during development and for testing purposes. You can create a virtual PhyOS device using the Phy CLI. This is supported on macOS and Linux.

1. Run the following command:

phy app vm create

2. Provide a name for the VM (this is how you'll identify it later)
3. When prompted for VM architecture, confirm the default (host architecture)
4. Confirm:
   • Use of the latest PhyOS version
   • The default memory allocation

The CLI will now download the PhyOS image to your machine.

After the process is completed, a message will appear with the command to start your VM:

phy vm start <vm-name>

If dependencies are missing on your system, the CLI will prompt you to install them — confirm and wait for setup to complete.

Once the VM is running, follow the same steps as in the Connect a PhyOS Device section to connect it to your installation and verify the deployment. Select x86-64 as the device type from the available options.

✏️ Make Code Changes

Let's make some changes to see the development workflow in action.

Open src/app.ts and update the code by adding an additional console.log statement:

setInterval(() => {
  counter += 1;
  console.log('Hello, world!', counter);
  console.log('This is a test'); // <-- added
  console.log('Settings:', JSON.stringify(settings, null, 2));
}, 3000);

🚧 Enable Development Mode on PhyVM

Now let's deploy your code to the connected PhyVM in development mode. Please note that this feature is intended for development and iteration, not for managing production devices.

Developer Mode allows you to directly deploy and test your edge apps on the device without building and publishing them to the Console first. This feature significantly accelerates the development workflow by enabling rapid iteration and real-time debugging capabilities.

To enable development mode on the PhyVM, please follow this guide: Enabling Developer Mode.

For the best experience, we recommend using the SSH public key authentication method.

To deploy your local app changes directly to the VM running in development mode, use the deploy script:

yarn deploy <device-name>

This script uses the phy app deploy command, which performs the following operations:

• Syncs your local app files to the target device
• Executes a Docker build on the device using your local app's source code, creating a new container image
• Creates a local twin configuration that instructs the device to run this newly built image

Note: You can also enable developer mode on a physical or virtual PhyOS device using the same steps. Keep in mind that phy app deploy requires both the device and your host machine to be discoverable on the same network.

To verify that your changes were deployed successfully, access your PhyOS shell again:

phy dev shell <device-name>

Verify the new image is running:

docker ps

Then inspect the logs:

docker logs <container-id> -f

You should see updated output reflecting your changes:

Hello, world! 3
This is a test
Settings: {
  "testSetting": "New setting value"
}

Important: When a device is in developer mode with a local deployment, it will ignore app version updates from regular Console deployments. However, the device will continue to use settings from the Console.

Before proceeding to the next step, disable the local deployment by removing the local twins configuration:

rm /data/settings/phyhub/local-twins.json

After removing the file, restart your PhyVM (using phy vm restart <vm-name>) or reboot your PhyOS device.

🚀 Publish an Updated Version

Once your app is updated and working as expected, it's time to publish a new version and deploy it via the Console.

1. Open your project in your IDE
2. In package.json, increase the version number:

"version": "0.2.0"

3. Run the build script:

yarn build

This builds the updated Docker image, pushes it to your registry, and generates a new .gridapp file ready to be published.

4. Publish the new version to your tenant:

yarn pub

🧪 Test the New Version in Console

1. Go back to your installation in the Phygrid Console
2. Open the Settings tab and press Edit settings
3. Change the value of "A test setting" to "New setting value"
4. In the Version dropdown, select 0.2.0
5. Press Save all changes

When you access the Settings tab of your installation, you'll see that the settings defined in your app's schema.ts appear in the Console as an editable form.

After a few moments, your app will be redeployed with the new version to all connected devices.

You can connect to one of your devices using the same steps as before and verify your app's updated output by checking the container logs.

🎉 Success!

Your app is now running the updated version with modified code and updated settings.

You've successfully gone from creation to deployment, iteration, and production publishing — all with full integration into the Phygrid platform.

✅ Checkpoint

After completing this part of the tutorial, you should have:

• A fully functional edge app deployed and running on your device or VM
• An installation in your tenant

🔄 Next Steps

Now that your app is setup, you can:

• Create settings schema to manage your app's configuration
• Start integrating with peripheral twins
• Use Signals to emit events and monitor edge activity