Build PhyStack
Login
Overview · Build PhyStack

Overview

This guide explores some of advanced PhyOS features that address real-world challenges developers face when building edge-based solutions and digital experiences.

🧑‍💻 Enabling Developer Mode

Developer Mode allows you to directly deploy and test your 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.

Benefits of Developer Mode:

  • Deploy code changes directly to your device
  • Iterate faster with immediate code deployment and testing
  • Test instantly without waiting for build processes

⚠️ Important: Developer Mode should never be enabled on production devices. To disable Developer Mode, you must re-provision your device before deploying it to a production environment.

To enable Developer Mode on your device:

phy dev shell <device-name>

Once connected to the device:

  1. Press Enter to bring up the interactive menu

  2. Select Advanced and press Enter

  3. Select Enable Developer Mode and press Enter

  4. Choose from the following authentication methods:

    Option 1: Set Custom Password

    • Select Set Password and press Enter
    • Enter a custom password when prompted
    • Confirm the password to complete setup

    Option 2: SSH Public Key Authentication (Recommended)

    • Select Provide SSH public key and press Enter
    • Paste your public SSH key when prompted
    • This method provides enhanced security and convenience

    Option 3: Default Password

    • Select Use default password (123) and press Enter
    • Uses the default password "123"

Note: If you don't have an SSH public key, you can generate one using the following commands:

macOS:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "[email protected]"

# Display the public key to copy
cat ~/.ssh/id_rsa.pub

Windows (PowerShell):

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "[email protected]"

# Display the public key to copy
Get-Content ~/.ssh/id_rsa.pub

Linux:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "[email protected]"

# Display the public key to copy
cat ~/.ssh/id_rsa.pub

🌐 Proxy Settings

All PhyOS devices connect to a regional platform proxy for security and simplified network configuration on-site. This default setup is recommended for optimal performance and ease of deployment. However, this may not be possible in corporate environments with mandatory proxy requirements or specific compliance and security policies.

In these cases, you can configure PhyOS devices to connect to another proxy to maintain compliance with mandatory network policies.

Important: Your custom proxy must allow traffic to the PhyStack platform. For specific network configuration requirements, contact [email protected].

Setting Up Custom Proxy

To configure a custom proxy on your PhyOS device, connect to your device:

phy dev shell <device-name>

Once connected to the device:

  1. Press Enter to bring up the interactive menu
  2. Select Advanced and press Enter
  3. Select Set Custom Proxy and press Enter
  4. Select Set proxy settings and press Enter
  5. Provide the following proxy configuration details:
    • Hostname: Enter the proxy server hostname or IP address
    • Port: Enter the proxy server port number (typically 8080, 3128, or 8888)
    • Username: Enter your proxy authentication username
    • Password: Enter your proxy authentication password

Important Considerations:

  • Verify authentication credentials with your network administrator
  • Some proxy configurations may require additional certificates related configuration - see Certificate Authority (CA) Configuration section

Verifying Proxy Configuration

To verify your custom proxy configuration is working correctly, test connectivity by running the following command in the device shell:

curl -v https://<hostname>

Choose a hostname that supports HTTPS and is accessible through your proxy configuration.

What to look for:

* Uses proxy env variable https_proxy == 'http://proxy_username:proxy_password@<hostname>:<port>'

This output line confirms that your proxy configuration is active and being used by the system.

Successful Proxy Indicators:

  • The command completes without connection errors
  • You see the proxy environment variable being used

If you see this output, your custom proxy configuration is working correctly and all traffic from your PhyOS device will route through the specified proxy server.

Resetting Proxy Settings

To remove custom proxy settings and restore default proxy configuration:

  1. In the interactive menu, select Advanced
  2. Select Set Custom Proxy and press Enter
  3. Select Clear proxy settings and press Enter

💡 Tip: Always test your proxy configuration in a development environment before deploying to production devices. Incorrect proxy settings can prevent your device from connecting to PhyStack services.

🔐 Certificate Authority (CA) Configuration

When using a custom proxy that performs SSL/TLS inspection, you may need to install custom CA certificates on the device to ensure proper certificate validation for HTTPS connections.

Adding CA Certificates

To configure custom Certificate Authority certificates on your PhyOS device:

phy dev shell <device-name>

Once connected to the device:

  1. Press Enter to bring up the interactive menu

  2. Select Advanced and press Enter

  3. Select CA (add certificate authority trust) and press Enter

  4. Enter the URL of the CA certificates when prompted

  5. Specify whether you need to use a proxy to download the certificate:

    Option 1: Direct Download (No Proxy)

    • Enter n when asked "Do you need to use a proxy to download the certificate?"
    • The system will download and install the CA certificates directly

    Option 2: Proxy-Assisted Download

    • Enter y when asked "Do you need to use a proxy to download the certificate?"
    • Provide the following proxy configuration details:
      • Hostname: Enter the proxy server hostname or IP address for certificate download
      • Port: Enter the proxy server port number (typically 8080, 3128, or 8888)
      • Username: Enter your proxy authentication username (optional)
      • Password: Enter your proxy authentication password (optional)

Certificate URL Formats

The CA certificate URL should point to a valid certificate file or certificate bundle. Common formats include:

  • PEM Format: https://your-ca-server.com/ca-certificate.pem
  • CRT Format: https://your-ca-server.com/ca-certificate.crt
  • Certificate Bundle: https://your-ca-server.com/ca-bundle.crt

Verification

After adding CA certificates, verify they are working as expected:

curl -v https://<hostname>

Choose a hostname that supports HTTPS and is accessible through your proxy configuration.

⚠️ Security Note: Only add CA certificates from trusted sources. Adding untrusted certificates can compromise the security of your device and network communications.

🔒 TPM 2.0 Support

PhyOS integrates Trusted Platform Module (TPM) 2.0 support, providing hardware-based security for applications running at the edge. This feature enables secure storage of sensitive data—such as API keys, certificates, and passwords—directly in hardware, eliminating the need for filesystem-based credential storage and significantly reducing security risks.

Benefits of TPM 2.0 Support:

  • Store secrets in hardware-protected memory, never on disk
  • Eliminate accidental credential exposure to operations staff
  • Simple API accessible from any programming language
  • No TPM libraries or tooling required in your applications
  • Automatic hardware detection and graceful fallback
  • Secrets persist across device reboots and OS upgrades

💡 Why This Matters: Traditional approaches store credentials in configuration files, environment variables, or container secrets—all of which can be accidentally exposed through logs, backups, or file system access. TPM 2.0 moves these secrets into hardware-protected storage, making them inaccessible even to users with root access to the filesystem.

What is TPM 2.0?

TPM 2.0 (Trusted Platform Module version 2.0) is an international standard for a secure cryptoprocessor—a dedicated hardware chip designed for security operations. Think of it as a secure vault built into your device's hardware that provides:

  • Cryptographic Key Generation: Hardware-based generation of encryption keys
  • Secure Storage: Tamper-resistant storage for sensitive data
  • Hardware Random Number Generation: True randomness for cryptographic operations
  • Root of Trust: A hardware foundation for platform security

Platform Support and Hardware Requirements

TPM 2.0 support is available on all Intel architecture devices that include TPM hardware. The same PhyOS image works seamlessly across devices with or without TPM chips—the system automatically detects available hardware and enables TPM features only when supported.

Hardware Detection:

PhyOS automatically detects TPM hardware availability. On devices without TPM hardware, the service remains disabled, ensuring seamless operation across different hardware configurations.

Architecture Components:

The implementation consists of three main components that work together to provide TPM functionality:

  1. TPM Software Stack (tpm2-tss): Core library providing standardized TPM 2.0 operations
  2. TCTI Device Support (libtss2-tcti-device): Communication interface for direct TPM device access
  3. TPM Daemon (tpmd): System service that abstracts TPM complexity and provides the application API

💡 Developer Benefit: Your applications don't need TPM CLI tools (tpm2-tools) or TPM libraries. The daemon handles all TPM operations behind a simple JSON API, keeping your application dependencies minimal.

How TPM Daemon Works

The TPM daemon (tpmd) is a system service that runs on PhyOS and handles all TPM operations. It provides a simple API over a Unix socket, allowing your applications to store and retrieve secrets without dealing with TPM complexity.

The Storage Model:

When you store a secret, here's what happens behind the scenes:

  1. First Run Initialization: On first startup, the daemon generates a 32-byte random authorization value using the TPM's hardware random number generator. This value is stored inside the TPM and never touches the filesystem.

  2. Secret Storage: When you store a secret, the daemon:

    • Computes a hash of your secret name to determine its storage location
    • Stores your secret data in the TPM's non-volatile (NV) memory
    • Stores the name hash in a metadata area for lookup
    • Protects both areas with the per-device authorization value

  3. Secret Retrieval: When you retrieve a secret, the daemon:

    • Authenticates to the TPM using the authorization value (stored in RAM)
    • Looks up your secret by hashing the name you provided
    • Reads the secret data from TPM NV memory
    • Returns the secret to your application (exists in RAM only during the request)

The daemon uses a hash-based slot mechanism to map secrets to storage locations algorithmically—no mapping table is needed, and nothing is stored in the filesystem.

💡 How It's Different: Traditional secret management stores credentials in files (even if encrypted) or environment variables. TPM-based storage keeps secrets in dedicated hardware that's inaccessible to the filesystem, backups, logs, or any software-based extraction method.

Using TPM Secrets in Your Applications

To learn how to use TPM secrets in your applications, including API details, code examples, and best practices, see Managing On-Device Secrets.

© 2026 · PhyStack. An Ombori company