---
title: Get Started
url: /docs/esc/get-started/
---
Pulumi ESC (Environments, Secrets, and Configuration) is a centralized secrets and configuration management service. In this quick start, you'll create your first environment, store a secret, and retrieve it programmatically.

## Prerequisites

1. **Create a Pulumi account** at [app.pulumi.com](https://app.pulumi.com/signup)
1. **Install the ESC CLI**

<!-- chooser: os -->

<!-- option: macos -->
```bash
brew update && brew install pulumi/tap/esc

```

<!-- /option -->

<!-- option: linux -->
```bash
curl -fsSL https://get.pulumi.com/esc/install.sh | sh

```

<!-- /option -->

<!-- option: windows -->

<h3 class="no-anchor pt-4">
<svg xmlns="http://www.w3.org/2000/svg" class="ph-icon ph-icon--regular pr-2" fill="currentColor" aria-hidden="true" focusable="false"><use href="/icons/sprite.70fd70d1a833861af10bfc0def62d9dd4208a71e6b1f81581da2b8c9f48cda97.svg#p-download-simple-regular"/></svg>
Windows binary download</h3>

[amd64](https://get.pulumi.com/esc/releases/esc-v0.23.0-windows-x64.zip)

<!-- /option -->

<!-- /chooser -->

See the [ESC installation docs](/docs/install/esc/) for more options.

## Create your first environment

1. **Log in** to the ESC CLI:

```bash
esc login
```

You'll be prompted to log in via your browser or with an access token. Follow the instructions to authenticate.

1. **Create an environment** in the Pulumi Cloud console:
  
1. Open [Pulumi Cloud](https://app.pulumi.com/signin) and log in
1. Select **Environments** in the left navigation
1. Select **+ Create Environment**
1. Choose **New Environment**
1. For **Project name**, enter: `my-project`
1. For **Environment name**, enter: `dev`
1. Select **Create Environment**

![Create Environment dialog in Pulumi Cloud showing fields for project name (my-project) and environment name (dev)](./images/esc-create-environment.png)

Your environment is now created and ready to store configuration and secrets.

## Store configuration and secrets

Add both plaintext configuration and encrypted secrets to your environment:

1. In the **Environment definition** editor, erase the contents and replace them with the following YAML:

```yaml
    values:
      region: us-west-2
      apiKey:
        fn::secret: demo-secret-123
    ```

This defines two values: `region` (a plaintext value) and `apiKey` (a secret value, denoted with `fn::secret`).

![ESC environment editor showing YAML definition with region and apiKey values before saving](./images/esc-env-edit-pre-save.png)

1. Select **Save**

Watch what happens: ESC automatically encrypts the secret value. The plaintext `demo-secret-123` is replaced with an encrypted value.

![ESC environment editor showing encrypted secret value and preview displayed as [secret] after saving](./images/esc-env-edit-post-save.png)

## Retrieve your configuration and secrets

Open your environment to retrieve all values, including decrypted secrets:

```bash
esc env open my-project/dev
```

You should see output like:

```json
{
  "apiKey": "demo-secret-123",
  "region": "us-west-2"
}
```

You've created an environment, stored configuration and secrets, and retrieved them interactively with the CLI. Notice that the secret is automatically decrypted when you open the environment.

## What's next?

### Core workflows

Now that you've created your first environment, explore these essential guides:

- **[Integrate with Pulumi IaC](/docs/esc/guides/integrate-with-pulumi-iac/)** - Use ESC environments in your infrastructure code to centralize secrets across all stacks
- **[Managing secrets](/docs/esc/guides/managing-secrets/)** - Store, organize, and retrieve secrets using the CLI and console
- **[Running commands with esc run](/docs/esc/guides/running-commands-with-esc/)** - Inject secrets into any command or script as environment variables
- **[Importing environments](/docs/esc/guides/importing-environments/)** - Compose environments to share configuration across teams and projects
- **[Dynamic login credentials](/docs/esc/integrations/dynamic-login-credentials/)** - Generate short-lived cloud credentials using OIDC with AWS, Azure, GCP, and more

New to Pulumi IaC? Start with the [Pulumi IaC Get Started guide](/docs/get-started/) first.

### Advanced capabilities

Extend ESC with external secret providers and advanced OIDC configuration:

- **[Dynamic secrets](/docs/esc/integrations/dynamic-secrets/)** - Pull secrets from external providers like AWS Secrets Manager, Azure Key Vault, and 1Password
- **[Configuring OIDC](/docs/esc/guides/configuring-oidc/)** - Deep dive into OpenID Connect configuration and trust relationships

### Learn the fundamentals

- **[Concepts](/docs/esc/concepts/)** - Understand how ESC works under the hood