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

# State

> How Pulumi state works in ubx and available state backends.

ubx uses Pulumi's state system to track which cloud resources exist and their current configuration. State is stored in a backend — locally by default.

## Default: Local State

```yaml theme={null}
# ubx.yaml
backend: file://.ubx/state
```

State is stored in `.ubx/state/`. Add `.ubx/` to your `.gitignore`.

## Remote State Backends

For team environments, use a remote backend:

```yaml theme={null}
# AWS S3
backend: s3://my-bucket/ubx-state

# Azure Blob Storage
backend: azblob://my-container/ubx-state

# GCP Cloud Storage
backend: gs://my-bucket/ubx-state

# Pulumi Cloud
backend: https://api.pulumi.com
```

## State Commands

```bash theme={null}
ubx state list                              # list all resources in state
ubx state show unit.aws_s3_bucket_v2.assets # show resource details
ubx state rm unit.aws_s3_bucket_v2.assets   # remove from state (not cloud)
ubx state mv old_name new_name             # rename in state
```

Prefer the [`moved`](/v1/language/moved) block for renames — it's declarative and version-controlled.

## Refreshing State

```bash theme={null}
ubx refresh    # sync state with actual cloud
```

Run this after manual changes to cloud resources outside of ubx, or before `ubx plan` to detect drift.

## State Locking

When using remote backends, Pulumi automatically locks state during operations to prevent concurrent modifications.

## Stacks and Environments

Each environment (`--env prod`, `--env staging`) gets its own Pulumi stack and state file. They are completely isolated.