Skip to main content
The Environments page at hud.ai/environments is where you deploy, configure, and monitor your agent environments. Connect a GitHub repo or push via CLI, configure environment variables, and see live build status.

​
Overview

Navigate to Environments to see two main tabs:
  • Explore — Browse public environments from the community
  • My Environments — Environments you’ve created or deployed
The header shows real-time stats: environments run in the last 24 hours and currently active instances.
Environments page showing deployed environments

​
Creating an Environment

Click New Environment to create one. You have three options:

​
Import from GitHub

Connect a GitHub repository containing your environment code.

​
Connect GitHub

First, connect your GitHub account by installing the GitHub App:
  1. Click Connect GitHub to install the HUD GitHub App
  2. You’ll be redirected to GitHub to authorize the installation
  3. Choose repository access:
    • All repositories — HUD can build from any repo in your account
    • Only select repositories — Grant access to specific repos
Connect GitHub button
You can change repository access later in your GitHub settings.

​
Build from Repository

Once GitHub is connected:
  1. Select a repository from the list
  2. Choose a branch (defaults to main)
  3. Click Import
Repository selection
HUD will clone your repo, build the Docker image, and push it to the HUD registry. Watch build logs in real-time on the Builds tab.

​
Automatic Rebuilds

HUD automatically rebuilds your environment when you push changes to the connected branch. To manually trigger a rebuild, go to the Builds tab and click Rebuild.
Rebuild button in Builds tab

​
Create from Template

Start from a pre-built template:
  • Blank — Minimal starter environment
  • Browser — Browser automation with Playwright
  • Deep Research — Web research and analysis tools

​
Push via CLI

Develop locally and push directly: 
hud init          # Scaffold a new environment
hud dev           # Test locally with hot reload
hud push          # Deploy to platform

​
Environment Details

Click on an environment to see its detail page with several tabs:

​
Overview Tab

The main landing page shows:
  • Source — GitHub repo link or “Pushed via CLI”
  • Visibility — Public or private
  • Tools — Available tools with their schemas
  • Code Snippet — Copy-paste code to use this environment
If environment variables are missing, you’ll see a warning banner linking to Settings.

​
Scenarios Tab

Lists all scenarios defined with @env.scenario():
  • Name — The scenario identifier
  • Description — What the scenario tests
  • Arguments — Required parameters
Click a scenario to see its full definition and create tasks from it.
Scenarios tab showing available scenarios

​
Builds Tab

Shows build history and status (for GitHub-connected environments):
  • Status — Building, Success, or Failed
  • Duration — How long the build took
  • Commit — Git commit that triggered the build
  • Logs — Click to view full build output
Failed builds show error details to help debug issues.
Builds tab is only available for environments connected to GitHub. Environments pushed via CLI don’t show builds.

​
Settings Tab

Configure your environment:
  • Display Name — How it appears in the UI
  • Build Settings — Branch and entry folder
  • Environment Variables — Secrets and configuration (see below)

​
Environment Variables

Many environments need API keys or configuration. Add them in Settings:
  1. Go to your environment’s Settings tab
  2. Find the Environment Variables section
  3. Add key-value pairs for each variable
  4. Click Save
Variables are encrypted at rest and injected at runtime. They’re available in your environment code as regular environment variables.
Never commit secrets to your repository. Always use environment variables for API keys and credentials.

​
Lock File Variables

If your environment has a hud.lock file defining required variables, Settings will show which ones are missing. You’ll see warnings until all required variables are configured.

​
Using Environments

Once deployed, use your environment in evaluations: 
import hud

# Create a task from a deployed environment
task = hud.Task(
    scenario="my-env/checkout",
    args={"product_name": "Laptop"}
)

async with hud.eval(task) as ctx:
    # Your agent code here
    await ctx.submit(response)
Or run from the CLI: 
hud eval my-env/checkout --model gpt-4o --group-size 10

​
Troubleshooting Builds

IssueSolution
Repository not appearingCheck that you’ve granted HUD access in GitHub settings
Build fails immediatelyVerify your Dockerfile exists in the repository root or check the build logs
Docker Hub rate limit errorSave your Docker Hub credentials in settings
Build times outReduce image size or use multi-stage builds
For local debugging before pushing, see hud debug.

​
Next Steps

Build Environments

Learn the environment SDK

Deploy Guide

Push your environment to production