> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horizon.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Configure encrypted server values for production and preview deployments.

Environment variables are
[encrypted](/security/data-protection) configuration values for hosted servers.
They are attached to a server, scoped to the deployment environment that will
use them, and provided to your Python process when Horizon builds and runs a
deployment artifact.

Use environment variables for values your server code needs at startup, during
manifest inspection, or while handling MCP requests: upstream API keys,
database URLs, feature toggles, model names, and similar configuration.

<Info>
  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.
</Info>

## Variable contract

Horizon treats an environment variable as part of the build and deployment
input. When Horizon prepares a build or deployment, it decrypts the variables
for the target environment. Deployment values take precedence for that
deployment.

That timing matters. Changing a variable does not alter work already in
progress, 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.

<Warning>
  Avoid printing secret values to stdout or stderr. Horizon captures those
  streams as server logs.
</Warning>

## Environments

Environment variables belong to the environment where a deployment will run.

| Environment | 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.             |

<Tip>
  Keep production and preview credentials separate when the upstream system has
  separate projects, databases, accounts, or rate limits. Preview builds should
  be safe to test without touching production data.
</Tip>

## Manage variables

Open the hosted server, then go to **Settings** > **Environment Variables**.

<Steps>
  <Step title="Add a variable">
    Choose **Add variable**, then enter the key, value, and an optional
    description. Check the environments that should receive the value.
    Checking both Production and Preview creates one variable record in each
    environment with the same initial value.
  </Step>

  <Step title="Choose whether the value is sensitive">
    New variables are sensitive by default. Sensitive variables are write-only
    after creation. Users who can manage server settings can copy a
    non-sensitive value to the clipboard; the dashboard does not display
    stored values. To make an existing non-sensitive variable write-only, open
    its actions menu and choose **Mark as sensitive**. This change cannot be
    reversed.
  </Step>

  <Step title="Update or delete values per environment">
    Production and Preview values are separate records. Updating one does not
    update the other unless you edit both.
  </Step>

  <Step title="Redeploy">
    Create a new build and deploy or promote it so server code receives the
    changed values.
  </Step>
</Steps>

## 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_` or `HORIZON_`, which are reserved by
  Horizon.

The dashboard uppercases keys as you type. Values must not be empty and can
contain multiline content such as JSON.

## 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](/platform/build-system). For
runtime behavior, see [Compute model](/platform/compute-model).

## Deployment overrides

The `env` values supplied when creating a deployment take precedence over the
variables configured for its target environment. For example, a preview
deployment can use `MODEL_NAME` from Preview settings while overriding
`DATABASE_URL`. Other preview deployments continue to use the saved Preview
value.

Use deployment overrides for branch-specific configuration and other values
that apply to one deployment. Use Production and Preview settings for values
shared by every deployment in an environment. See the generated
[API reference](https://horizon.prefect.io/api/v0/docs) for the deployment
request contract.

## Rotation

Rotate a variable in the environment where the credential is used.

<Steps>
  <Step title="Create the replacement upstream credential">
    Keep the old credential active until Horizon has deployed the new value.
  </Step>

  <Step title="Update Horizon">
    Update the Production or Preview value. For a deployment override, update
    the deployment input instead.
  </Step>

  <Step title="Build and verify">
    Start a new build, deploy it to the relevant preview or production
    deployment, and confirm representative tool calls succeed.
  </Step>

  <Step title="Revoke the old credential">
    Revoke the old value only after the deployment using the new value is live.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="A preview deployment is using the wrong value">
    Confirm that the deployment uses a preview target, then check whether its
    `env` input overrides the saved Preview value.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 values available during that build.
  </Accordion>

  <Accordion title="A secret value appeared in logs">
    Rotate the credential, update the matching environment, rebuild and redeploy,
    then remove or mask the logging statement in server code.
  </Accordion>
</AccordionGroup>

## Related docs

<CardGroup cols={2}>
  <Card title="Hosted servers" icon="server" href="/servers/hosted">
    Understand the hosted-server lifecycle and ownership boundary.
  </Card>

  <Card title="Builds" icon="hammer" href="/builds">
    See how build inputs become immutable artifacts.
  </Card>

  <Card title="Deployments" icon="cloud-arrow-up" href="/deployments">
    Confirm which artifact is live for production or preview traffic.
  </Card>

  <Card title="Encryption and data protection" icon="lock" href="/security/data-protection">
    How values are encrypted at rest and kept out of logs and responses.
  </Card>
</CardGroup>