Environment variables are available to hosted servers. External and remix
servers use their own connection and authorization settings instead of hosted
build-time environment variables.
Variable contract
Horizon treats an environment variable as part of the build and deployment input. When a build starts, Horizon resolves the target environment, decrypts the matching variables, applies any branch override, and includes the resulting key-value map in the build request. That timing matters. Changing a variable after a build starts does not change that build, and changing a variable after an artifact is live does not update the running server by itself. Create a new build and make sure the deployment selects that artifact before expecting server code to see the new value.Scopes
Environment variables are scoped by where the deployment will run.| Scope | Used by | Behavior |
|---|---|---|
| Production | Default-branch builds and production deployments | Values used for the live production deployment path. |
| Preview | Non-default branch and pull request preview builds | Values used before production promotion. |
| Branch override | A named preview branch | Overrides the preview value for the same key on that branch only. Other preview keys are inherited. |
DATABASE_URL, that branch receives the override and still
inherits any other preview variables that are not overridden.
Manage variables
Open the hosted server, then go to Settings > Environment Variables.Add a variable
Choose Add New Variable, enter the key, value, optional description, and
the scopes that should receive the value. Selecting both production and
preview creates one variable record in each scope with the same initial
value.
Choose whether the value is sensitive
Sensitive variables are write-only in the dashboard after creation.
Non-sensitive variables can be revealed by users who can manage server
settings.
Update or delete values per scope
Production and preview values are separate records. Updating one does not
update the other unless you edit both.
Key rules
Variable names must:- Be 255 characters or fewer.
- Start with an uppercase letter or underscore.
- Use only uppercase letters, numbers, and underscores.
- Not start with
FASTMCP_CLOUD_orHORIZON_, which are reserved by Horizon.
Build-time and runtime behavior
Environment variables can affect both the build and the deployed server. During a build, variables may be available while Horizon installs dependencies, loads the entrypoint, and inspects the server manifest. If your server registers tools conditionally based on an environment variable, preview and production builds can produce different manifests. At runtime, the deployed Python process receives the variables that were included in the selected artifact. Horizon does not reinstall dependencies or refresh environment variables when a request arrives. For the full build lifecycle, see Build system. For runtime behavior, see Compute model.Branch preview behavior
Preview variables are the base configuration for preview builds. Branch overrides layer on top of that base for one branch: each key takes the branch override if one exists, otherwise it inherits the preview base. For example, if thefeature/search branch overrides only DATABASE_URL:
| Key | Preview base | feature/search override | Build receives |
|---|---|---|---|
DATABASE_URL | preview-db | search-branch-db | search-branch-db (overridden) |
MODEL_NAME | test-model | — | test-model (inherited) |
Rotation
Rotate a variable in the scope where the credential is used.Create the replacement upstream credential
Keep the old credential active until Horizon has deployed the new value.
Update Horizon
Update the production, preview, or branch-scoped value that should use the
replacement credential.
Build and verify
Start a new build, deploy it to the relevant preview or production
deployment, and confirm representative tool calls succeed.
Troubleshooting
A new value is not visible to server code
A new value is not visible to server code
Confirm a new build started after the variable was saved, then confirm the
deployment selects that build artifact. Existing artifacts keep the values
they were built with.
A preview deployment is using the wrong value
A preview deployment is using the wrong value
Check whether the build is for the expected branch. Preview builds use
preview variables, then apply branch overrides for that branch.
A branch override is not applied
A branch override is not applied
Branch overrides apply only to preview deployments. Confirm the override is
attached to the exact branch name used by the build, then rebuild that
branch.
A variable cannot be created
A variable cannot be created
Check the key name. Keys must start with an uppercase letter or underscore,
use only uppercase letters, numbers, and underscores, and avoid reserved
prefixes.
A tool is missing after a successful build
A tool is missing after a successful build
If tool registration depends on environment variables, compare the manifest
for the build that is live with the expected scope and branch values.
A secret value appeared in logs
A secret value appeared in logs
Rotate the credential, update the matching Horizon scope, rebuild and
redeploy, then remove or mask the logging statement in server code.
Related docs
Hosted servers
Understand the hosted-server lifecycle and ownership boundary.
Builds
See how build inputs become immutable artifacts.
Deployments
Confirm which artifact is live for production or preview traffic.