Dev Environment Setup

Your local development environment is where you’ll build, test, and publish PhyStack apps using the PhyStack CLI.

Once configured, you’ll be able to create edge apps, screen apps, and manage other aspects of your PhyStack workflow from your terminal.

Prerequisites

A PhyStack Tenant

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

Software Requirements

Before installing the PhyStack CLI, make sure your development machine meets these requirements:

Supported Operating Systems

• macOS 15.4+
• Ubuntu 22.04/24.04

Note: Windows support is coming soon. For now, you can use WSL2 with Ubuntu.

Required Software

• Node.js 24+
• Git

For Edge Apps (Optional)

If you plan to build edge apps, you’ll also need:

• Docker Desktop

Step-by-Step: Environment Setup

1. Install the PhyStack CLI

Install the CLI globally using npm:

npm i -g @phystack/cli

Verify the installation was successful:

phy --version

If you see the CLI version printed without errors, you’re ready to proceed.

2. Authenticate

Connect your CLI to your PhyStack tenant:

phy login

This command will:

• Open your default web browser
• Prompt you to authenticate with your PhyStack account
• Show a confirmation prompt in the browser, confirm to complete the login

If you’re already logged into your PhyStack tenant in your browser, you can confirm the operation without re-entering credentials.

Headless Authentication

If you’re using the CLI in an environment without a GUI browser, use the device code flow:

phy login --use-device-code

Follow the instructions displayed in your terminal to authenticate using a web browser on another device.

Verify Authentication

Once authentication is complete, verify your CLI connection by listing your available tenants:

phy tenant list

If you see your tenant’s name displayed without any errors, your authentication is working correctly and you’re ready to proceed.

3. Configure Docker (For Edge Apps)

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

To do this:

1. Open Docker Desktop
2. Go to Settings General
3. Enable the option “Use containerd for pulling and storing images”
4. Click Apply & Restart

This feature is available in Docker Desktop ≥ 4.29

Authenticate with Docker Hub

If you plan to use Docker Hub as your container registry, log in now:

docker login

This ensures the Docker CLI can pull and push images during the app creation process.

Simulator

The PhyStack CLI includes a local device simulator for testing apps without a physical device. Both screen and edge app templates integrate with the simulator out of the box.

For full simulator documentation including commands, options, and how it works, see the Simulator reference.

Checkpoint

After completing these steps, you should have:

• PhyStack CLI installed, authenticated and working
• Docker configured (if building edge apps)
• Simulator available for local testing

Next Steps

With your development environment ready, you can now:

• Provision your first device
• Build your first edge app
• Build your first screen app

Troubleshooting

CLI Installation Issues

Problem: phy command not found after installation
Solution: Make sure your npm global bin directory is in your PATH:

npm config get prefix

Add <prefix>/bin to your PATH if it’s not already there.

Authentication Issues

Problem: Browser doesn’t open during phy login
Solution: Use the device code flow: phy login --use-device-code

For additional help, contact support at [email protected].