Saving to Cloud Pods

In the previous section you learned how to save a snapshot of the emulator’s state to a local file, then to re-load the snapshot into a different emulator instance. When working in a team environment, it’s important to have a standard mechanism for sharing snapshot files amongst your team, and for managing updates as new versions are published.

LocalStack provides the web-based Cloud Pods repository for exactly this purpose, accessible only to the users in your organization. Snapshots can be generated by an emulator instance, then automatically published to your Cloud Pods repository. From there, snapshots can be loaded back into an emulator instance, either on a desktop environment or a CI environment.

Each organization has its own private Cloud Pods repository, securely managed in LocalStack’s cloud. These are backed by dedicated, isolated Amazon S3 buckets. The LocalStack CLI utilizes secure S3 presigned URLs to directly interface with the S3 bucket, bypassing the need to transmit the snapshot files through LocalStack’s Platform APIs.

Using the lstk CLI

You can save and load the snapshots to or from your Cloud Pods repository using the lstk snapshot command.

lstk snapshot --help

Manage emulator snapshots

Usage: lstk snapshot [flags]

Commands:
  list        List Cloud Pod snapshots available on the LocalStack platform
  load        Load a snapshot into the running emulator
  remove      Delete a cloud snapshot from the LocalStack platform
  save        Save a snapshot of the emulator state
  show        Show metadata for a cloud snapshot

Saving a snapshot to Cloud Pods

The command for saving a snapshot to Cloud Pods is similar to saving locally, but instead of a file name, provide the pod: prefix followed by a valid Cloud Pod name.

lstk snapshot save pod:sample-application

✔︎ Snapshot saved to pod:sample-application
• Version: 1
• Services: sqs, sns, cloudwatch, cloudcontrol, s3, sts
• Size: 127.0 KB

You can access the list of available Cloud Pods for both you and your organization by using the list command:

lstk snapshot list

~ 3 snapshots

  NAME                VERSION  LAST CHANGED
  snapshot1           1        2026-07-20 20:02 UTC
  sample-application  1        2026-07-23 23:47 UTC
  snapshot2           1        2026-07-20 20:04 UTC

With the save command you can create multiple versions of a Cloud Pod. For instance, let us create a SQS queue and second version of sample-application.

lstk aws sqs create-queue --queue-name test-queue
lstk snapshot save pod:sample-application

✔︎ Snapshot saved to pod:sample-application
• Version: 2
• Services: sqs, sns, cloudwatch, cloudcontrol, s3, sts
• Size: 130.9 KB

Note

Permissions on Cloud Pods are assigned at organization level. This means that every individual in the organization can view, load, and delete snapshots created by other team members. Similarly, everyone can save a new version on top of a snapshot originally created by someone else.

Loading snapshots from a Cloud Pod

To load a snapshot from a Cloud Pod into a running emulator, use the lstk snapshot load command:

lstk snapshot load pod:sample-application

✔︎ Snapshot loaded from pod:sample-application
• Services: sts, s3, sqs, cloudwatch, cloudcontrol, sns

You can examine the loaded resources with the lstk status command:

lstk status

✔︎ LocalStack AWS Emulator is running
• Endpoint: localhost.localstack.cloud:4566
• Container: localstack-aws-dev
• Version: 2026.7.0
• Uptime: 25m 46s

~ 6 resources · 3 services

  SERVICE  RESOURCE                                                                        REGION          ACCOUNT
  S3       bucket1                                                                         global          000000000000
  SNS      topic1                                                                          us-east-1       000000000000
  SNS      topic2                                                                          ap-southeast-2  000000000000
  SQS      http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2  ap-southeast-2  000000000000
  SQS      http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1       us-east-1       000000000000
  SQS      http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/test-queue    us-east-1       000000000000

Comprehensive instructions on using the lstk snapshot CLI command are found in the lstk CLI Guide.

Note

The snapshots stored in a Cloud Pod may not remain compatible if used with a different version of LocalStack. LocalStack applies snapshot compatibility rules to block loading snapshots known to be incompatible with the running LocalStack version.

Using the LocalStack Console

The LocalStack Console enables you to:

• Browse your Cloud Pods and access your snapshot version history.
• Save and load snapshots to and from Cloud Pods.
• View snapshot metadata, resources, regions, and version history.

Browse Cloud Pods

The Cloud Pods Browser allows you to view, manage, and explore your snapshots through the LocalStack Console. With Cloud Pods, you can have individual or shared ownership of a snapshot of your LocalStack instance.

The Cloud Pods Browser provides the following functionalities:

• View Cloud Pods: View all snapshots saved by you or your organization.
• View Versions: View the version history of a snapshot and access previous snapshots by clicking on the Cloud Pod’s name.
• View Snapshot Details: View the details of a specific snapshot version by clicking on the version.
• View Cloud Pod storage: View the organization storage usage and user storage usage on top of the Cloud Pods Browser.
• Delete Snapshot: Delete a snapshot by selecting the snapshot and navigating to the Actions button, followed by Delete.

View snapshot metadata

You can view snapshot metadata by selecting any snapshot in the Cloud Pods Browser. The metadata includes details such as:

• The user who created the snapshot
• The creation timestamp
• The LocalStack version used to create the snapshot
• The size of the snapshot
• The service resources contained in the snapshot

You can view detailed information within a snapshot, including available resources, categorized services with configurations, and quick access to resource identifiers and endpoints—all without loading the snapshot into your LocalStack runtime.

To save metadata with resource details in the Cloud Pod, ensure your LocalStack container is running and save the snapshot with ENABLE_POD_RESOURCES=1. Snapshots saved without this configuration enabled will not display granular details.

Save and load snapshots to or from Cloud Pods

You can save and load your LocalStack infrastructure state as a snapshot to or from a Cloud Pod using the LocalStack Console. This feature is particularly useful when you need to use a user-friendly interface to manage your snapshots, without the need to interact with the CLI.

Save the snapshot

To save a snapshot, follow these steps:

1. Navigate to the Cloud Pod tab within the Export/Import State page.
2. Create AWS resources locally as needed.
3. Enter the Cloud Pod name and toggle between the New Pod and Existing Pod options.
4. Enter the services to save resources for. By default, all available service resources are saved.
5. Click on Create New Pod.

A new Cloud Pod will be created and the snapshot will be available for loading into another LocalStack instance. You can check out the list of available Cloud Pods in the Cloud Pods page.

Load the snapshot

To load a snapshot, follow these steps:

1. Navigate to the Cloud Pod tab within the Export/Import State page.
2. Choose the Cloud Pod from the drop-down list.
3. Click on Load State From Pod.

To confirm the successful injection of the container state, visit the respective Resource Browser for the services and verify the resources.

Auto Loading from Cloud Pods

In addition to loading snapshots through the Command-Line Interface (CLI) or the Console, you can configure the automatic loading of one or more Cloud Pods upon the startup of the LocalStack container.

Environment variables

To automatically load a Cloud Pod at startup, utilize the AUTO_LOAD_POD configuration variable.

AUTO_LOAD_POD can accept multiple Cloud Pod names separated by commas. To autoload multiple Cloud Pods, such as foo-pod and bar-pod, use: AUTO_LOAD_POD=foo-pod,bar-pod. The order of Cloud Pods in AUTO_LOAD_POD dictates their loading sequence. When autoloading multiple Cloud Pods, later pods might overwrite the state of earlier ones if they share the same service, account, and region.

LocalStack CLI

AUTO_LOAD_POD=foo-pod localstack start

Docker Compose

services:
  localstack:
    container_name: "localstack-main"
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4510-4559:4510-4559"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
      - DEBUG=1
      - AUTO_LOAD_POD=foo-pod,bar-pod
    volumes:
      - "./volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Docker

docker run \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  -e AUTO_LOAD_POD=foo-pod \
  -v ./volume:/var/lib/localstack \
  -p 4566:4566 \
  localstack/localstack-pro

Configuration file

LocalStack allows for the use of configuration files to automatically load Cloud Pods during startup.

Within the container, LocalStack searches through the /etc/localstack/init-pods.d directory for two file types: zip files created using the localstack state export command, and txt files, where each line represents the name of a Cloud Pod.

Take the following example of a project layout:

• docker-compose.yml
• Directoryinit-pods.d

  • pod-list.txt
  • my-state.pod.zip

The pod-list.txt contains the following:

foo-pod
bar-pod

LocalStack, upon mounting init-pods.d to the appropriate location, will sequentially load foo-pod and bar-pod as listed in pod-list.txt, and then proceed to load my-state.pod.zip.

The docker compose file for correctly mounting init-pods.d will look like:

services:
  localstack:
    container_name: "localstack-main"
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4510-4559:4510-4559"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
      - DEBUG=1
    volumes:
      - "./volume:/var/lib/localstack"
      - "./init-pods.d:/etc/localstack/init-pods.d"

End-to-End Encryption Enterprise

Cloud Pods’ artifacts are stored in S3 buckets when using the LocalStack platform as the storage remote. By default, Amazon S3 encrypts all objects before saving them on disks, while the opposite operation happens at download time. This ensures encryption at rest for Cloud Pods.

When this is not enough, LocalStack also offers end-to-end encryption for enterprise customers as a preview feature. To activate this feature, make sure to start LocalStack with the POD_ENCRYPTION environment variable set to 1.

The next step is to generate a passphrase used to encrypt and decrypt the Cloud Pods’ artifacts. We advise creating a strong passphrase by using the openssl utility, e.g.:

openssl rand --base64 32
# 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Users should treat the generated passphrase as a secret and they are responsible for securely sharing it within the organization. The generated secret can now be provided as an option to the save command when creating an encrypted Cloud Pod.

localstack pod save my-secret-pod --secret 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Loading an encrypted Cloud Pod would require a similar load command:

localstack pod load my-secret-pod --secret 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Encryption with PGP keys

We also offer the option of using PGP keys to encrypt and decrypt Cloud Pods. The process is the following:

• Customers would have to export both their private and public keys into two files, private.pgp and public.pgp respectively.
• These files need to be mounted in a specific pods.keys.d folder when starting LocalStack, i.e., localstack start -v $PWD/pods.keys.d:/etc/localstack/pods.keys.d.
• The secret option passed to the save and load commands corresponds to the passphrase needed to import the private key into the LocalStack runtime.

Limitations

• Both browsing the Cloud Pod content via the UI and loading Cloud Pods into ephemeral instances are currently not supported for encrypted Cloud Pods.
• It is not possible to have both encrypted and non-encrypted versions for a Cloud Pod. Encryption is set at the moment of the creation and it cannot be changed.

Troubleshooting

Unable to obtain Auth Token

When you try to save a Cloud Pod and see the error in LocalStack logs like this:

localstack.cli.exceptions.CLIError: Failed to create Cloud Pod sample-pod ❌ - Unable to obtain auth token (code 401) - please log in again.

It would be good to check if you have outdated authentication credentials (bearer token from a previous LocalStack login) in the remotes.yaml file for cloud pods. You have two options to fix this:

1. Run another localstack auth login command.
2. Find the remotes.yaml file in the <localstack_volume> directory on your machine and delete the file, or at least remove the "default" entry from it.

Additionally, if there is a ~/.localstack/auth.json file in your home directory, delete it as well if it still exists.

License not found

When you try to save a Cloud Pod and see the license.not_found error in LocalStack logs like this:

lsmulti-localstack  | 2024-03-15T13:06:16.358  WARN --- [functhread31] l.p.remotes.remotes        : Failed to register pod sample-pod: {"error": true, "message": "licensing.license.not_found"}

To fix this, clear the LocalStack cache directory and restart the LocalStack instance before trying to save the Cloud Pod again. You can find the cache directories at:

• /Users/localstack/Library/Caches/localstack
• /Users/localstack/Library/Caches/localstack-cli

Adjust the path based on your operating system.

SSL Certificate verification failed

If you get an SSL certificate verification error while trying to save a Cloud Pod, as shown below:

An error occurred while checking remote management for pod "cloud-pod-product-app": "MyHTTPSConnectionPool(host='api.localstack.cloud', port=443): Max retries exceeded with url: /v1/cloudpods/cloud-pod-product-app (Caused by SSLError(SSLCertVerificationError(1, "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'api.localstack.cloud'. (_ssl.c:1006)")))"

Check if your machine’s clock is set incorrectly or if the certificate store is outdated. This error can also occur if you use localstack as LOCALSTACK_HOST. In this case, the DNS incorrectly resolves api.localstack.cloud to localhost, causing a certificate mismatch.

InvalidAccessKeyId during CreateBucket API call

You may see this error:

An error occurred (InvalidAccessKeyId) when calling the CreateBucket operation: The AWS Access Key Id you provided does not exist in our records.

This usually means you’re using temporary AWS credentials, but AWS_SESSION_TOKEN is missing from the environment.

To fix this, ensure that you export the AWS_SESSION_TOKEN environment variable:

export AWS_SESSION_TOKEN=...

Then, add session_token to the pod remote add URL:

localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}&session_token={session_token}'

If you’re still unable to connect to the S3 bucket, add the bucket hostname to the upstream DNS resolution list:

DNS_NAME_PATTERNS_TO_RESOLVE_UPSTREAM=ls-pods-bucket-test.s3.amazonaws.com/

For more details, see the Skip LocalStack DNS Resolution section.