Skip to main content
The hud deploy command builds and deploys your environment directly to the HUD platform from a Dockerfile, without requiring a GitHub repository.
This is the recommended way to deploy environments. Unlike hud push which pushes to Docker Hub, hud deploy builds remotely on HUD’s infrastructure and stores the image in HUD’s registry.

​
Usage

hud deploy [DIRECTORY] [OPTIONS]

​
Arguments

​
directory
string
default:"."
Environment directory containing a Dockerfile.hud or Dockerfile

​
Options

​
--name
string
Environment display name. Defaults to [tool.hud].name in pyproject.toml, or directory name. Short: -n
​
--env
string
Environment variable in KEY=VALUE format. Can be repeated. Short: -e
​
--env-file
string
Path to .env file (default: .env in directory if exists)
​
--build-arg
string
Docker build argument in KEY=VALUE format. Can be repeated. Used for Dockerfile ARG directives.
​
--secret
string
Docker build secret. Format: id=SECRET_ID,env=ENV_VAR or id=SECRET_ID,src=./path. Encrypted at rest.
​
--no-cache
boolean
default:"false"
Disable Docker build cache for a clean rebuild
​
--yes
boolean
default:"false"
Skip confirmation prompts. Short: -y
​
--verbose
boolean
default:"false"
Show detailed output including files added to tarball. Short: -v

​
Prerequisites

Requires HUD_API_KEY:
hud set HUD_API_KEY=your-api-key
# or
export HUD_API_KEY="your-api-key"
Get your API key at hud.ai/settings.

​
What It Does

1

Package Context

Creates a tarball of your build context, respecting .dockerignore and excluding sensitive files (.env, .git, etc.)
2

Upload

Uploads the tarball to HUD’s build service via a secure presigned URL
3

Build

Triggers a remote build via AWS CodeBuild using your Dockerfile
4

Stream Logs

Streams build logs in real-time via WebSocket
5

Link

Creates .hud/deploy.json to link this directory to the deployed environment for future rebuilds

​
Environment Variables, Build Arguments & Secrets

Three flags for different purposes:
FlagWhen UsedStored InUse For
--envRuntimePlatform (encrypted)API keys, feature flags, runtime config
--build-argBuild timeImage layersRepo URLs, build modes, versions
--secretBuild timeNot stored in imagePrivate repo tokens, credentials during build
Runtime environment variables — injected when the container runs.
hud deploy . -e API_KEY=secret -e DEBUG=true
Values are encrypted on the platform and can be changed without rebuilding.
Common mistake: Using --env for Dockerfile ARG values. If your Dockerfile has ARG REPO_URL, use --build-arg REPO_URL=..., not -e REPO_URL=....

​
Environment Name Resolution

The environment name is determined in this order:
  1. --name flag (explicit)
  2. [tool.hud].name in pyproject.toml
  3. [tool.hud].image in pyproject.toml (name part, without tag)
  4. Directory name
# pyproject.toml
[tool.hud]
name = "My Browser Environment"

​
Examples

​
Basic Deploy

# Deploy current directory
hud deploy

# Deploy specific directory
hud deploy environments/browser

​
With Environment Variables

# Pass runtime env vars
hud deploy . -e API_KEY=secret -e DEBUG=true

# Use env file
hud deploy . --env-file .env.production

​
With Build Arguments

# Pass Docker build arguments
hud deploy . --build-arg NODE_ENV=production

# Multiple build args
hud deploy . --build-arg REPO_URL=https://github.com/org/repo --build-arg FOLDER_NAME=project

​
With Build Secrets

# Secret from environment variable
hud deploy . --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN

# Secret from file
hud deploy . --secret id=SSH_KEY,src=~/.ssh/deploy_key

​
Combined Usage

# All three: build args + secrets for build, env vars for runtime
hud deploy . --build-arg REPO_URL=https://github.com/org/repo \
             --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN \
             -e API_KEY=secret

​
Custom Name

hud deploy . --name "Production Browser"

​
Non-Interactive (CI/CD)

hud deploy . --yes --no-cache

​
Rebuilding

When you run hud deploy again in a linked directory:
  1. Reads .hud/deploy.json to find the existing environment
  2. Fetches stored environment variables from the platform
  3. Builds a new version of the same environment
  4. Version number auto-increments (0.1.0 → 0.1.1 → 0.1.2)

​
Project Linking

After deployment, .hud/deploy.json is created: 
{
  "registryId": "abc123-def456-...",
  "version": "0.1.0"
}
This links the directory to the platform environment. To unlink: 
rm .hud/deploy.json
To link to a different existing environment: 
hud link --id existing-registry-id

​
.dockerignore

Create a .dockerignore file to exclude files from the build context: 
# .dockerignore
.git
.venv
__pycache__
*.pyc
node_modules
.env
.env.*
Even without .dockerignore, HUD automatically excludes common sensitive files like .env, .git, and virtual environments.

​
Comparison with hud build + hud push

Featurehud deployhud build + hud push
Build locationRemote (HUD CodeBuild)Local (Docker)
RegistryHUD ECRDocker Hub/GHCR
Build argsYes (--build-arg)Yes (via hud build)
Build secretsYes (--secret)Yes (via hud build)
Env var storageHUD platformNot stored
Recommended forPlatform deploymentsDocker Hub sharing
hud push only pushes an already-built image. Use hud build --build-arg and hud build --secret for local builds with build arguments and secrets, then hud push to share.

​
See Also