Aspire Polyglot AppHost SDK Guide - Python, Go, Java, Rust (PR #13978)

aspire-polyglot-guide.md

Aspire Polyglot AppHost SDK Guide

Based on PR #13978 - Testing conducted on January 21, 2026

This guide documents the requirements and setup instructions for running Aspire AppHosts in Python, Go, Java, and Rust using the new polyglot SDK support.

Table of Contents

• Overview
• Prerequisites
• Python
• Go
• Java
• Rust
• Adding Integrations
• Troubleshooting

---

Overview

Aspire's polyglot support allows you to write AppHosts in languages other than C#. The AppHost communicates with a .NET backend server via JSON-RPC, giving you access to all 40+ Aspire hosting integrations (Redis, PostgreSQL, Azure services, etc.) from any supported language.

How It Works

1. The Aspire CLI scaffolds a language-specific AppHost project
2. A .NET AppHost Server runs in the background, handling orchestration
3. Your guest language code communicates via Unix sockets using JSON-RPC
4. The server manages containers, service discovery, and the Aspire Dashboard

---

Prerequisites

All Languages

1. Aspire CLI (v13.2.0 or later with polyglot support)

   # Install from PR #13978 (for testing)
   curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13978
   
   # Add to PATH
   export PATH="$HOME/.aspire/bin:$PATH"

2. Enable Polyglot Support

   aspire config set features:polyglotSupportEnabled true --global

3. .NET SDK 9.0+ (for the backend server)

   # Verify installation
   dotnet --version

4. Docker (for running containers like Redis, PostgreSQL)

   # Verify Docker is running
   docker info

---

Python

Requirements

Requirement	Version	Notes
Python	3.10+	Detects python3 or python automatically
uv	Latest	Python package manager used by Aspire

Setup

# Install Python (Ubuntu/Debian)
sudo apt-get install python3 python3-pip python3-venv

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Verify installations
python3 --version  # or python --version
uv --version

Create a Python AppHost

# Create project directory
mkdir my-python-app && cd my-python-app

# Initialize Python AppHost
aspire init -l python --non-interactive

# Project structure created:
# ├── .aspire/
# │   └── settings.json
# ├── .modules/          # Generated SDK (created on first run)
# ├── apphost.py
# ├── apphost.run.json
# ├── requirements.txt
# └── uv-install.py

Add Redis Integration

Use the aspire add command to add integrations:

# Add Redis integration
aspire add Aspire.Hosting.Redis --non-interactive

# This updates .aspire/settings.json and regenerates the SDK

Then add the Redis resource to your apphost.py:

# Aspire Python AppHost
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent / ".modules"))

from aspire import create_builder

builder = create_builder()

# Add Redis cache
redis = builder.add_redis("cache")

# Add more resources as needed
# postgres = builder.add_postgres("db")
# container = builder.add_container("myapp", "nginx:latest")

app = builder.build()
app.run()

Run the AppHost

aspire run

Expected output:

🔐 Checking certificates...
⚙  Preparing Aspire server...
Connecting to apphost...
Starting dashboard...

     AppHost:  apphost.py
   Dashboard:  https://localhost:13416/login?t=...
        Logs:  ~/.aspire/cli/logs/apphost-....log

               Press CTRL+C to stop the apphost and exit.

---

Go

Requirements

Requirement	Version	Notes
Go	1.23+	Required for module support

Setup

# Install Go 1.23 (Ubuntu/Debian)
curl -fsSL https://go.dev/dl/go1.23.0.linux-amd64.tar.gz | sudo tar -C /usr/local -xzf -
export PATH="/usr/local/go/bin:$PATH"
export GOPATH="$HOME/go"
export PATH="$GOPATH/bin:$PATH"

# Verify installation
go version

Create a Go AppHost

# Create project directory
mkdir my-go-app && cd my-go-app

# Initialize Go AppHost
aspire init -l go --non-interactive

# Project structure created:
# ├── .aspire/
# │   └── settings.json
# ├── .modules/          # Generated SDK
# ├── apphost.go
# ├── apphost.run.json
# └── go.mod

Add Redis Integration

# Add Redis integration
aspire add Aspire.Hosting.Redis --non-interactive

Then add the Redis resource to your apphost.go:

// Aspire Go AppHost
package main

import (
    "log"
    "apphost/modules/aspire"
)

func main() {
    builder, err := aspire.CreateBuilder(nil)
    if err != nil {
        log.Fatalf("Failed to create builder: %v", err)
    }

    // Add Redis cache (name, port, password)
    // Use 0 for default port, nil for optional parameters
    _, err = builder.AddRedis("cache", 0, nil)
    if err != nil {
        log.Fatalf("Failed to add Redis: %v", err)
    }

    // Add more resources as needed
    // _, _ = builder.AddPostgres("db", 0, nil, nil)
    // _, _ = builder.AddContainer("myapp", "nginx:latest")

    app, err := builder.Build()
    if err != nil {
        log.Fatalf("Failed to build: %v", err)
    }
    
    if err := app.Run(nil); err != nil {
        log.Fatalf("Failed to run: %v", err)
    }
}

Run the AppHost

aspire run

---

Java

Requirements

Requirement	Version	Notes
Java JDK	17+	OpenJDK recommended

Setup

# Install Java (Ubuntu/Debian)
sudo apt-get install openjdk-17-jdk

# Verify installation
java -version
javac -version

Create a Java AppHost

# Create project directory
mkdir my-java-app && cd my-java-app

# Initialize Java AppHost
aspire init -l java --non-interactive

# Project structure created:
# ├── .aspire/
# │   └── settings.json
# ├── .modules/          # Generated SDK
# ├── AppHost.java
# └── apphost.run.json

Add Redis Integration

# Add Redis integration
aspire add Aspire.Hosting.Redis --non-interactive

Then add the Redis resource to your AppHost.java:

// Aspire Java AppHost
package aspire;

public class AppHost {
    public static void main(String[] args) {
        try {
            IDistributedApplicationBuilder builder = Aspire.createBuilder(null);

            // Add Redis cache (name, port, password)
            // Use null for optional parameters
            builder.addRedis("cache", null, null);

            // Add more resources as needed
            // builder.addPostgres("db", null, null, null);
            // builder.addContainer("myapp", "nginx:latest");

            DistributedApplication app = builder.build();
            app.run(null);
        } catch (Exception e) {
            System.err.println("Failed to run: " + e.getMessage());
            e.printStackTrace();
            System.exit(1);
        }
    }
}

Run the AppHost

aspire run

---

Rust

Requirements

Requirement	Version	Notes
Rust	Latest stable	Via rustup
Cargo	Latest	Included with Rust

Setup

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Verify installation
rustc --version
cargo --version

Create a Rust AppHost

# Create project directory
mkdir my-rust-app && cd my-rust-app

# Initialize Rust AppHost
aspire init -l rust --non-interactive

# Project structure created:
# ├── .aspire/
# │   └── settings.json
# ├── .modules/          # Generated SDK
# ├── Cargo.toml
# ├── apphost.rs         # Marker file
# ├── apphost.run.json
# └── src/
#     └── main.rs        # Entry point

Add Redis Integration

# Add Redis integration
aspire add Aspire.Hosting.Redis --non-interactive

Then add the Redis resource to your src/main.rs:

// Aspire Rust AppHost

#[path = "../.modules/mod.rs"]
mod aspire;

use aspire::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let builder = create_builder(None)?;

    // Add Redis cache (name, port, password)
    // Use None for optional parameters
    builder.add_redis("cache", None, None)?;

    // Add more resources as needed
    // builder.add_postgres("db", None, None, None)?;
    // builder.add_container("myapp", "nginx:latest")?;

    let app = builder.build()?;
    app.run(None)?;
    Ok(())
}

Run the AppHost

aspire run

---

Adding Integrations

The recommended way to add Aspire integrations is using the aspire add command:

# Add Redis
aspire add Aspire.Hosting.Redis --non-interactive

# Add PostgreSQL
aspire add Aspire.Hosting.PostgreSQL --non-interactive

# Add RabbitMQ
aspire add Aspire.Hosting.RabbitMQ --non-interactive

# Add Azure Storage (Blobs, Queues, Tables)
aspire add Aspire.Hosting.Azure.Storage --non-interactive

Using Preview Packages

For testing with PR builds:

aspire add Aspire.Hosting.Redis --non-interactive \
  --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json \
  --prerelease

Manual Configuration

Alternatively, edit .aspire/settings.json directly:

{
  "appHostPath": "../apphost.py",
  "language": "python",
  "packages": {
    "Aspire.Hosting.Redis": "9.2.0",
    "Aspire.Hosting.PostgreSQL": "9.2.0"
  }
}

---

Troubleshooting

Common Issues

"Command 'python' not found in PATH"

The Aspire CLI now automatically detects python3 if python is not available. If you still encounter issues:

# Create symlink (optional)
sudo ln -sf /usr/bin/python3 /usr/bin/python

"Failed to install Python dependencies"

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Or link to system path
sudo ln -sf ~/.local/bin/uv /usr/local/bin/uv

"go: download go1.23 for linux/amd64: toolchain not available"

# Install Go 1.23+
curl -fsSL https://go.dev/dl/go1.23.0.linux-amd64.tar.gz | sudo tar -C /usr/local -xzf -
export PATH="/usr/local/go/bin:$PATH"

"Unrecognized app host type"

Ensure your apphost file is named correctly:

• Python: apphost.py
• Go: apphost.go
• Java: AppHost.java
• Rust: apphost.rs (marker) + src/main.rs (entry point)

"GLIBC_2.38 not found"

Use a newer base OS or container image (Ubuntu 24.04+ or .NET SDK 10.0 image).

Debug Mode

Run with debug output to diagnose issues:

aspire run --debug

Check Logs

Logs are stored at:

~/.aspire/cli/logs/apphost-<pid>-<timestamp>.log

---

Test Results Summary

Language	Status	Redis Integration	Notes
Python	✅ Working	✅ Verified	Detects python3 automatically
Go	✅ Working	✅ Verified	Requires Go 1.23+
Java	✅ Working	✅ Verified	Use null for optional params
Rust	✅ Working	✅ Verified	Uses Option<T> for optional params

---

Resources

• Aspire Documentation
• Polyglot AppHost Spec
• PR #13978 - Add common languages SDKs
• Dogfooding Pull Requests

---

Last updated: January 21, 2026