Solution Variables

Variables allow solutions to have environment-specific configuration without modifying the underlying actions or sequences.

What Are Variables?

Variables are placeholders in your solution that can have different values per environment:

Variable	Development	Staging	Production
database_host	dev-db.local	staging-db.company.com	prod-db.company.com
log_level	debug	info	warn
replica_count	1	2	5

Variable Templates

Variables are defined as templates on the solution, then values are set per environment.

Template Properties

Property	Description	Required
Name	Identifier (e.g., database_host)	Yes
Label	Display name	Yes
Help Text	Guidance for operators	No
Control Type	Input type (text, select, etc.)	Yes
Default Value	Fallback if not set	No
Required	Must have a value	Yes

Control Types

Text

Single-line text input:

┌─────────────────────────────────────────────────────────┐
│  Database Hostname                                      │
│  ┌───────────────────────────────────────────────────┐  │
│  │ db.example.com                                    │  │
│  └───────────────────────────────────────────────────┘  │
│  Enter the primary database server address              │
└─────────────────────────────────────────────────────────┘

Use for: Hostnames, URLs, paths, simple values

Multiline

Multi-line text area:

┌─────────────────────────────────────────────────────────┐
│  Configuration JSON                                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │ {                                                 │  │
│  │   "feature_flags": {                              │  │
│  │     "new_checkout": true                          │  │
│  │   }                                               │  │
│  │ }                                                 │  │
│  └───────────────────────────────────────────────────┘  │
│  JSON configuration for the application                 │
└─────────────────────────────────────────────────────────┘

Use for: JSON, YAML, configuration files, scripts

Select

Dropdown selection:

┌─────────────────────────────────────────────────────────┐
│  Log Level                                              │
│  ┌───────────────────────────────────────────────────┐  │
│  │ info                                          ▼   │  │
│  └───────────────────────────────────────────────────┘  │
│  • debug                                                │
│  • info                                                 │
│  • warn                                                 │
│  • error                                                │
└─────────────────────────────────────────────────────────┘

Use for: Predefined options, log levels, regions

Checkbox

Boolean toggle:

┌─────────────────────────────────────────────────────────┐
│  Enable Debug Mode                                      │
│  ┌───┐                                                  │
│  │ ✓ │ Enable                                           │
│  └───┘                                                  │
│  Turn on detailed logging for troubleshooting           │
└─────────────────────────────────────────────────────────┘

Use for: Feature flags, on/off settings

Sensitive

Masked input for secrets:

┌─────────────────────────────────────────────────────────┐
│  API Key                                                │
│  ┌───────────────────────────────────────────────────┐  │
│  │ ••••••••••••••••••••••••••                        │  │
│  └───────────────────────────────────────────────────┘  │
│  API key for external service integration               │
└─────────────────────────────────────────────────────────┘

Use for: Passwords, API keys, tokens, secrets

Note

Sensitive variables are encrypted at rest and never displayed in logs or the UI after being set.

Creating Variable Templates

Where variables are authored

There is no Variables tab or template editor on the solution page. Author variables in the Variable Sets UI (or via the variables API) and scope them to the solution with scope_solution_id. Each variable carries its own name, type (string / sensitive / certificate / execution_pool), value and prompt/is_prompted metadata.

Note

Solution-scoped prompted variables are currently read-only in Lens (served by GET /solutions/{id}/prompted-variables). There is no in-product editor for authoring them yet — use the variable-sets UI or the API.

Setting Environment Values

Per-Environment Configuration

Per-environment values are set on the variable itself, by giving it a scope_environment_id (there is no “Configure Variables” button on the environment page). Create one variable per environment value, or use a variable set scoped to both the solution and the environment.

Using Variables in Actions

Resolved variables reach an action in two ways during deployment:

1. {{...}} substitution in command arguments, the script file name, and the working directory. The supported placeholder syntaxes are {{variable}} (mustache) and ${variable} (shell-style).
2. MANTIS_* environment variables injected into the executed process. Each resolved variable is exposed as an uppercased, MANTIS_-prefixed environment variable (for example, database_host becomes MANTIS_DATABASE_HOST).

In Command Payloads

Command payloads are structured (a binary plus ordered arguments), so reference variables inside individual arguments with {{...}}:

• Binary: docker
• Argument 1: run
• Argument 2: --env
• Argument 3: DB_HOST={{database_host}}
• Argument 4: --env
• Argument 5: LOG_LEVEL={{log_level}}
• Argument 6: myapp

When using the DefaultShell executor (the default), arguments are passed directly to the binary without any shell interpretation, so shell metacharacters are treated as literal values. When using the Sh, Bash, Pwsh, or Zsh executors, Mantis rejects shell metacharacters (;, |, $, `, etc.) in arguments before execution, preventing chaining, piping, or $VAR expansion; the arguments are then safely quoted and passed to the shell as a single composed command.

In Script Payloads

A script’s content is not substituted. Read resolved variables from their MANTIS_* environment variables instead:

#!/bin/bash
echo "Connecting to $MANTIS_DATABASE_HOST"
docker compose up -d --scale web="$MANTIS_REPLICA_COUNT"

Variable Resolution

Mantis resolves each variable by additive specificity: every variable with the key whose scopes all match the deployment context is a candidate, each scored by the sum of its scopes’ points, and the highest total wins. Solution scope is worth 40 points — well below tenant (200), environment (100) and target (500) — so a solution-level default is a low-priority fallback, not “level 1”.

Scope	Points
Current action	1000
Current target	500
Tenant	200
Environment	100
Solution	40
Variable set	20
Global	0

(The full 11-level table is in Tenant Variables.)

A variable whose scope does not match the context is discarded outright. If no candidate matches a required variable, the deployment errors; otherwise resolution falls back to the lowest-scoring match (often the global or solution value).

Best Practices

1. Use Descriptive Names

Good: database_primary_host, api_gateway_url
Bad:  db, host1, var1

2. Add Help Text

Help operators understand what values to provide:

Variable: connection_string
Help: PostgreSQL connection string in format:
      postgres://user:pass@host:5432/dbname

3. Set Sensible Defaults

Provide defaults for development/testing:

Variable: log_level
Default: info
(Production can override to "warn")

4. Mark Secrets as Sensitive

Encryption and log masking key off the variable’s type (variable_type = sensitive), not the control type. Set the variable’s type to sensitive for:

• Passwords
• API keys
• Tokens
• Certificates
• Connection strings with credentials

5. Validate Early

Set variables as required when they must have values:

Variable: database_host
Required: true
(Deployment fails if not set)

Common Variable Patterns

Database Configuration

Variable	Type	Example
database_host	Text	db.example.com
database_port	Text	5432
database_name	Text	myapp_production
database_user	Text	app_user
database_password	Sensitive	•••••••

Feature Flags

Variable	Type	Example
feature_new_ui	Checkbox	true
feature_beta_api	Checkbox	false
feature_analytics	Checkbox	true

Scaling

Variable	Type	Example
web_replicas	Text	3
worker_replicas	Text	2
max_connections	Text	100

Troubleshooting

Variable Not Substituted

Symptom: Seeing {{variable_name}} in output

Solutions:

• Check variable is defined on solution
• Check environment has a value set
• Verify spelling matches exactly
• Remember that script content is never substituted — a script should read the value from its MANTIS_* environment variable instead

Deployment Fails: Missing Required Variable

Symptom: Deployment fails with “Missing required prompted variables: ”

Solution: Set the value on the target environment before deploying

Sensitive Value Exposed in Logs

Symptom: Secret appears in deployment logs

Solution: Set the variable’s type to sensitive (variable_type = sensitive). Masking and encryption read variable_type, never the free-text control type — setting the control type to “sensitive” does not mask or encrypt the value.

Next Steps

• Creating Solutions - Create new solutions
• Versioning - Version management
• Promotion Lifecycle - Environment progression
• Overview - Return to solutions overview