Configuration settings

Aspire configuration is a rooted aspire.config.json file for project-scoped CLI configuration. Use the aspire config command family to inspect and update those settings, and use aspire config list --all to see the feature flags surfaced by your installed CLI.

Configuration file model

Starting in Aspire 13.2, Aspire prefers a rooted aspire.config.json file for project-scoped configuration. The CLI can also read and write user-scoped global defaults.

• Project-scoped configuration

  Project-scoped settings live in a rooted aspire.config.json file. This replaces the older .aspire/settings.json model.

• Global configuration

  User-scoped defaults can be set with aspire config set --global .... Project-scoped settings override global values when both are present. Project-specific values such as appHost.path must be configured locally in aspire.config.json.

The consolidated aspire.config.json file also stores other rooted Aspire configuration, such as the SDK version, launch profiles, and integration packages. The settings table lists the settings you can configure in the file and their default values.

Example aspire.config.json

aspire.config.json

{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  },
  "channel": "staging",
  "features": {
    "defaultWatchEnabled": true,
    "showAllTemplates": true,
    "updateNotificationsEnabled": true
  }
}

The highlighted $schema property is additive

By default, the configuration files do not include the $schema property. You can add it manually to enable editor support for JSON Schema.

JSON Schema support

Aspire publishes a JSON Schema for aspire.config.json so editors can provide completions, validation, and hover documentation while you edit the file.

Two URLs are available:

• The latest URL always points to the newest published schema:

  Latest schema URL

  https://aspire.dev/reference/cli/configuration/schema.json

  schema.json

• A versioned URL pins to a specific Aspire release, such as 13.6.0:

  Versioned schema URL

  https://aspire.dev/reference/cli/configuration/schema/13.6.0.json

  Every stable Aspire release starting with 13.2.0 has a versioned schema, and that schema never changes after the release ships.

Reference the schema from aspire.config.json

Most editors automatically pick up a schema when the JSON file declares a top-level $schema property:

aspire.config.json

{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  }
}

Note

Use a versioned URL, such as .../schema/13.6.0.json, when you want schema behavior to stay stable alongside a pinned Aspire CLI version. Use the unversioned schema.json when you want to always validate against the latest release.

Associate the schema in Visual Studio Code

With the Aspire VS Code extension installed, the schema is registered for aspire.config.json automatically. Without the extension, add a $schema property to the top of aspire.config.json (see above) or map the schema manually in .vscode/settings.json under json.schemas.

Other editors

Any editor or tool that understands JSON Schema draft-07 can consume the hosted schema — including JetBrains IDEs (Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings), Neovim with jsonls, and command-line validators such as ajv or check-jsonschema. Point the tool at either the latest or versioned URL above.

Settings surfaced by aspire config

Use aspire config list to see the values that are currently set, and use aspire config list --all to enumerate the feature flags your installed CLI can configure. The following table lists the settings, their default values, and what they control.

Key	Default	Description
appHost.language	—	Language of the AppHost, such as typescript/nodejs or python. The CLI uses it to choose the runtime that runs the AppHost.
appHost.path	—	Path to the default AppHost entry point, such as apphost.mts, Program.cs, or an AppHost project file, relative to the directory that contains aspire.config.json. Set it in the local aspire.config.json file; the CLI ignores it in global configuration.
certificates.nssDbPaths	—	NSS database paths used for browser certificate trust on Linux. Separate paths with the platform path separator. Prefix a path with firefox= or chromium= to apply the trust settings expected by that browser family. Takes precedence over the upstream DOTNET_DEV_CERTS_NSSDB_PATHS environment variable.
channel	—	Aspire channel used to resolve Aspire packages, such as stable, staging, or daily. aspire new, aspire init, and aspire update can record it, aspire add reads it for non-C# AppHosts, and aspire update uses it when you don’t pass --channel.
docs.api.sitemapUrl	https://aspire.dev/sitemap-0.xml	API reference sitemap used by aspire docs api. Leave it unset to use the built-in aspire.dev source.
docs.llmsTxtUrl	https://aspire.dev/llms-full.txt	llms.txt documentation source used by aspire docs. Leave it unset to use the built-in aspire.dev source.
features.defaultWatchEnabled	false	Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes.
features.experimentalPolyglot:go	false	Enable or disable experimental Go AppHost support.
features.experimentalPolyglot:java	false	Enable or disable experimental Java AppHost support.
features.experimentalPolyglot:python	false	Enable or disable experimental Python AppHost support.
features.experimentalPolyglot:rust	false	Enable or disable experimental Rust AppHost support.
features.nugetSignatureVerificationEnabled	true	Enable or disable defaulting the DOTNET_NUGET_SIGNATURE_VERIFICATION environment variable for NuGet operations. When enabled on Linux, the CLI sets the variable to true unless you’ve set it to false.
features.polyglotIntegrationFilterEnabled	false	Enable or disable an experimental filter that restricts aspire add, aspire integration list, and aspire integration search in non-C# AppHosts to integrations with the polyglot NuGet tag. The filter fails closed, so enabling it against a remote feed hides every integration. Azure DevOps Artifacts feeds ignore tags: query scoping, and nuget.org returns no first-party integrations for the tag. Enable it only against a local package source or hive, where the CLI reads the tag from the package’s .nuspec file.
features.showAllTemplates	false	Show all available templates, including experimental ones, in aspire new and aspire init.
features.showDeprecatedPackages	false	Show or hide deprecated packages in aspire add search results.
features.stagingChannelEnabled	false	Enable or disable access to the staging channel for early access to preview features and packages. When enabled, daily, local, and per-PR CLI builds can also resolve the staging channel.
features.updateNotificationsEnabled	true	Enable or disable Aspire CLI update notifications.
overrideStagingFeed	—	Feed URL for the staging channel. Any non-empty value lets every CLI build resolve the staging channel, and a valid http or https URL replaces the default staging feed. To set it, run aspire config set -g overrideStagingFeed <feed-url>. Without this setting or features.stagingChannelEnabled, --channel staging only resolves on stable or staging Aspire CLI builds. Daily, local, and per-PR builds refuse it and report the recovery options. This key isn’t part of the published JSON Schema, so schema-aware editors flag it as an unknown property.
packages.<packageId>	—	Version of a hosting integration package for a non-C# AppHost, keyed by package ID. A value that ends in .csproj is treated as a project reference. aspire add adds entries, and aspire update updates their versions. For more information, see Add and restore integrations.
profiles.<name>.applicationUrl	—	Application URLs for the launch profile, such as https://localhost:17000;http://localhost:15000. To learn where each kind of AppHost stores launch profiles, see AppHost configuration.
profiles.<name>.environmentVariables	—	Environment variables for the launch profile.
sdk.version	Installed CLI version	Aspire SDK version for a non-C# AppHost, which determines the version of the Aspire.Hosting packages to use. aspire update updates this value.

Each . in a key maps to a nested object in aspire.config.json. For example, aspire config set appHost.path ./apphost.mts writes "appHost": { "path": "./apphost.mts" }. Replace placeholders such as <packageId> and <name> with your own values.

Caution

aspire config set treats every . and : in a key as a nesting separator, so it can’t write keys whose names contain those characters:

• In features.experimentalPolyglot:<language>, experimentalPolyglot:<language> is a single feature name. Without --global, the CLI writes a nested experimentalPolyglot object to the local aspire.config.json file, and later commands fail to load the file. Set these flags with --global, or add them to the local file by hand, for example "experimentalPolyglot:go": true in the features object.
• Package IDs such as Aspire.Hosting.Redis contain dots. Use aspire add to add packages, or edit the packages object by hand.

Configure the AppHost path

Use appHost.path to set the default AppHost entry point for the current configuration root:

Set the local AppHost path

aspire config set appHost.path ./apphost.mts

The CLI writes this value to the local aspire.config.json file:

aspire.config.json

{
  "appHost": {
    "path": "./apphost.mts"
  }
}

The AppHost path can point to the entry point used by your AppHost language, such as apphost.mts, Program.cs, or an AppHost project file. The path is project-specific and can’t be configured globally. If a global settings file contains appHost.path or the legacy appHostPath key, the CLI ignores that value and warns that AppHost paths must be configured locally. The legacy appHostPath key is also blocked by aspire config set; use appHost.path instead.

Configure browser certificate trust on Linux

On Linux, the NSS databases used to trust the Aspire HTTPS development certificate can be configured through certificates.nssDbPaths, including user-level configuration:

Set the NSS database paths globally

aspire config set --global certificates.nssDbPaths "firefox=/path/to/firefox/profile:chromium=/path/to/chromium/nssdb"

Prefix a path with firefox= or chromium= to apply the trust settings expected by that browser family, and separate multiple paths with the platform path separator.

If certificates.nssDbPaths is unset, aspire certs trust will also honor the DOTNET_DEV_CERTS_NSSDB_PATHS environment variable, but Aspire configuration will take precedence when present. When no specific configuration is supplied, Aspire applies certificate trust to NSS databases in well-known browser specific paths for Firefox and Chrome/Chromium. Run aspire certs trust to apply the configured trust settings.

Toggle preview feature experiences

Use feature flags to opt in to preview experiences that your installed Aspire CLI supports.

Tip

The available feature flags depend on your installed CLI version. Treat the output of aspire config list --all as the authoritative list of feature flags and their default values.

1. Run aspire config list --all to discover available features.* keys.

2. Enable a feature flag for the current project with aspire config set:

   Enable a project-scoped preview feature

   aspire config set features.<featureKey> true

3. Use --global (or -g) when you want the feature enabled by default across projects. Copy the key name exactly from aspire config list --all because some language-specific flags use a :<language> suffix:

   Enable a user-scoped preview feature default

   aspire config set features.<featureKey> true --global

   For example, consider the following that enables global support for Go:

   Enable global Go support

   aspire config set features.experimentalPolyglot:go true --global

   Always set experimentalPolyglot:<language> flags with --global, or add them to the local aspire.config.json file by hand. For details, see the caution under Settings surfaced by aspire config.

4. Turn a feature off by setting it to false, or remove the override with aspire config delete <key>.

Working with configuration

• Use aspire config list to show currently set project-scoped and global values.

• Use aspire config list --all to include the feature flags that your installed CLI can configure.

• Use aspire config get <key> to inspect a specific setting such as channel or appHost.path.

• Use aspire config set <key> <value> to update a setting, and aspire config set --global ... when you want a user-scoped default.

CLI commands

Command	Status	Function
aspire config	Stable	Command driver for managing Aspire configuration.
aspire config list	Stable	List currently configured values, or all available feature flags with --all.
aspire config get <key>	Stable	Get a configuration value.
aspire config set <key> <value>	Stable	Set a configuration value.
aspire config delete <key>	Stable	Delete a configuration value.

For command-level details, see the aspire config command reference.