GitHub Release

Develop Once, Deploy Anywhere.

Take your app from Compose to a secure and scalable deployment on your favorite cloud in minutes.

How It Works

flowchart LR

subgraph local["Your Machine or CI/CD"]
    compose["compose.yaml"] --&gt; cli["Defang CLI"]
end

subgraph defang["Defang Backend"]
    fabric["Fabric API (gRPC)"]
end

subgraph cloud["Your Cloud Account"]
    secrets["Config &amp; Secrets"]
    cd["Defang CD Task"]
    logs["Logs"]
    runtime["Load Balancer, Containers, DB, Cache, LLM, DNS, Roles"]
end

%% control plane
cli &lt;-.-&gt; fabric

%% deploy
cli --&gt; secrets
cli --&gt; cd
cd --&gt; runtime

%% observability
cli -.-&gt; logs

You write a standard Docker Compose file
Defang CLI validates your Compose project and uploads the project to storage in your AWS/GCP account
CD runs in your cloud — a deployment task spins up in your AWS/GCP account
Infrastructure is created — containers, DNS, load balancing, and roles are provisioned
Monitor the deployment and tail or query runtime logs with the Defang CLI

Your code and secrets never leave your cloud account. Defang orchestrates the deployment, but everything runs in your infrastructure.

Defang CLI

The Defang Command-Line Interface (CLI) is designed for developers who prefer to manage their workflows directly from the terminal. It offers full access to Defang’s capabilities, allowing you to build, test, and deploy applications efficiently to the cloud.

Deploying with Defang

If you already have a Docker Compose file, create a new stack and then deploy it. For example:

$ defang stack new
? Which cloud provider do you want to deploy to? AWS
? Which AWS region do you want to deploy to? us-west-2
? Which deployment mode do you want to use? AFFORDABLE
? What do you want to call this stack? awsuswest2
 * Created new stack configuration file: `.defang/awsuswest2`. Check this file into version control. You can now deploy this stack using `defang up --stack=awsuswest2`

$ defang up --stack=awsuswest2

Defang MCP Server

The Defang Model Context Protocol (MCP) Server is tailored for developers who work primarily within integrated development environments (IDEs). It enables seamless cloud deployment from supported editors such as Cursor, Windsurf, VS Code, VS Code Insiders and Claude delivering a fully integrated experience without leaving your development environment.

Claude Code Plugin

Install the Defang plugin for Claude Code to deploy directly from any Claude Code session — no CLI required upfront:

/plugin marketplace add DefangLabs/defang
/plugin install defang@defang-skills

After installing, use /defang:deploy to guide you through deploying your project. The Defang MCP server activates automatically once the Defang CLI is installed.

This repo includes:

Public releases of the Defang CLI; click here for the latest version
Built-in support for MCP Server — the Defang MCP Server makes cloud deployment as easy as a single prompt. Learn more
Samples that show how to deploy an app using the Defang Pulumi Provider.

Getting started

Read our Getting Started page
Follow the installation instructions from the Installing page
Take a look at our Samples in Golang, Python, and Node.js that show how to accomplish various tasks and deploy them
Try the AI integration by running defang generate
Start your new service with defang compose up

Installing

Install the Defang CLI from one of the following sources:

Using the Homebrew package manager DefangLabs/defang tap:
```
brew install DefangLabs/defang/defang
```

Using a shell script:

eval "$(curl -fsSL s.defang.io/install)"

Using Go:

go install github.com/DefangLabs/defang/src/cmd/cli@latest

Using the Nix package manager:
- with Nix-Env:
```
nix-env -if https://github.com/DefangLabs/defang/archive/main.tar.gz
```
- or with Flakes:
```
nix profile install github:DefangLabs/defang#defang-cli --refresh
```
Released tags are available from our Cachix binary cache, so you can download the CLI instead of compiling it. If you have Cachix installed, run cachix use defanglabs; otherwise add these lines to /etc/nix/nix.conf (or ~/.config/nix/nix.conf if you are a trusted user):
```
extra-substituters = https://defanglabs.cachix.org
extra-trusted-public-keys = defanglabs.cachix.org-1:mTXLTfYprWDrIK50Kz34fhOTreeKlQRZFQcKL7HtHx0=
```
Then install a tagged version, e.g. nix profile install github:DefangLabs/defang/v3.14.1#defang-cli. The cache holds x86_64-linux and aarch64-darwin builds. Other platforms, and builds from main, compile from source as before.
Using winget:
```
winget install defang
```

Using a PowerShell script:

iwr https://s.defang.io/defang_win_amd64.zip -OutFile defang.zip
Expand-Archive defang.zip . -Force

Using the official image from Docker Hub:

docker run -it defangio/defang-cli help

Using NPX:
```
npx defang@latest help
```
or download the latest binary of the Defang CLI.

Support

File any issues here

Command completion

The Defang CLI supports command completion for Bash, Zsh, Fish, and Powershell. To get the shell script for command completion, run the following command:

defang completion [bash|zsh|fish|powershell]

If you're using Bash, you can add the following to your ~/.bashrc file:

source &lt;(defang completion bash)

If you're using Zsh, you can add the following to your ~/.zshrc file:

source &lt;(defang completion zsh)

or pipe the output to a file called _defang in the directory with the completions.

If you're using Fish, you can add the following to your ~/.config/fish/config.fish file:

defang completion fish | source

If you're using Powershell, you can add the following to your $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 file:

Invoke-Expression -Command (defang completion powershell | Out-String)

Environment Variables

The Defang CLI recognizes the following environment variables:

COMPOSE_DISABLE_ENV_FILE - Whether to disable loading environment variables from a .env file in the current directory; defaults to false
COMPOSE_ENV_FILES - A comma-separated list of environment file(s) to use for interpolation instead of .env; overridden by the --env-file flag
COMPOSE_FILE - The Compose file(s) to use; defaults to compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml in the current directory
COMPOSE_PATH_SEPARATOR - The path separator to use for COMPOSE_FILE; defaults to : on Unix/MacOS and ; on Windows
COMPOSE_PROJECT_NAME - The name of the project to use; overrides the name in the Compose file
DEFANG_ACCESS_TOKEN - The access token to use for authentication; if not specified, uses token from defang login
DEFANG_ALLOW_UPGRADE - If set to true, allows upgrading the CD image and Pulumi version to the latest available; defaults to false, ie. previously deployed versions will be used to avoid unexpected upgrades
DEFANG_AWS_APN_ID - The AWS APN ID to use for attribution, eg. use pc:123456789abcdefgh for AWS Marketplace products
DEFANG_BUILD_CONTEXT_LIMIT - The maximum size of the build context when building container images; defaults to 100MiB
DEFANG_CD_BUCKET - The S3 bucket to use for the BYOC CD pipeline; defaults to defang-cd-bucket-…
DEFANG_CD_IMAGE - The image to use for the Continuous Deployment (CD) pipeline; defaults to public.ecr.aws/defang-io/cd:public-beta
DEFANG_DEBUG - set this to 1 or true to enable debug logging
DEFANG_DISABLE_ANALYTICS - If set to true, disables sending analytics to Defang; defaults to false
DEFANG_EDITOR - The editor to launch after new project generation; defaults to code (VS Code)
DEFANG_FABRIC - The address of the Defang Fabric to use; defaults to fabric-prod1.defang.dev
DEFANG_JSON - If set to true, outputs JSON instead of human-readable output; defaults to false
DEFANG_HIDE_HINTS - If set to true, hides hints in the CLI output; defaults to false
DEFANG_HIDE_UPDATE - If set to true, hides the update notification; defaults to false
DEFANG_ISSUER - The OAuth2 issuer to use for authentication; defaults to https://auth.defang.io
DEFANG_MODEL_ID - The model ID of the LLM to use for the generate/debug AI integration (Pro users only)
DEFANG_NO_CACHE - If set to true, disables pull-through caching of container images; defaults to false
DEFANG_PREFIX - The prefix to use for all BYOC resources; defaults to Defang
DEFANG_PROVIDER - The name of the cloud provider to use, auto (default), aws, azure, digitalocean, gcp, or defang
DEFANG_PULUMI_BACKEND - The Pulumi backend URL or "pulumi-cloud"; defaults to a self-hosted backend
DEFANG_PULUMI_DEBUG - If set to true, enables debug logging for Pulumi operations; defaults to false
DEFANG_PULUMI_DIFF - If set to true, shows the Pulumi diff during deployments; defaults to false
DEFANG_PULUMI_DIR - Run Pulumi from this folder, instead of spawning a cloud task; requires --debug (BYOC only)
DEFANG_PULUMI_VERSION - Override the version of the Pulumi image to use (aws provider only)
DEFANG_RECIPE - The deployment mode / recipe to use; defaults to AFFORDABLE
DEFANG_STACK - The name of the stack to use
DEFANG_SUFFIX - The suffix to use for all BYOC resources; defaults to the stack name, or beta if unset.
DEFANG_WORKSPACE - The workspace (name or ID) to use; preferred way to select which workspace the CLI uses
GCP_PROJECT_ID - The Google Cloud project ID for the gcp provider; must be a real shell environment variable (e.g. export GCP_PROJECT_ID=my-project-id), not set via defang config set. Also recognized: GOOGLE_PROJECT, GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, CLOUDSDK_CORE_PROJECT
NO_COLOR - If set to any value, disables color output; by default, color output is enabled depending on the terminal
PULUMI_ACCESS_TOKEN - The Pulumi access token to use for authentication to Pulumi Cloud; see DEFANG_PULUMI_BACKEND
PULUMI_CONFIG_PASSPHRASE - Passphrase used to generate a unique key for your stack, and configuration and encrypted state values
TZ - The timezone to use for log timestamps: an IANA TZ name like UTC or Europe/Amsterdam; defaults to Local
XDG_STATE_HOME - The directory to use for storing state; defaults to ~/.local/state

Environment variables will be loaded from a .defang file in the current directory, if it exists. This file follows the same format as a .env file: KEY=VALUE pairs on each line, lines starting with # are treated as comments and ignored.

Compose interpolation

After selecting a stack, the CLI makes the resolved DEFANG_PROVIDER and DEFANG_STACK values available for Compose interpolation. They are not injected into services automatically; reference them explicitly where needed:

services:
  app:
    environment:
      PUBLISH_PROVIDER: "${DEFANG_PROVIDER}"
      PUBLISH_STACK: "${DEFANG_STACK}"

The resolved values take precedence over values with the same names in Compose env files. Fields that Compose must decode before stack selection should provide a default, such as ${DEFANG_PROVIDER:-auto}.

Development

At Defang we use the Nix package manager for our dev environment, in conjunction with DirEnv.

To get started quickly, install Nix and DirEnv, then create a .envrc file to automatically load the Defang developer environment:

echo use flake &gt;&gt; .envrc
direnv allow

Adding cloud support

At a high-level, support for a specific cloud lives in three repositories:

In this CLI repository
- an implementation of the client.Provider interface under the byoc package
- low-level cloud helpers ("driver") under the clouds package
  - authenticate with the cloud
  - start a CD container (task/job)
  - monitor the CD container's status and logs
  - stream/query logs from deployed services
  - set/list config (secrets/parameters)
In the Defang Pulumi Provider repository
- Pulumi component resources under the provider folder
  - Project component
  - Service component
  - Postgres component
  - Redis component
- a Pulumi custom resource for Build
- an implementation of the ConfigProvider interface to read config (secrets/parameters) at deploy time
In the Defang Docs repository
- under the providers section, documentation for how to set up credentials and permissions for the cloud, and any cloud-specific features

GitHub Release

Develop Once, Deploy Anywhere.

Take your app from Compose to a secure and scalable deployment on your favorite cloud in minutes.

How It Works

flowchart LR

subgraph local["Your Machine or CI/CD"]
    compose["compose.yaml"] --&gt; cli["Defang CLI"]
end

subgraph defang["Defang Backend"]
    fabric["Fabric API (gRPC)"]
end

subgraph cloud["Your Cloud Account"]
    secrets["Config &amp; Secrets"]
    cd["Defang CD Task"]
    logs["Logs"]
    runtime["Load Balancer, Containers, DB, Cache, LLM, DNS, Roles"]
end

%% control plane
cli &lt;-.-&gt; fabric

%% deploy
cli --&gt; secrets
cli --&gt; cd
cd --&gt; runtime

%% observability
cli -.-&gt; logs

You write a standard Docker Compose file
Defang CLI validates your Compose project and uploads the project to storage in your AWS/GCP account
CD runs in your cloud — a deployment task spins up in your AWS/GCP account
Infrastructure is created — containers, DNS, load balancing, and roles are provisioned
Monitor the deployment and tail or query runtime logs with the Defang CLI

Your code and secrets never leave your cloud account. Defang orchestrates the deployment, but everything runs in your infrastructure.

Defang CLI

Deploying with Defang

If you already have a Docker Compose file, create a new stack and then deploy it. For example:

$ defang stack new
? Which cloud provider do you want to deploy to? AWS
? Which AWS region do you want to deploy to? us-west-2
? Which deployment mode do you want to use? AFFORDABLE
? What do you want to call this stack? awsuswest2
 * Created new stack configuration file: `.defang/awsuswest2`. Check this file into version control. You can now deploy this stack using `defang up --stack=awsuswest2`

$ defang up --stack=awsuswest2

Defang MCP Server

Claude Code Plugin

Install the Defang plugin for Claude Code to deploy directly from any Claude Code session — no CLI required upfront:

/plugin marketplace add DefangLabs/defang
/plugin install defang@defang-skills

After installing, use /defang:deploy to guide you through deploying your project. The Defang MCP server activates automatically once the Defang CLI is installed.

This repo includes:

Public releases of the Defang CLI; click here for the latest version
Built-in support for MCP Server — the Defang MCP Server makes cloud deployment as easy as a single prompt. Learn more
Samples that show how to deploy an app using the Defang Pulumi Provider.

Getting started

Read our Getting Started page
Follow the installation instructions from the Installing page
Take a look at our Samples in Golang, Python, and Node.js that show how to accomplish various tasks and deploy them
Try the AI integration by running defang generate
Start your new service with defang compose up

Installing

Install the Defang CLI from one of the following sources:

Using the Homebrew package manager DefangLabs/defang tap:
```
brew install DefangLabs/defang/defang
```

Using a shell script:

eval "$(curl -fsSL s.defang.io/install)"

Using Go:

go install github.com/DefangLabs/defang/src/cmd/cli@latest

Using the Nix package manager:
- with Nix-Env:
```
nix-env -if https://github.com/DefangLabs/defang/archive/main.tar.gz
```
- or with Flakes:
```
nix profile install github:DefangLabs/defang#defang-cli --refresh
```
Released tags are available from our Cachix binary cache, so you can download the CLI instead of compiling it. If you have Cachix installed, run cachix use defanglabs; otherwise add these lines to /etc/nix/nix.conf (or ~/.config/nix/nix.conf if you are a trusted user):
```
extra-substituters = https://defanglabs.cachix.org
extra-trusted-public-keys = defanglabs.cachix.org-1:mTXLTfYprWDrIK50Kz34fhOTreeKlQRZFQcKL7HtHx0=
```
Then install a tagged version, e.g. nix profile install github:DefangLabs/defang/v3.14.1#defang-cli. The cache holds x86_64-linux and aarch64-darwin builds. Other platforms, and builds from main, compile from source as before.
Using winget:
```
winget install defang
```

Using a PowerShell script:

iwr https://s.defang.io/defang_win_amd64.zip -OutFile defang.zip
Expand-Archive defang.zip . -Force

Using the official image from Docker Hub:

docker run -it defangio/defang-cli help

Using NPX:
```
npx defang@latest help
```
or download the latest binary of the Defang CLI.

Support

File any issues here

Command completion

The Defang CLI supports command completion for Bash, Zsh, Fish, and Powershell. To get the shell script for command completion, run the following command:

defang completion [bash|zsh|fish|powershell]

If you're using Bash, you can add the following to your ~/.bashrc file:

source &lt;(defang completion bash)

If you're using Zsh, you can add the following to your ~/.zshrc file:

source &lt;(defang completion zsh)

or pipe the output to a file called _defang in the directory with the completions.

If you're using Fish, you can add the following to your ~/.config/fish/config.fish file:

defang completion fish | source

If you're using Powershell, you can add the following to your $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 file:

Invoke-Expression -Command (defang completion powershell | Out-String)

Environment Variables

The Defang CLI recognizes the following environment variables:

COMPOSE_DISABLE_ENV_FILE - Whether to disable loading environment variables from a .env file in the current directory; defaults to false
COMPOSE_ENV_FILES - A comma-separated list of environment file(s) to use for interpolation instead of .env; overridden by the --env-file flag
COMPOSE_FILE - The Compose file(s) to use; defaults to compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml in the current directory
COMPOSE_PATH_SEPARATOR - The path separator to use for COMPOSE_FILE; defaults to : on Unix/MacOS and ; on Windows
COMPOSE_PROJECT_NAME - The name of the project to use; overrides the name in the Compose file
DEFANG_ACCESS_TOKEN - The access token to use for authentication; if not specified, uses token from defang login
DEFANG_ALLOW_UPGRADE - If set to true, allows upgrading the CD image and Pulumi version to the latest available; defaults to false, ie. previously deployed versions will be used to avoid unexpected upgrades
DEFANG_AWS_APN_ID - The AWS APN ID to use for attribution, eg. use pc:123456789abcdefgh for AWS Marketplace products
DEFANG_BUILD_CONTEXT_LIMIT - The maximum size of the build context when building container images; defaults to 100MiB
DEFANG_CD_BUCKET - The S3 bucket to use for the BYOC CD pipeline; defaults to defang-cd-bucket-…
DEFANG_CD_IMAGE - The image to use for the Continuous Deployment (CD) pipeline; defaults to public.ecr.aws/defang-io/cd:public-beta
DEFANG_DEBUG - set this to 1 or true to enable debug logging
DEFANG_DISABLE_ANALYTICS - If set to true, disables sending analytics to Defang; defaults to false
DEFANG_EDITOR - The editor to launch after new project generation; defaults to code (VS Code)
DEFANG_FABRIC - The address of the Defang Fabric to use; defaults to fabric-prod1.defang.dev
DEFANG_JSON - If set to true, outputs JSON instead of human-readable output; defaults to false
DEFANG_HIDE_HINTS - If set to true, hides hints in the CLI output; defaults to false
DEFANG_HIDE_UPDATE - If set to true, hides the update notification; defaults to false
DEFANG_ISSUER - The OAuth2 issuer to use for authentication; defaults to https://auth.defang.io
DEFANG_MODEL_ID - The model ID of the LLM to use for the generate/debug AI integration (Pro users only)
DEFANG_NO_CACHE - If set to true, disables pull-through caching of container images; defaults to false
DEFANG_PREFIX - The prefix to use for all BYOC resources; defaults to Defang
DEFANG_PROVIDER - The name of the cloud provider to use, auto (default), aws, azure, digitalocean, gcp, or defang
DEFANG_PULUMI_BACKEND - The Pulumi backend URL or "pulumi-cloud"; defaults to a self-hosted backend
DEFANG_PULUMI_DEBUG - If set to true, enables debug logging for Pulumi operations; defaults to false
DEFANG_PULUMI_DIFF - If set to true, shows the Pulumi diff during deployments; defaults to false
DEFANG_PULUMI_DIR - Run Pulumi from this folder, instead of spawning a cloud task; requires --debug (BYOC only)
DEFANG_PULUMI_VERSION - Override the version of the Pulumi image to use (aws provider only)
DEFANG_RECIPE - The deployment mode / recipe to use; defaults to AFFORDABLE
DEFANG_STACK - The name of the stack to use
DEFANG_SUFFIX - The suffix to use for all BYOC resources; defaults to the stack name, or beta if unset.
DEFANG_WORKSPACE - The workspace (name or ID) to use; preferred way to select which workspace the CLI uses
GCP_PROJECT_ID - The Google Cloud project ID for the gcp provider; must be a real shell environment variable (e.g. export GCP_PROJECT_ID=my-project-id), not set via defang config set. Also recognized: GOOGLE_PROJECT, GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, CLOUDSDK_CORE_PROJECT
NO_COLOR - If set to any value, disables color output; by default, color output is enabled depending on the terminal
PULUMI_ACCESS_TOKEN - The Pulumi access token to use for authentication to Pulumi Cloud; see DEFANG_PULUMI_BACKEND
PULUMI_CONFIG_PASSPHRASE - Passphrase used to generate a unique key for your stack, and configuration and encrypted state values
TZ - The timezone to use for log timestamps: an IANA TZ name like UTC or Europe/Amsterdam; defaults to Local
XDG_STATE_HOME - The directory to use for storing state; defaults to ~/.local/state

Compose interpolation

services:
  app:
    environment:
      PUBLISH_PROVIDER: "${DEFANG_PROVIDER}"
      PUBLISH_STACK: "${DEFANG_STACK}"

Development

At Defang we use the Nix package manager for our dev environment, in conjunction with DirEnv.

To get started quickly, install Nix and DirEnv, then create a .envrc file to automatically load the Defang developer environment:

echo use flake &gt;&gt; .envrc
direnv allow

Adding cloud support

At a high-level, support for a specific cloud lives in three repositories:

In this CLI repository
- an implementation of the client.Provider interface under the byoc package
- low-level cloud helpers ("driver") under the clouds package
  - authenticate with the cloud
  - start a CD container (task/job)
  - monitor the CD container's status and logs
  - stream/query logs from deployed services
  - set/list config (secrets/parameters)
In the Defang Pulumi Provider repository
- Pulumi component resources under the provider folder
  - Project component
  - Service component
  - Postgres component
  - Redis component
- a Pulumi custom resource for Build
- an implementation of the ConfigProvider interface to read config (secrets/parameters) at deploy time
In the Defang Docs repository
- under the providers section, documentation for how to set up credentials and permissions for the cloud, and any cloud-specific features

Defang DefangLabs

README

Develop Once, Deploy Anywhere.

How It Works

Defang CLI

Deploying with Defang

Defang MCP Server

Claude Code Plugin

This repo includes:

Getting started

Installing

Support

Command completion

Environment Variables

Compose interpolation

Development

Adding cloud support

Defang DefangLabs

README

Develop Once, Deploy Anywhere.

How It Works

Defang CLI

Deploying with Defang

Defang MCP Server

Claude Code Plugin

This repo includes:

Getting started

Installing

Support

Command completion

Environment Variables

Compose interpolation

Development

Adding cloud support