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

🖥 Simulator

Important: The simulator currently supports Node-based edge and screen apps only. Python support is coming soon.

The PhyStack CLI includes a local device simulator that simulates the on-device environment and runtime locally, letting you test application logic, settings behavior, and more. You can also test messaging between multiple apps running on your computer and connected to the same simulator instance. The simulator runs in offline mode and does not fully replicate the real device environment, so always verify your app on a real device before publishing.

Screen and edge boilerplate templates already integrate with the simulator out of the box.

Starting the Simulator

Start the simulator server:

phy simulator start

Running Apps

Once the simulator is running, launch an app against it:

phy simulator run <path>

To run the app in the current directory:

phy simulator run .

How It Works

The simulator injects the PHYSTACK_SIMULATOR_URL environment variable, which instructs the PhyStack SDK in your app to connect to the local simulator instance instead of the edge runtime on the device. It also creates a local simulated twin and provides the mandatory TWIN_ID environment variable so your app can connect when running locally.

For screen apps, the TWIN_ID must be passed to the browser as a URL hash parameter (/#instanceId=<twin-id>). This mirrors how the production screen bootloader delivers the instance ID to screen apps running inside iframes. The Vite config in the screen app boilerplate handles this automatically by opening the browser with the correct hash when the simulator is active.

For this reason, your launch script should ensure these environment variables are propagated to your app on start. Screen and edge app boilerplate created using the CLI configures this for you out of the box.

When you run phy simulator run, the CLI performs the following steps:

1. App type detection — reads application-type from package.json, or uses the --type flag if provided
2. Twin and settings setup — creates a virtual simulated twin identity for the app and uses your local settings from src/settings/index.json (generates defaults from schema.ts if the file doesn't exist)
3. Launch:
   • Screen apps → runs npm start (or your custom --dev-command)
   • Edge apps with Dockerfile → builds a Docker image and runs the container with Docker config from settings.json
   • Edge apps without Dockerfile → falls back to npm start (or your custom --dev-command)

✅ Checkpoint

After completing these steps, you should have:

• PhyStack CLI installed, authenticated and working
• Docker configured (if building edge apps)
• Simulator running and able to launch apps locally (optional)

🔄 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 support@phystack.com.