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
Windows 10/11 (x64)

Note: Windows on ARM is not yet supported. On ARM devices, use WSL2 with Ubuntu.

Required Software

Node.js 24+
Bun 1.x — the app templates use Bun for scripts and package management
Git — phy app init scaffolds projects by cloning the template repositories

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, skip the automatic browser launch:

phy login --no-browser

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

CI and automation: don’t log in interactively. Create a personal access token with phy token create <name> and set it as the PHY_TOKEN environment variable in your pipeline.

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:

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

This feature is available in Docker Desktop ≥ 4.29

Log In to Your Container Registry

Edge app publishing pushes a container image to your registry. Log in once with the CLI:

phy registry login docker.io

The command stores a push credential and a read-only pull credential in your OS keychain, and sets the default registry the CLI derives image references from. The Edge App tutorial covers this step in detail, including the two access tokens you need. An existing docker login session works as a fallback for the push, but phy registry login is the supported flow.

4. Install the Device Simulator (Optional, Recommended)

The device simulator lets you run and test apps locally without a physical device. It ships as its own package, separate from the CLI:

npm i -g @phystack/device-simulator

This provides the phy-simulator binary. You rarely invoke it by hand — every app template wires it into bun run dev, which starts a simulated device and runs your app inside it.

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:

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 phy login --no-browser and open the printed URL on any device

For additional help, contact support at support@phystack.com.