diff --git a/crates/aqua-registry/src/lib.rs b/crates/aqua-registry/src/lib.rs
index e38e064f07..79ada578d5 100644
--- a/crates/aqua-registry/src/lib.rs
+++ b/crates/aqua-registry/src/lib.rs
@@ -13,7 +13,8 @@ pub use registry::{
     NoOpCacheStore, package_ids,
 };
 pub use types::{
-    AquaChecksum, AquaChecksumType, AquaMinisignType, AquaPackage, AquaPackageType, RegistryYaml,
+    AquaChecksum, AquaChecksumType, AquaMinisignType, AquaPackage, AquaPackageType, AquaVar,
+    RegistryYaml,
 };
 
 use thiserror::Error;
diff --git a/crates/aqua-registry/src/template.rs b/crates/aqua-registry/src/template.rs
index 40417aec54..8f6b1abb6d 100644
--- a/crates/aqua-registry/src/template.rs
+++ b/crates/aqua-registry/src/template.rs
@@ -144,26 +144,22 @@ fn lex(code: &str) -> Result<Vec<Token<'_>>> {
                 }
             }
         } else if code.starts_with(".") {
-            // Check if this is a property access (after ) or identifier)
-            let next_char = code.chars().nth(1);
-            if next_char.is_some_and(|c| c.is_alphabetic()) {
-                // This could be .Key or .Property
-                let end = code[1..]
-                    .chars()
-                    .enumerate()
-                    .find(|(_, c)| !c.is_alphanumeric() && *c != '_')
-                    .map(|(i, _)| i + 1)
-                    .unwrap_or(code.len());
-
-                // If preceded by RParen, it's a property access
+            if let Some(first_end) = dotted_identifier_end(code) {
+                // This could be .Key or .Property, and can also include chained fields
+                // like .Vars.channel.
                 if tokens.last().is_some_and(|t| t.is_r_paren()) {
                     tokens.push(Token::Dot);
-                    tokens.push(Token::Ident(&code[1..end]));
+                    tokens.push(Token::Ident(&code[1..first_end]));
                 } else {
-                    // Otherwise it's a key reference
-                    tokens.push(Token::Key(&code[1..end]));
+                    tokens.push(Token::Key(&code[1..first_end]));
+                }
+                code = &code[first_end..];
+
+                while let Some(end) = dotted_identifier_end(code) {
+                    tokens.push(Token::Dot);
+                    tokens.push(Token::Ident(&code[1..end]));
+                    code = &code[end..];
                 }
-                code = &code[end..];
             } else {
                 tokens.push(Token::Dot);
                 code = &code[1..];
@@ -190,6 +186,22 @@ fn lex(code: &str) -> Result<Vec<Token<'_>>> {
     Ok(tokens)
 }
 
+fn dotted_identifier_end(code: &str) -> Option<usize> {
+    let rest = code.strip_prefix('.')?;
+    let first = rest.chars().next()?;
+    if !first.is_alphabetic() {
+        return None;
+    }
+    Some(1 + identifier_len(rest))
+}
+
+fn identifier_len(code: &str) -> usize {
+    code.char_indices()
+        .find(|(_, c)| !c.is_alphanumeric() && *c != '_')
+        .map(|(i, _)| i)
+        .unwrap_or(code.len())
+}
+
 /// Parse tokens into an AST
 fn parse_tokens(tokens: &[Token]) -> Result<Expr> {
     let mut tokens = tokens.iter().peekable();
@@ -220,7 +232,7 @@ fn parse_primary(tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>) -> R
 
     let token = tokens.next().wrap_err("unexpected end of expression")?;
 
-    let mut expr = match token {
+    let expr = match token {
         Token::Key(k) => Expr::Var(k.to_string()),
         Token::String(s) => Expr::Literal(s.to_string()),
         Token::LParen => {
@@ -256,19 +268,7 @@ fn parse_primary(tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>) -> R
         _ => bail!("unexpected token: {token:?}"),
     };
 
-    // Handle property access: expr.Property
-    while matches!(tokens.peek(), Some(Token::Dot)) {
-        tokens.next(); // consume dot
-        skip_whitespace(tokens);
-
-        if let Some(Token::Ident(prop)) = tokens.next() {
-            expr = Expr::PropertyAccess(Box::new(expr), prop.to_string());
-        } else {
-            bail!("expected identifier after dot");
-        }
-    }
-
-    Ok(expr)
+    parse_property_chain(tokens, expr)
 }
 
 /// Parse a function argument
@@ -284,23 +284,11 @@ fn parse_arg(tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>) -> Resul
             if !matches!(tokens.next(), Some(Token::RParen)) {
                 bail!("expected closing parenthesis");
             }
-
-            // Check for property access after paren
-            let mut result = expr;
-            while matches!(tokens.peek(), Some(Token::Dot)) {
-                tokens.next(); // consume dot
-                skip_whitespace(tokens);
-                if let Some(Token::Ident(prop)) = tokens.next() {
-                    result = Expr::PropertyAccess(Box::new(result), prop.to_string());
-                } else {
-                    bail!("expected identifier after dot");
-                }
-            }
-            Ok(result)
+            parse_property_chain(tokens, expr)
         }
         Some(Token::Key(k)) => {
             tokens.next();
-            Ok(Expr::Var(k.to_string()))
+            parse_property_chain(tokens, Expr::Var(k.to_string()))
         }
         Some(Token::String(s)) => {
             tokens.next();
@@ -310,6 +298,24 @@ fn parse_arg(tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>) -> Resul
     }
 }
 
+fn parse_property_chain(
+    tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>,
+    mut expr: Expr,
+) -> Result<Expr> {
+    while matches!(tokens.peek(), Some(Token::Dot)) {
+        tokens.next(); // consume dot
+        skip_whitespace(tokens);
+
+        if let Some(Token::Ident(prop)) = tokens.next() {
+            expr = Expr::PropertyAccess(Box::new(expr), prop.to_string());
+        } else {
+            bail!("expected identifier after dot");
+        }
+    }
+
+    Ok(expr)
+}
+
 fn skip_whitespace(tokens: &mut std::iter::Peekable<std::slice::Iter<Token>>) {
     while matches!(tokens.peek(), Some(Token::Whitespace(_))) {
         tokens.next();
@@ -442,6 +448,12 @@ impl<'a> Evaluator<'a> {
 
     /// Evaluate property access
     fn eval_property(&self, expr: &Expr, prop: &str) -> Result<Box<dyn Value>> {
+        if let Expr::Var(name) = expr {
+            let key = format!("{name}.{prop}");
+            if let Some(value) = self.ctx.get(&key) {
+                return Ok(Box::new(StringValue(value.clone())) as Box<dyn Value>);
+            }
+        }
         let value = self.eval_value(expr)?;
         let prop_value = value.get_property(prop)?;
         Ok(Box::new(StringValue(prop_value)) as Box<dyn Value>)
@@ -683,4 +695,18 @@ mod tests {
         let ctx = hashmap(vec![("AssetWithoutExt", "gradle-8.14.3-bin")]);
         assert_eq!(render(tmpl, &ctx).unwrap(), "gradle-8.14.3/bin/gradle");
     }
+
+    #[test]
+    fn test_render_vars_property_access() {
+        let tmpl = "{{.Vars.channel}}";
+        let ctx = hashmap(vec![("Vars.channel", "stable")]);
+        assert_eq!(render(tmpl, &ctx).unwrap(), "stable");
+    }
+
+    #[test]
+    fn test_render_vars_property_in_function_arg() {
+        let tmpl = "{{title .Vars.channel}}";
+        let ctx = hashmap(vec![("Vars.channel", "stable")]);
+        assert_eq!(render(tmpl, &ctx).unwrap(), "Stable");
+    }
 }
diff --git a/crates/aqua-registry/src/types.rs b/crates/aqua-registry/src/types.rs
index d38d63508b..f7d4da76c9 100644
--- a/crates/aqua-registry/src/types.rs
+++ b/crates/aqua-registry/src/types.rs
@@ -38,6 +38,7 @@ pub struct AquaPackage {
     pub complete_windows_ext: bool,
     pub supported_envs: Vec<String>,
     pub files: Vec<AquaFile>,
+    pub vars: Vec<AquaVar>,
     pub replacements: HashMap<String, String>,
     pub version_prefix: Option<String>,
     version_filter: Option<String>,
@@ -54,6 +55,8 @@ pub struct AquaPackage {
     pub no_asset: bool,
     pub error_message: Option<String>,
     pub path: Option<String>,
+    #[serde(skip)]
+    var_values: HashMap<String, String>,
 }
 
 /// Override configuration for specific OS/architecture combinations
@@ -65,6 +68,15 @@ struct AquaOverride {
     goarch: Option<String>,
 }
 
+/// Variable definition for Aqua templates
+#[derive(Debug, Deserialize, Clone, Default)]
+pub struct AquaVar {
+    pub name: String,
+    pub default: Option<serde_yaml::Value>,
+    #[serde(default)]
+    pub required: bool,
+}
+
 /// File definition within a package
 #[derive(Debug, Deserialize, Clone)]
 pub struct AquaFile {
@@ -195,6 +207,7 @@ impl Default for AquaPackage {
             complete_windows_ext: true,
             supported_envs: Vec::new(),
             files: Vec::new(),
+            vars: Vec::new(),
             replacements: HashMap::new(),
             version_prefix: None,
             version_filter: None,
@@ -210,6 +223,7 @@ impl Default for AquaPackage {
             no_asset: false,
             error_message: None,
             path: None,
+            var_values: HashMap::new(),
         }
     }
 }
@@ -234,6 +248,13 @@ impl AquaPackage {
         self
     }
 
+    /// Apply user-provided variable values used by aqua `vars` templates.
+    pub fn with_var_values(mut self, var_values: HashMap<String, String>) -> Result<AquaPackage> {
+        self.var_values = var_values;
+        self.validate_vars()?;
+        Ok(self)
+    }
+
     fn version_override(&self, versions: &[&str]) -> &AquaPackage {
         let expressions = versions
             .iter()
@@ -401,11 +422,45 @@ impl AquaPackage {
         ctx.insert("GOARCH".to_string(), replace(actual_arch));
         ctx.insert("Arch".to_string(), replace(actual_arch));
         ctx.insert("Format".to_string(), replace(&self.format));
+        ctx.extend(self.vars_ctx()?);
         ctx.extend(overrides.clone());
 
         crate::template::render(s, &ctx)
     }
 
+    fn vars_ctx(&self) -> Result<HashMap<String, String>> {
+        self.validate_vars()?;
+        let mut ctx = HashMap::new();
+        for var in &self.vars {
+            if let Some(value) = self.var_value(var)? {
+                ctx.insert(format!("Vars.{}", var.name), value);
+            }
+        }
+        Ok(ctx)
+    }
+
+    fn validate_vars(&self) -> Result<()> {
+        for var in &self.vars {
+            if var.name.is_empty() {
+                return Err(eyre!("aqua var name is empty"));
+            }
+            if var.required && self.var_value(var)?.is_none() {
+                return Err(eyre!("required aqua var not set: {}", var.name));
+            }
+        }
+        Ok(())
+    }
+
+    fn var_value(&self, var: &AquaVar) -> Result<Option<String>> {
+        if let Some(value) = self.var_values.get(&var.name) {
+            return Ok(Some(value.clone()));
+        }
+        var.default
+            .as_ref()
+            .map(|value| yaml_var_to_string(&var.name, value))
+            .transpose()
+    }
+
     /// Set up version filter expression if configured
     pub fn setup_version_filter(&mut self) -> Result<()> {
         if let Some(version_filter) = &self.version_filter {
@@ -473,6 +528,31 @@ impl AquaPackage {
     }
 }
 
+fn yaml_var_to_string(name: &str, value: &serde_yaml::Value) -> Result<String> {
+    match value {
+        serde_yaml::Value::String(s) => Ok(s.clone()),
+        serde_yaml::Value::Null => Ok(String::new()),
+        serde_yaml::Value::Tagged(tagged) => yaml_var_to_string(name, &tagged.value),
+        value => Err(eyre!(
+            "aqua var `{}` must be a string, got {}",
+            name,
+            yaml_value_kind(value)
+        )),
+    }
+}
+
+fn yaml_value_kind(value: &serde_yaml::Value) -> &'static str {
+    match value {
+        serde_yaml::Value::String(_) => "string",
+        serde_yaml::Value::Number(_) => "number",
+        serde_yaml::Value::Bool(_) => "boolean",
+        serde_yaml::Value::Sequence(_) => "array",
+        serde_yaml::Value::Mapping(_) => "object",
+        serde_yaml::Value::Null => "null",
+        serde_yaml::Value::Tagged(tagged) => yaml_value_kind(&tagged.value),
+    }
+}
+
 /// splits a version number into an optional prefix and the remaining version string
 fn split_version_prefix(version: &str) -> (String, String) {
     version
@@ -561,6 +641,9 @@ fn apply_override(mut orig: AquaPackage, avo: &AquaPackage) -> AquaPackage {
     if !avo.files.is_empty() {
         orig.files = avo.files.clone();
     }
+    if !avo.vars.is_empty() {
+        orig.vars = avo.vars.clone();
+    }
     orig.replacements.extend(avo.replacements.clone());
     if let Some(avo_version_prefix) = avo.version_prefix.clone() {
         orig.version_prefix = Some(avo_version_prefix);
@@ -904,6 +987,10 @@ impl AquaGithubArtifactAttestations {
 mod tests {
     use super::*;
 
+    fn default_str(value: &str) -> Option<serde_yaml::Value> {
+        Some(serde_yaml::Value::String(value.to_string()))
+    }
+
     #[test]
     fn test_aqua_file_src_gradle() {
         // Test the gradle package src template: {{.AssetWithoutExt | trimSuffix "-bin"}}/bin/gradle
@@ -1030,4 +1117,145 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn test_vars_default_value() {
+        let pkg = AquaPackage {
+            asset: "tool-{{.Vars.channel}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "channel".to_string(),
+                default: default_str("stable"),
+                required: false,
+            }],
+            ..Default::default()
+        };
+        let asset = pkg.asset("1.0.0", "linux", "amd64").unwrap();
+        assert_eq!(asset, "tool-stable-1.0.0.tar.gz");
+    }
+
+    #[test]
+    fn test_vars_override_value() {
+        let mut var_values = HashMap::new();
+        var_values.insert("channel".to_string(), "beta".to_string());
+        let pkg = AquaPackage {
+            asset: "tool-{{.Vars.channel}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "channel".to_string(),
+                default: default_str("stable"),
+                required: false,
+            }],
+            ..Default::default()
+        }
+        .with_var_values(var_values)
+        .unwrap();
+        let asset = pkg.asset("1.0.0", "linux", "amd64").unwrap();
+        assert_eq!(asset, "tool-beta-1.0.0.tar.gz");
+    }
+
+    #[test]
+    fn test_vars_default_scalar_value() {
+        let pkg = AquaPackage {
+            asset: "tool-go{{.Vars.go_version}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "go_version".to_string(),
+                default: Some(serde_yaml::from_str(r#""1.24""#).unwrap()),
+                required: false,
+            }],
+            ..Default::default()
+        };
+        let asset = pkg.asset("1.0.0", "linux", "amd64").unwrap();
+        assert_eq!(asset, "tool-go1.24-1.0.0.tar.gz");
+    }
+
+    #[test]
+    fn test_vars_default_array_errors() {
+        let pkg = AquaPackage {
+            asset: "tool-{{.Vars.channels}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "channels".to_string(),
+                default: Some(serde_yaml::from_str("[stable, beta]").unwrap()),
+                required: true,
+            }],
+            ..Default::default()
+        };
+        let err = pkg.asset("1.0.0", "linux", "amd64").unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("aqua var `channels` must be a string, got array"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_vars_default_object_errors() {
+        let pkg = AquaPackage {
+            asset: "tool-{{.Vars.config}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "config".to_string(),
+                default: Some(serde_yaml::from_str("{channel: stable, flavor: beta}").unwrap()),
+                required: true,
+            }],
+            ..Default::default()
+        };
+        let err = pkg.asset("1.0.0", "linux", "amd64").unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("aqua var `config` must be a string, got object"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_vars_required_missing() {
+        let pkg = AquaPackage {
+            asset: "tool-{{.Vars.channel}}-{{.Version}}.tar.gz".to_string(),
+            vars: vec![AquaVar {
+                name: "channel".to_string(),
+                default: None,
+                required: true,
+            }],
+            ..Default::default()
+        };
+        let err = pkg.asset("1.0.0", "linux", "amd64").unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("required aqua var not set: channel"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_vars_required_missing_with_var_values() {
+        let pkg = AquaPackage {
+            vars: vec![AquaVar {
+                name: "go_version".to_string(),
+                default: None,
+                required: true,
+            }],
+            ..Default::default()
+        };
+        let err = pkg.with_var_values(HashMap::new()).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("required aqua var not set: go_version"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_vars_empty_name() {
+        let pkg = AquaPackage {
+            vars: vec![AquaVar {
+                name: String::new(),
+                default: None,
+                required: false,
+            }],
+            ..Default::default()
+        };
+        let err = pkg.asset("1.0.0", "linux", "amd64").unwrap_err();
+        assert!(
+            err.to_string().contains("aqua var name is empty"),
+            "unexpected error: {err}"
+        );
+    }
 }
diff --git a/docs/dev-tools/backends/aqua.md b/docs/dev-tools/backends/aqua.md
index 540bf51a52..6f0633a028 100644
--- a/docs/dev-tools/backends/aqua.md
+++ b/docs/dev-tools/backends/aqua.md
@@ -64,6 +64,20 @@ When enabled:
 - A `.mise-bins` subdirectory is created with symlinks to the exposed binaries
 - Bundled dependencies and other extra executables, such as Python in `aws-cli`, are not added to PATH
 
+### `vars`
+
+Some aqua registry entries define template variables (for example <span v-pre>`{{.Vars.channel}}`</span>).
+Set them via tool options using either top-level keys or a nested `vars` table:
+
+```toml
+[tools]
+"aqua:flutter/flutter" = { version = "3.32.8", channel = "stable" }
+"aqua:scenarigo/scenarigo" = { version = "0.21.0", vars = { go_version = "1.24" } }
+```
+
+Vars with defaults are filled automatically. Vars marked as required in the aqua registry must be set
+unless the registry also provides a default.
+
 ## Settings
 
 <script setup>
diff --git a/e2e/backend/test_aqua_vars b/e2e/backend/test_aqua_vars
new file mode 100644
index 0000000000..7681937507
--- /dev/null
+++ b/e2e/backend/test_aqua_vars
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+export MISE_EXPERIMENTAL=1
+export MISE_LOCKFILE=1
+export MISE_AQUA_BAKED_REGISTRY=0
+
+detect_platform
+
+REGISTRY_DIR="$PWD/aqua-registry-local"
+mkdir -p "$REGISTRY_DIR/pkgs/example/vars-tool"
+
+cat <<'EOF_REGISTRY' >"$REGISTRY_DIR/pkgs/example/vars-tool/registry.yaml"
+packages:
+  - type: http
+    supported_envs:
+      - darwin
+      - linux
+      - windows
+    url: https://mise.jdx.dev/test-fixtures/hello-world-{{.Vars.fixture_version}}.tar.gz
+    files:
+      - name: hello-world
+        src: hello-world-{{.Vars.fixture_version}}/bin/hello-world
+    vars:
+      - name: fixture_version
+        required: true
+EOF_REGISTRY
+
+(
+	cd "$REGISTRY_DIR"
+	git init -q
+	git add pkgs/example/vars-tool/registry.yaml
+	git commit -qm "init local aqua registry"
+)
+
+export MISE_AQUA_REGISTRY_URL="file://$REGISTRY_DIR"
+
+cat <<'EOF_MISE' >mise.toml
+[tools]
+"aqua:example/vars-tool" = { version = "1.0.0", fixture_version = "1.0.0" }
+EOF_MISE
+
+mise install
+assert_contains "mise x -- hello-world" "hello world"
+
+cat <<'EOF_MISE' >mise.toml
+[tools]
+"aqua:example/vars-tool" = { version = "1.0.0", fixture_version = "2.0.0" }
+EOF_MISE
+
+mise install --force aqua:example/vars-tool@1.0.0
+assert_contains "mise x -- hello-world" "hello world 2.0.0"
+
+rm -f mise.lock
+cat <<'EOF_MISE' >mise.toml
+[tools]
+"aqua:example/vars-tool" = { version = "1.0.0", vars = { fixture_version = "2.0.0" } }
+EOF_MISE
+
+mise lock --platform "$MISE_PLATFORM"
+assert_contains "cat mise.lock" '"vars.fixture_version" = "2.0.0"'
+assert_contains "cat mise.lock" 'url = "https://mise.jdx.dev/test-fixtures/hello-world-2.0.0.tar.gz"'
+cp mise.lock nested-vars.lock
+
+cat <<'EOF_MISE' >mise.toml
+[tools]
+"aqua:example/vars-tool" = { version = "1.0.0", fixture_version = "2.0.0" }
+EOF_MISE
+
+mise lock --platform "$MISE_PLATFORM"
+assert_succeed "cmp mise.lock nested-vars.lock"
+
+cat <<'EOF_MISE' >mise.toml
+[tools]
+"aqua:example/vars-tool" = { version = "1.0.0", vars = { fixture_version = ["2.0.0"] } }
+EOF_MISE
+
+# shellcheck disable=SC2016
+assert_fail "mise install --force aqua:example/vars-tool@1.0.0" 'aqua var `vars.fixture_version` must be a string, got array'
diff --git a/src/backend/aqua.rs b/src/backend/aqua.rs
index 2a8258c0d5..0c5ff84a59 100644
--- a/src/backend/aqua.rs
+++ b/src/backend/aqua.rs
@@ -13,7 +13,7 @@ use crate::lockfile::{PlatformInfo, ProvenanceType};
 use crate::path::{Path, PathBuf, PathExt};
 use crate::plugins::VERSION_REGEX;
 use crate::registry::REGISTRY;
-use crate::toolset::ToolVersion;
+use crate::toolset::{EPHEMERAL_OPT_KEYS, ToolRequest, ToolVersion, ToolVersionOptions};
 use crate::ui::progress_report::SingleReport;
 use crate::{
     aqua::aqua_registry_wrapper::{
@@ -31,7 +31,10 @@ use itertools::Itertools;
 use regex::Regex;
 use std::borrow::Cow;
 use std::fmt::Debug;
-use std::{collections::HashSet, sync::Arc};
+use std::{
+    collections::{BTreeMap, HashMap, HashSet},
+    sync::Arc,
+};
 
 #[derive(Debug)]
 pub struct AquaBackend {
@@ -55,10 +58,7 @@ impl Backend for AquaBackend {
     }
 
     async fn install_operation_count(&self, tv: &ToolVersion, _ctx: &InstallContext) -> usize {
-        let pkg = match AQUA_REGISTRY
-            .package_with_version(&self.id, &[&tv.version])
-            .await
-        {
+        let pkg = match self.package_with_options(tv, &[&tv.version]).await {
             Ok(pkg) => pkg,
             Err(_) => return 3, // fallback to default
         };
@@ -320,9 +320,7 @@ impl Backend for AquaBackend {
             Some(v_prefixed) => vec![v.as_str(), v_prefixed.as_str()],
             None => vec![v.as_str()],
         };
-        let pkg = AQUA_REGISTRY
-            .package_with_version(&self.id, &versions)
-            .await?;
+        let pkg = self.package_with_options(&tv, &versions).await?;
         if let Some(prefix) = &pkg.version_prefix
             && !v.starts_with(prefix)
         {
@@ -495,10 +493,13 @@ impl Backend for AquaBackend {
             });
         }
 
+        let request_options = tv.request.options();
+        let cache_key = Self::lockfile_options(&request_options);
         let cache: CacheManager<Vec<PathBuf>> =
             CacheManagerBuilder::new(tv.cache_path().join("bin_paths.msgpack.z"))
                 .with_fresh_file(install_path.clone())
                 .with_fresh_duration(Settings::get().fetch_remote_versions_cache())
+                .with_cache_key(format!("{cache_key:?}"))
                 .build();
 
         let paths = cache
@@ -506,6 +507,7 @@ impl Backend for AquaBackend {
                 let pkg = AQUA_REGISTRY
                     .package_with_version(&self.id, &[&tv.version])
                     .await?;
+                let pkg = Self::apply_var_options(pkg, &request_options)?;
 
                 let srcs = self.srcs(&pkg, tv)?;
                 let paths = if srcs.is_empty() {
@@ -529,6 +531,14 @@ impl Backend for AquaBackend {
         Ok(paths)
     }
 
+    fn resolve_lockfile_options(
+        &self,
+        request: &ToolRequest,
+        _target: &PlatformTarget,
+    ) -> BTreeMap<String, String> {
+        Self::lockfile_options(&request.options())
+    }
+
     fn fuzzy_match_filter(&self, versions: Vec<String>, query: &str) -> Vec<String> {
         let escaped_query = regex::escape(query);
         let query = if query == "latest" {
@@ -600,7 +610,9 @@ impl Backend for AquaBackend {
         // Using package_with_version() here would apply overrides for the current host
         // platform first, which can leak host-specific overrides into cross-platform lock.
         let pkg = AQUA_REGISTRY.package(&self.id).await?;
-        let pkg = pkg.with_version(&versions, target_os, target_arch);
+        let opts = tv.request.options();
+        let pkg =
+            Self::apply_var_options(pkg.with_version(&versions, target_os, target_arch), &opts)?;
 
         // Apply version prefix if present
         if let Some(prefix) = &pkg.version_prefix
@@ -742,6 +754,60 @@ impl Backend for AquaBackend {
 }
 
 impl AquaBackend {
+    async fn package_with_options(
+        &self,
+        tv: &ToolVersion,
+        versions: &[&str],
+    ) -> Result<AquaPackage> {
+        let pkg = AQUA_REGISTRY
+            .package_with_version(&self.id, versions)
+            .await?;
+        Self::apply_var_options(pkg, &tv.request.options())
+    }
+
+    fn apply_var_options(pkg: AquaPackage, opts: &ToolVersionOptions) -> Result<AquaPackage> {
+        if pkg.vars.is_empty() {
+            return Ok(pkg);
+        }
+        let mut var_values = HashMap::new();
+        for var in &pkg.vars {
+            if let Some(value) = aqua_var_option(opts, &var.name)? {
+                var_values.insert(var.name.clone(), value);
+            }
+        }
+        pkg.with_var_values(var_values)
+    }
+
+    fn lockfile_options(opts: &ToolVersionOptions) -> BTreeMap<String, String> {
+        let mut result = BTreeMap::new();
+        for (key, value) in opts.iter() {
+            if key == "symlink_bins" || EPHEMERAL_OPT_KEYS.contains(&key.as_str()) {
+                continue;
+            }
+            if key == "vars" {
+                if let toml::Value::Table(table) = value {
+                    Self::insert_vars_lockfile_options(&mut result, table);
+                }
+            } else if let Some(value) = toml_value_to_string(value) {
+                let key = if key.starts_with("vars.") {
+                    key.clone()
+                } else {
+                    format!("vars.{key}")
+                };
+                result.entry(key).or_insert(value);
+            }
+        }
+        result
+    }
+
+    fn insert_vars_lockfile_options(result: &mut BTreeMap<String, String>, table: &toml::Table) {
+        for (key, value) in table {
+            if let Some(value) = toml_value_to_string(value) {
+                result.insert(format!("vars.{key}"), value);
+            }
+        }
+    }
+
     /// Detect provenance type from aqua registry package config.
     ///
     /// Returns the highest-priority provenance type that is configured and
@@ -1941,6 +2007,216 @@ impl AquaBackend {
     }
 }
 
+fn toml_value_to_string(value: &toml::Value) -> Option<String> {
+    match value {
+        toml::Value::String(s) => Some(s.clone()),
+        _ => None,
+    }
+}
+
+fn aqua_var_option(opts: &ToolVersionOptions, name: &str) -> Result<Option<String>> {
+    if let Some(toml::Value::Table(vars)) = opts.opts.get("vars")
+        && let Some(value) = vars.get(name)
+    {
+        return toml_string_var(&format!("vars.{name}"), value).map(Some);
+    }
+    opts.opts
+        .get(name)
+        .map(|value| toml_string_var(name, value).map(Some))
+        .unwrap_or(Ok(None))
+}
+
+fn toml_string_var(key: &str, value: &toml::Value) -> Result<String> {
+    match value {
+        toml::Value::String(s) => Ok(s.clone()),
+        value => bail!(
+            "aqua var `{}` must be a string, got {}",
+            key,
+            toml_value_kind(value)
+        ),
+    }
+}
+
+fn toml_value_kind(value: &toml::Value) -> &'static str {
+    match value {
+        toml::Value::String(_) => "string",
+        toml::Value::Integer(_) | toml::Value::Float(_) => "number",
+        toml::Value::Boolean(_) => "boolean",
+        toml::Value::Array(_) => "array",
+        toml::Value::Table(_) => "object",
+        toml::Value::Datetime(_) => "datetime",
+    }
+}
+
+/// Returns install-time-only option keys for the Aqua backend.
+///
+/// Aqua registry vars may be provided either as a nested `vars` table or as
+/// flat top-level keys whose names are declared by the registry package. The
+/// flat names are not statically knowable here, so `is_install_time_option_key`
+/// handles the precise filtering rule.
+pub fn install_time_option_keys() -> Vec<String> {
+    vec!["vars".into()]
+}
+
+pub fn is_install_time_option_key(key: &str) -> bool {
+    key != "symlink_bins"
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use aqua_registry::AquaVar;
+
+    fn aqua_var(name: &str, required: bool) -> AquaVar {
+        AquaVar {
+            name: name.to_string(),
+            default: None,
+            required,
+        }
+    }
+
+    #[test]
+    fn test_apply_var_options_prefers_nested_vars() {
+        let mut pkg = AquaPackage::default();
+        pkg.asset = "tool-{{.Vars.channel}}-{{.Version}}.tar.gz".to_string();
+        pkg.vars = vec![aqua_var("channel", true)];
+        let mut opts = ToolVersionOptions::default();
+        opts.opts.insert(
+            "channel".to_string(),
+            toml::Value::String("stable".to_string()),
+        );
+        let mut vars = toml::Table::new();
+        vars.insert(
+            "channel".to_string(),
+            toml::Value::String("beta".to_string()),
+        );
+        opts.opts
+            .insert("vars".to_string(), toml::Value::Table(vars));
+
+        let pkg = AquaBackend::apply_var_options(pkg, &opts).unwrap();
+
+        assert_eq!(
+            pkg.asset("1.0.0", "linux", "amd64").unwrap(),
+            "tool-beta-1.0.0.tar.gz"
+        );
+    }
+
+    #[test]
+    fn test_apply_var_options_errors_for_array_vars() {
+        let mut pkg = AquaPackage::default();
+        pkg.vars = vec![aqua_var("channels", true)];
+        let mut opts = ToolVersionOptions::default();
+        let mut vars = toml::Table::new();
+        vars.insert(
+            "channels".to_string(),
+            toml::Value::Array(vec![toml::Value::String("stable".to_string())]),
+        );
+        opts.opts
+            .insert("vars".to_string(), toml::Value::Table(vars));
+
+        let err = AquaBackend::apply_var_options(pkg, &opts).unwrap_err();
+
+        assert!(
+            err.to_string()
+                .contains("aqua var `vars.channels` must be a string, got array"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_apply_var_options_errors_for_missing_required_var() {
+        let mut pkg = AquaPackage::default();
+        pkg.vars = vec![aqua_var("go_version", true)];
+        let err = AquaBackend::apply_var_options(pkg, &ToolVersionOptions::default()).unwrap_err();
+
+        assert!(
+            err.to_string()
+                .contains("required aqua var not set: go_version"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_lockfile_options_include_aqua_vars() {
+        let mut opts = ToolVersionOptions::default();
+        opts.opts.insert(
+            "channel".to_string(),
+            toml::Value::String("stable".to_string()),
+        );
+        opts.opts.insert(
+            "symlink_bins".to_string(),
+            toml::Value::String("true".to_string()),
+        );
+        opts.opts.insert(
+            "postinstall".to_string(),
+            toml::Value::String("echo ok".to_string()),
+        );
+        let mut vars = toml::Table::new();
+        vars.insert("go_version".to_string(), toml::Value::String("1.24".into()));
+        opts.opts
+            .insert("vars".to_string(), toml::Value::Table(vars));
+
+        let lock_opts = AquaBackend::lockfile_options(&opts);
+
+        assert_eq!(lock_opts.get("vars.channel"), Some(&"stable".to_string()));
+        assert_eq!(lock_opts.get("vars.go_version"), Some(&"1.24".to_string()));
+        assert!(!lock_opts.contains_key("symlink_bins"));
+        assert!(!lock_opts.contains_key("postinstall"));
+    }
+
+    #[test]
+    fn test_lockfile_options_canonicalize_equivalent_aqua_vars() {
+        let mut top_level = ToolVersionOptions::default();
+        top_level.opts.insert(
+            "channel".to_string(),
+            toml::Value::String("stable".to_string()),
+        );
+
+        let mut nested = ToolVersionOptions::default();
+        let mut vars = toml::Table::new();
+        vars.insert(
+            "channel".to_string(),
+            toml::Value::String("stable".to_string()),
+        );
+        nested
+            .opts
+            .insert("vars".to_string(), toml::Value::Table(vars));
+
+        assert_eq!(
+            AquaBackend::lockfile_options(&top_level),
+            AquaBackend::lockfile_options(&nested)
+        );
+    }
+
+    #[test]
+    fn test_lockfile_options_nested_aqua_vars_take_precedence() {
+        let mut opts = ToolVersionOptions::default();
+        opts.opts.insert(
+            "channel".to_string(),
+            toml::Value::String("stable".to_string()),
+        );
+        let mut vars = toml::Table::new();
+        vars.insert(
+            "channel".to_string(),
+            toml::Value::String("beta".to_string()),
+        );
+        opts.opts
+            .insert("vars".to_string(), toml::Value::Table(vars));
+
+        let lock_opts = AquaBackend::lockfile_options(&opts);
+
+        assert_eq!(lock_opts.get("vars.channel"), Some(&"beta".to_string()));
+    }
+
+    #[test]
+    fn test_aqua_install_time_options_include_flat_vars() {
+        assert!(is_install_time_option_key("channel"));
+        assert!(is_install_time_option_key("vars.channel"));
+        assert!(is_install_time_option_key("vars"));
+        assert!(!is_install_time_option_key("symlink_bins"));
+    }
+}
+
 async fn get_tags(pkg: &AquaPackage) -> Result<Vec<String>> {
     Ok(get_tags_with_created_at(pkg)
         .await?
@@ -2073,7 +2349,7 @@ pub fn arch() -> &'static str {
 }
 
 #[cfg(test)]
-mod tests {
+mod lock_candidate_tests {
     fn build_lock_candidates(
         version: &str,
         tag: Option<&str>,
diff --git a/src/backend/mod.rs b/src/backend/mod.rs
index ed45b89933..42515aaac4 100644
--- a/src/backend/mod.rs
+++ b/src/backend/mod.rs
@@ -291,10 +291,25 @@ pub fn install_time_option_keys_for_type(backend_type: &BackendType) -> Vec<Stri
         BackendType::Cargo => cargo::install_time_option_keys(),
         BackendType::Go => go::install_time_option_keys(),
         BackendType::Pipx => pipx::install_time_option_keys(),
+        BackendType::Aqua => aqua::install_time_option_keys(),
         _ => vec![],
     }
 }
 
+/// Returns true if a backend option only affects installation/download.
+/// Used to filter cached options when config provides its own options.
+pub fn is_install_time_option_key_for_type(backend_type: &BackendType, key: &str) -> bool {
+    if matches!(backend_type, BackendType::Aqua) {
+        return aqua::is_install_time_option_key(key);
+    }
+
+    let install_time_keys = install_time_option_keys_for_type(backend_type);
+    install_time_keys.iter().any(|itk| itk == key)
+        || install_time_keys
+            .iter()
+            .any(|itk| key.starts_with("platforms.") && key.ends_with(&format!(".{itk}")))
+}
+
 /// Normalize idiomatic file contents by removing comments and empty lines.
 /// Full-line and inline comments are supported by .python-version, .nvmrc, etc.
 pub(crate) fn normalize_idiomatic_contents(contents: &str) -> String {
diff --git a/src/config/config_file/mise_toml.rs b/src/config/config_file/mise_toml.rs
index 5969952eef..0f5484a2f2 100644
--- a/src/config/config_file/mise_toml.rs
+++ b/src/config/config_file/mise_toml.rs
@@ -772,18 +772,10 @@ impl ConfigFile for MiseToml {
                     // - Changing url/asset_pattern/checksum without reinstall issues
                     // - Preserving post-install options like bin_path for binary discovery
                     let mut ba_opts = ba.opts().clone();
-                    let install_time_keys =
-                        crate::backend::install_time_option_keys_for_type(&ba.backend_type());
-                    if !install_time_keys.is_empty() {
-                        ba_opts.opts.retain(|k, _| {
-                            // Keep option if it's NOT an install-time-only key
-                            // Also filter platform-specific variants (platforms.X.key)
-                            !install_time_keys.contains(k)
-                                && !install_time_keys.iter().any(|itk| {
-                                    k.starts_with("platforms.") && k.ends_with(&format!(".{itk}"))
-                                })
-                        });
-                    }
+                    let backend_type = ba.backend_type();
+                    ba_opts.opts.retain(|k, _| {
+                        !crate::backend::is_install_time_option_key_for_type(&backend_type, k)
+                    });
                     ba_opts.merge(&options.opts);
                     // Re-apply registry defaults for install-time keys not overridden by user.
                     // The filtering above strips both stale install-state cache AND registry
diff --git a/src/toolset/tool_version_options.rs b/src/toolset/tool_version_options.rs
index cdd67699ac..e8ff79d9ff 100644
--- a/src/toolset/tool_version_options.rs
+++ b/src/toolset/tool_version_options.rs
@@ -74,6 +74,11 @@ impl ToolVersionOptions {
         self.opts.get(key).and_then(|v| v.as_str())
     }
 
+    /// Get a scalar value for a key as an owned string.
+    pub fn get_string(&self, key: &str) -> Option<String> {
+        self.opts.get(key).and_then(Self::value_to_string)
+    }
+
     /// Convert opts to string values, extracting inner strings from
     /// `toml::Value::String` and calling `to_string()` on other types.
     pub fn opts_as_strings(&self) -> IndexMap<String, String> {
@@ -164,13 +169,7 @@ impl ToolVersionOptions {
 
     fn get_string_at_path(value: &toml::Value, path: &[&str]) -> Option<String> {
         if path.is_empty() {
-            return match value {
-                toml::Value::String(s) => Some(s.clone()),
-                toml::Value::Integer(i) => Some(i.to_string()),
-                toml::Value::Boolean(b) => Some(b.to_string()),
-                toml::Value::Float(f) => Some(f.to_string()),
-                _ => None,
-            };
+            return Self::value_to_string(value);
         }
 
         match value {
@@ -184,6 +183,16 @@ impl ToolVersionOptions {
             _ => None,
         }
     }
+
+    fn value_to_string(value: &toml::Value) -> Option<String> {
+        match value {
+            toml::Value::String(s) => Some(s.clone()),
+            toml::Value::Integer(i) => Some(i.to_string()),
+            toml::Value::Boolean(b) => Some(b.to_string()),
+            toml::Value::Float(f) => Some(f.to_string()),
+            _ => None,
+        }
+    }
 }
 
 pub fn parse_tool_options(s: &str) -> ToolVersionOptions {
@@ -464,6 +473,18 @@ mod tests {
         assert_eq!(opts.get("strip_components"), Some("1"));
     }
 
+    #[test]
+    fn test_get_string_handles_scalar_values() {
+        let mut opts = ToolVersionOptions::default();
+        opts.opts
+            .insert("integer".to_string(), toml::Value::Integer(124));
+        opts.opts
+            .insert("boolean".to_string(), toml::Value::Boolean(true));
+
+        assert_eq!(opts.get_string("integer"), Some("124".to_string()));
+        assert_eq!(opts.get_string("boolean"), Some("true".to_string()));
+    }
+
     #[test]
     fn test_serialize_tool_options_quotes_comma_strings() {
         let mut opts = IndexMap::new();