A command-line tool for managing Trusted Execution Environment (TEE) deployments on Phala Cloud, from local development to cloud deployment.

Phala Network Discord | GitHub Issues | Phala Documentation

Usage

• Dstack-TEE: Dstack
• Bun for runtime and package management
• TypeScript for type safety
• Commander.js for CLI interface
• Zod for runtime validation

🚀 Quick Start (5 Minutes)

1. Install Prerequisites:

   # Install Bun
   curl -fsSL https://bun.sh/install | bash
      
   # Verify Docker is installed
   docker --version

2. Install TEE Cloud CLI:

   Install via npm or use npx/bunx

   # Install the CLI globally
   npm install -g phala

   NOTE

   You can use npx or bunx to call the phala command

   # Use npx/bunx
   
   npx phala help
   bunx phala help

   # Phala CLI help menu
   npx phala help

3. Sign Up and Get API Key:

   To deploy applications to Phala Cloud, you'll need an API key:

   • Visit Phala Cloud to log into your Phala Cloud account. If you do not have an account, register with this link with PROMO_CODE or run npx phala free in the terminal.
   • After logging in, navigate to the "API Keys" section in your profile
   • Create a new API key with an appropriate name (e.g., "CLI Access")
   • Copy the generated API key - you'll need it for authentication
   • You can verify your API key using:

     phala auth login [your-phala-cloud-api-key]
     phala auth status

4. Deploy Your First Confidential App: Clone the Dstack Examples repo and cd into the webshell directory

   git clone https://github.com/Dstack-TEE/dstack-examples.git && cd dstack-examples/webshell

   # Deploy the webshell Dstack example
   phala cvms create

   Provide a name and select from the drop down of examples

   # ? Enter a name for the CVM: webshell
   # ℹ Detected docker compose file: ./docker-compose.yml
   
   # ? Enter the path to your Docker Compose file:(docker-compose.yml)
   #   ✔ Enter number of vCPUs (default: 1): 1
   
   #   ✔ Enter memory in MB (default: 2048): 2048
   #   ✔ Enter disk size in GB (default: 20): 20
   #   ⟳ Fetching available TEEPods... ✓
   #   ⟳ Getting public key from CVM... ✓
   #   ⟳ Encrypting environment variables... ✓
   #   ⟳ Creating CVM... ✓
   #   ✓ CVM created successfully
   #   ℹ CVM ID: 2755
   #   ℹ Name: webshell
   #   ℹ Status: creating
   #   ℹ App ID: e15c1a29a9dfb522da528464a8d5ce40ac28039f
   #   ℹ App URL: <https://cloud.phala.network/dashboard/cvms/app_e15c1a29a9dfb522da528464a8d5ce40ac28039f>
   #    ℹ
   #    ℹ Your CVM is being created. You can check its status with:
   #    ℹ phala cvms status e15c1a29a9dfb522da528464a8d5ce40ac28039f

   Now interact with your application in Phala Cloud by going to the url on port 7681 (Example of what a url at port 7681 would look like https://e15c1a29a9dfb522da528464a8d5ce40ac28039f-7681.dstack-prod5.phala.network)

5. Check the CVM's Attestation:

   phala cvms attestation
   
   # ℹ No CVM specified, fetching available CVMs...
   # ⟳ Fetching available CVMs... ✓
   # ✔ Select a CVM: testing (88721d1685bcd57166a8cbe957cd16f733b3da34) - Status: running
   # ℹ Fetching attestation information for CVM 88721d1685bcd57166a8cbe957cd16f733b3da34...
   # ⟳ Fetching attestation information... ✓
   # ✓ Attestation Summary:
   
   # or list the app-id
   phala cvms attestation 88721d1685bcd57166a8cbe957cd16f733b3da34

🏗️ Development Workflow

1️⃣ Local Development

Develop and test your application locally with the built-in TEE simulator:

# Start the TEE simulator
phala simulator start

# Build your Docker image
phala docker build --image my-tee-app --tag v1.0.0

# Create an environment file
echo "API_KEY=test-key" > .env
echo "DEBUG=true" >> .env

2️⃣ Cloud Deployment

Deploy your application to Phala's decentralized TEE Cloud:

# Set your Phala Cloud API key
phala auth login

# Login to Docker and Push your image to Docker Hub
phala docker login
phala docker build --image my-tee-app --tag v1.0.0
phala docker push --image my-tee-app --tag v1.0.0

# Deploy to Phala Cloud
phala cvms create --name my-tee-app --compose ./docker-compose.yml --env-file ./.env

# Access your app via the provided URL

💼 Real-World Use Cases for Confidential Computing

🏦 Financial Services

• Private Trading Algorithms: Execute proprietary trading strategies without revealing algorithms
• Secure Multi-Party Computation: Perform financial calculations across organizations without exposing sensitive data
• Compliant Data Processing: Process regulated financial data with provable security guarantees

🏥 Healthcare

• Medical Research: Analyze sensitive patient data while preserving privacy
• Drug Discovery: Collaborate on pharmaceutical research without exposing intellectual property
• Health Record Processing: Process electronic health records with HIPAA-compliant confidentiality

🔐 Cybersecurity

• Secure Key Management: Generate and store cryptographic keys in hardware-protected environments
• Threat Intelligence Sharing: Share cyber threat data across organizations without exposing sensitive details
• Password Verification: Perform credential validation without exposing password databases

🏢 Enterprise Applications

• Confidential Analytics: Process sensitive business data without exposure to cloud providers
• IP Protection: Run proprietary algorithms and software while preventing reverse engineering
• Secure Supply Chain: Validate and process sensitive supply chain data across multiple organizations

🌐 Web3 and Blockchain

• Private Smart Contracts: Execute contracts with confidential logic and data
• Decentralized Identity: Process identity verification without exposing personal information
• Trustless Oracles: Provide verified external data to blockchain applications

🧩 Project Structure

The Phala Cloud CLI is organized around core workflows:

1. Authentication: Connect to your Phala Cloud account
2. TEEPod Info: Fetch information about TEEPods (TEEPods are where your docker apps deploy to)
3. Docker Management: Build and manage Docker images for TEE
4. TEE Simulation: Local development environment
5. Cloud Deployment: Deploy to production and manage TEE Cloud deployments

📚 Command Reference

The Phala Cloud CLI provides a comprehensive set of commands for managing your TEE deployments. Below is a detailed reference for each command category.

Authentication Commands

Commands for managing authentication with the Phala Cloud API.

Login

phala auth login [options]

Set the API key for authentication with Phala Cloud. The API key is stored with encryption for enhanced security.

Options:

• [api-key]: Phala Cloud API key to set

Example:

phala auth login [your-phala-cloud-api-key]

Logout

phala auth logout

Remove the stored API key.

Example:

phala auth logout

Status

phala auth status [options]

Check your authentication status with Phala Cloud. Displays user information in a table format.

Options:

• -j, --json: Output in JSON format

Example:

phala auth status
phala auth status --json

Docker Management Commands

Commands for managing Docker images for TEE deployments.

Docker Login

phala docker login [options]

Login to Docker Hub to enable pushing and pulling images.

Options:

• -u, --username <username>: Docker Hub username (if not provided, you will be prompted)
• -p, --password <password>: Docker Hub password (if not provided, you will be prompted)
• -r, --registry <registry>: Docker registry URL (optional, defaults to Docker Hub)

Example:

phala docker login --username your-dockerhub-username

Build Docker Image

phala docker build [options]

Build a Docker image for your TEE application.

Options:

• -i, --image <image>: Image name (required)
• -t, --tag <tag>: Image tag (required)
• -f, --file <file>: Path to Dockerfile (defaults to 'Dockerfile')

Example:

phala docker build --image my-tee-app --tag v1.0.0 --file ./Dockerfile

Push Docker Image

phala docker push [options]

Push a Docker image to Docker Hub.

Options:

• -i, --image <image>: Image name (required)
• -t, --tag <tag>: Image tag (required)

Example:

phala docker push --image my-tee-app --tag v1.0.0

Build Docker Compose File

phala docker generate [options]

Build a Docker Compose file for your TEE application.

Options:

• -i, --image Docker image name to use in the compose file
• -t, --tag Docker image tag to use in the compose file
• -e, --env-file Path to environment variables file
• -o, --output Output path for generated docker-compose.yml
• --template Template to use for the generated docker-compose.yml
• --manual Skip automatic image detection and enter image/tag manually
• -h, --help display help for command

Example:

phala docker generate --image my-tee-app --tag v1.0.0 --env-file ./.env

TEE Simulator Commands

Commands for managing the local TEE simulator for development and testing.

Start Simulator

phala simulator start [options]

Start the TEE simulator locally for development and testing.

Options:

• -i, --image <image>: Simulator image (defaults to 'phalanetwork/tappd-simulator:latest')

Example:

phala simulator start

Stop Simulator

phala simulator stop

Stop the running TEE simulator.

Example:

phala simulator stop

Cloud Virtual Machine (CVM) Commands

Commands for managing Cloud Virtual Machines (CVMs) on Phala Cloud.

List CVMs

phala cvms list|ls [options]

List all CVMs associated with your account.

Options:

• -j, --json: Output in JSON format

Example:

phala cvms list

Get CVM Details

phala cvms get [options] <app-id>

Get detailed information about a specific CVM.

Arguments:

• app-id: App ID of the CVM

Options:

• -j, --json: Output in JSON format

Example:

phala cvms get app_123456

Create CVM

phala cvms create [options]

Create a new CVM on Phala Cloud.

Options:

• -n, --name <name>: Name of the CVM (required)
• -c, --compose <compose>: Path to Docker Compose file (required)
• --vcpu <vcpu>: Number of vCPUs (default: 1)
• --memory <memory>: Memory in MB (default: 2048)
• --disk-size <diskSize>: Disk size in GB (default: 20)
• --teepod-id <teepodId>: TEEPod ID to launch the CVM to (default: 3)
• --image <image>: Version of dstack image to use (i.e. dstack-0.3.5)
• -e, --env-file <envFile>: Environment variables in the form of KEY=VALUE
• --skip-env: Path to environment file (default: false)
• --debug: Enable debug mode

Example:

phala cvms create --name my-tee-app --compose ./docker-compose.yml --vcpu 2 --memory 4096 --diskSize 60 --teepod-id 3 --image dstack-dev-0.3.5 --env-file ./.env

Upgrade CVM

phala cvms upgrade [options] <app-id>

Upgrade a CVM to a new version.

Arguments:

• app-id: App ID of the CVM to upgrade

Options:

• -c, --compose <compose>: Path to new Docker Compose file
• --env-file <envFile>: Path to environment file
• --debug: Enable debug mode

Example:

phala cvms upgrade app_123456 --compose ./new-docker-compose.yml --env-file ./.env

Start CVM

phala cvms start [app-id]

Start a stopped CVM.

Arguments:

• app-id: App ID of the CVM to start

Example:

phala cvms start e15c1a29a9dfb522da528464a8d5ce40ac28039f

Stop CVM

phala cvms stop [app-id]

Stop a running CVM.

Arguments:

• app-id: App ID of the CVM to stop

Example:

phala cvms stop e15c1a29a9dfb522da528464a8d5ce40ac28039f

Restart CVM

phala cvms restart [app-id]

Restart a CVM.

Arguments:

• app-id: App ID of the CVM to restart

Example:

phala cvms restart e15c1a29a9dfb522da528464a8d5ce40ac28039f

Delete CVM

phala cvms delete [options] <app-id>

Delete a CVM.

Arguments:

• app-id: App ID of the CVM to delete

Options:

• -f, --force: Skip confirmation prompt

Example:

phala cvms delete e15c1a29a9dfb522da528464a8d5ce40ac28039f
phala cvms delete --force e15c1a29a9dfb522da528464a8d5ce40ac28039f

📋 Sample Applications

Explore these example applications to understand different use cases for TEE deployment:

• Timelock Encryption: Encrypt messages that can only be decrypted after a specified time
• Light Client: A lightweight blockchain client implementation
• SSH Over TEE Proxy: Secure SSH tunneling through a TEE
• Web Shell: Browser-based secure terminal
• Custom Domain: Deploy with your own domain name
• Private Docker Image: Deploy using private Docker registries

🛠️ Advanced Features

Docker Compose Templates

This feature is still being developed. Best to build your own docker-compose file for now.

(WIP) Choose from docker compose file for your application:

phala docker generate --image my-app --tag v1.0.0 --env

Customizing Resource Allocation

Resize specific resources for your existing CVM:

phala cvms resize e15c1a29a9dfb522da528464a8d5ce40ac28039f --name resource-intensive-app --compose ./compose.yml \
  --vcpu 4 --memory 8192 --disk-size 50 -r true -y

Environment Variables Management

# Using env file
phala cvms create --name env-app --compose ./compose.yml --env-file ./.env

🔒 Security

The TEE Cloud CLI employs several security measures:

1. Encrypted Credentials: API keys and Docker credentials are stored with encryption using a machine-specific key
2. Restricted Permissions: All credential files are stored with 0600 permissions (user-only access)
3. No Validation Storage: API keys are not validated during login, preventing unnecessary transmission
4. Local Storage: All credentials are stored locally in the ~/.phala-cloud/ directory

🔍 Troubleshooting

Common issues and solutions:

1. Docker Build Fails

   • Verify Docker daemon is running
   • Check Dockerfile path
   • Ensure proper permissions

2. Simulator Issues

   • Check if port 8090 is available
   • Verify Docker permissions

3. Cloud Deployment Fails

   • Validate API key
   • Confirm image exists on Docker Hub
   • Check environment variables

For detailed help:

phala --help
phala <command> --help

📝 License

Apache 2.0

🤝 Contributing

To contribute or run in development mode:

bun run src/index.ts