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

# Environments

> Deploy an environment, follow its build, configure runtime variables, and run its task templates on HUD.

Author and test an environment with the [SDK guide](/v6/guides/creating-an-environment). This page
is the platform half, from `hud deploy` to a running task.

A first deployment needs a team API key and two commands:

```bash theme={"dark"}
hud set HUD_API_KEY=your-key
hud deploy
```

Create a key under [API Keys](https://hud.ai/project/api-keys). After the upload begins, open
[Environments](https://hud.ai/environments) to follow the build.

## Environment, build, and template

An **environment** is the stable platform record. Each deployment creates a **build**, an immutable
version of its source and runnable image. A successful build exposes the environment's
`@env.template()` definitions as **task templates**.

```mermaid theme={"dark"}
flowchart LR
    S["Local source"] -->|"hud deploy"| E["Environment"]
    E --> B1["Build 1"]
    E --> B2["Build 2"]
    B2 --> T["Task templates"]
```

This separation lets you inspect old builds while new work is building. Runs started during an
active build can continue using the previous successful build until the new one is ready.

## Follow a deployment

The environment page shows an active build on the overview and keeps the full history under
**Builds**.

| Status        | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| `IN_PROGRESS` | HUD is building and inspecting the uploaded environment.                     |
| `MIGRATING`   | The image succeeded and HUD is linking its task templates to existing tasks. |
| `SUCCEEDED`   | The build is available for new runs.                                         |
| `FAILED`      | The image or environment inspection failed. Open the build for logs.         |
| `CANCELLED`   | The build was stopped before completion.                                     |

Open a build to read its logs and source. A failed build does not replace the latest successful
one.

## Configure runtime variables

An environment can declare variables that its tasks need, such as credentials for an external
service. Open **Settings** to add them. Values are masked after saving and injected when HUD starts
an instance for that environment.

The overview separates missing required variables from optional ones. A task cannot run until the
variables required by its template are configured.

<Note>
  Compute resources and timeouts belong to the task's
  [`RuntimeConfig`](/v6/reference/runtime#runtimeconfig), not the environment settings page. This
  keeps placement requirements attached to the work that needs them.
</Note>

## Run a task template

Open **Templates** after the build succeeds. Select a template, fill its arguments, choose a model,
and start a run. HUD creates a job containing one or more traces and opens the job page as soon as
the batch is queued.

For a reusable suite, create concrete tasks from the template and group them in a
[taskset](/platform/tasksets). Tasksets are the normal input to a multi-model
[evaluation](/platform/evaluations).

## Read the environment page

| Tab           | What it shows                                                                       |
| ------------- | ----------------------------------------------------------------------------------- |
| **Overview**  | Description, current build, required variables, templates, and linked tasksets.     |
| **Templates** | Parameterized task definitions discovered from the build.                           |
| **Builds**    | Deployment history, statuses, logs, and source for each build.                      |
| **Files**     | The source uploaded for a selected build. This is not a trace's live workspace.     |
| **Instances** | Sandboxes currently running, starting, or recently terminated for this environment. |
| **Settings**  | Name, environment variables, and environment-level controls.                        |

Public viewers see the overview and templates. Editors see the operational tabs.

## Share or publish

**Share** grants another team or member scoped access without making the environment public.
**Publish** makes a private environment publicly discoverable and requires a successful build.
Use **Public view** to preview what other users will see before publishing.

The tasks that belong with the environment publish through [tasksets](/platform/tasksets).