AI agents test better locally than humans can in the cloud

# LocalStack for AI Agents

You are an AI assistant helping a developer set up and use LocalStack — a
platform that emulates cloud services (AWS, Snowflake, Azure) locally, so they
can build and test cloud applications without connecting to real cloud providers
or incurring costs.

This document contains everything you need to get LocalStack running on the
user's machine and connect it to your tools. Work through the steps in order,
pausing when you need the user to complete an action in their browser.

---

## Prerequisites

Verify Docker is installed and running:

```bash
docker version
```

If Docker is not installed:

- **Interactive context:** direct the user to https://docs.docker.com/get-docker/
  and wait for them to confirm it is installed before continuing.
- **Headless context with no way to install Docker:** skip the local container
  and use a cloud-hosted ephemeral instance instead — see the **Headless setup**
  section below.

Choose one setup path before installing anything:

- **Interactive local container:** use this when Docker is available and the user can complete browser-based signup/login. Follow Steps 1–5 in order.
- **Headless or Docker-less setup:** use this when no human is available for browser login, or Docker cannot be installed. Follow Step 1 if Docker is available, skip Steps 2–4, follow the **Headless setup** section, then resume at Step 5.

Do not mix the paths. The interactive path obtains an auth token through login; the headless path requests a short-lived token.

---

## Step 1: Install lstk

`lstk` is LocalStack's CLI. It handles downloading the LocalStack container
image, authentication, and lifecycle management automatically.

**macOS / Linux (Homebrew — recommended):**
```bash
brew install localstack/tap/lstk
```

**Any platform (npm):**

If Homebrew is not available and you use npm instead, verify Node.js and npm are installed first:

```bash
node --version
npm --version
```

```bash
npm install -g @localstack/lstk
```

Verify the installation succeeded:

```bash
lstk --version
```

---

## Step 2: Create a LocalStack account

Continue here only if you chose the **interactive local container** path. If you chose the headless or Docker-less path, stop here, go to **Headless setup**, and resume at Step 5 when that section tells you to.

LocalStack requires an account. Tell the user:

> "LocalStack requires a free account. Please sign up at
> https://www.localstack.cloud/pricing, then let me know when you're done."

Wait for the user to confirm before continuing.

---

## Step 3: Authenticate

```bash
lstk login
```

This opens a browser window. Tell the user to complete the login flow, then
confirm when done before you proceed.

---

## Step 4: Start LocalStack

```bash
lstk start
```

This downloads the LocalStack Docker image on first run (may take a few
minutes) and starts the emulator. Wait for the output to confirm LocalStack
is ready before continuing.

Useful lifecycle commands for later:

| Command           | Purpose                        |
|-------------------|--------------------------------|
| `lstk stop`       | Stop LocalStack                |
| `lstk status`     | Check if LocalStack is running |
| `lstk logs --follow` | Stream logs in real time    |

---

## Headless setup (alternative to Steps 2–4)

Use this path **only** when no human is available to create an account or
complete a browser login (CI, an autonomous agent, etc.). It requests a
short-lived token and starts either a Docker-backed local emulator with `lstk`
or a cloud-hosted ephemeral instance.

> Do **not** run Step 4 separately — this path starts LocalStack itself.
> Running both starts two emulators that collide on port 4566.

This path needs `curl` and `jq`. Verify they are available:

```bash
curl --version
jq --version
```

If `jq` is missing, install it with the user's package manager (for example,
`brew install jq` on macOS or `sudo apt-get install -y jq` on Debian/Ubuntu).

If no `LOCALSTACK_AUTH_TOKEN` is already configured, request a short-lived token:

```bash
RESP=$(curl -s -X POST https://v2.api.localstack.cloud/v1/auth/agent-token)
export LOCALSTACK_AUTH_TOKEN=$(echo $RESP | jq -r .token)
export API_ENDPOINT=$(echo $RESP | jq -r .api_endpoint)
```

Verify both values were returned before continuing:

```bash
test -n "$LOCALSTACK_AUTH_TOKEN" && test "$LOCALSTACK_AUTH_TOKEN" != "null"
test -n "$API_ENDPOINT" && test "$API_ENDPOINT" != "null"
```

Each token request returns a unique `api_endpoint` that identifies the agent
session. If `LOCALSTACK_AUTH_TOKEN` was already configured but `API_ENDPOINT` is
empty, request a fresh short-lived token so both values are available. If either
verification command fails, stop and request a new token before choosing a
runtime.

Now choose exactly one runtime:

**Docker available:** make sure `lstk` is installed (Step 1), then start a
local container and wait for LocalStack to report ready.

```bash
export LOCALSTACK_API_ENDPOINT=$API_ENDPOINT
lstk start --non-interactive
```

`lstk` uses `LOCALSTACK_AUTH_TOKEN` directly, so no `lstk login` is needed. It
forwards `LOCALSTACK_*` variables to the container, where
`LOCALSTACK_API_ENDPOINT` becomes `API_ENDPOINT` for the emulator's license
check. Do not set `LSTK_API_ENDPOINT` — `lstk`'s own license check must use its
default platform endpoint.

**No Docker available:** do not run `lstk start`. `lstk` does not manage
ephemeral instances, so this runtime uses the `localstack` Python CLI, which
needs Python 3.8+ and `pip`:

```bash
python3 --version
pip --version
pip install localstack
```

Create a cloud-hosted ephemeral instance (`API_ENDPOINT` from the token request
above must still be exported in the shell):

```bash
localstack ephemeral create --name agent-$(date +%s)
```

This returns an endpoint URL; set it as `AWS_ENDPOINT_URL` to interact with it:

```bash
export AWS_ENDPOINT_URL=<endpoint-url>
```

Ephemeral tokens are short-lived; for persistent use, switch to the interactive
path and a regular account.

Once LocalStack reports ready (or the ephemeral instance is created), continue
to **Step 5**.

---

## Step 5: Configure the MCP server

The LocalStack MCP server gives AI agents direct access to AWS service
operations, log analysis, IAM policy generation, infrastructure deployment,
chaos injection, and more.

**Get the auth token:**

The MCP server runs as a separate process and needs its own
`LOCALSTACK_AUTH_TOKEN` — it does not inherit the credentials from `lstk login`.

- If `LOCALSTACK_AUTH_TOKEN` is already set in the environment (for example,
  from the headless path above), reuse that value and skip the request below.
- Otherwise, ask the user for it:

> "Please copy your auth token from
> https://app.localstack.cloud/workspace/auth-token
> and share it with me so I can configure the MCP server."

Wait for the user to provide the token.

**Add this to your MCP client's configuration file**
(e.g. Claude Desktop config, `~/.cursor/mcp.json`, or your agent's MCP
settings file):

First verify Node.js and `npx` are available. The MCP server package requires
Node.js 20+; Node.js 22+ is recommended.

```bash
node --version
npx --version
```

If Node.js or `npx` is missing, ask the user to install Node.js before
continuing.

```json
{
  "mcpServers": {
    "localstack-mcp-server": {
      "command": "npx",
      "args": ["-y", "@localstack/localstack-mcp-server"],
      "env": {
        "LOCALSTACK_AUTH_TOKEN": "<paste-auth-token-here>"
      }
    }
  }
}
```

Replace `<paste-auth-token-here>` with the token the user provided.

If you created a cloud-hosted ephemeral instance and set `AWS_ENDPOINT_URL`, the
MCP server `env` block should include both values:

```json
"env": {
  "LOCALSTACK_AUTH_TOKEN": "<paste-auth-token-here>",
  "AWS_ENDPOINT_URL": "<endpoint-url>"
}
```

After saving the config, restart your MCP client for the server to load.

---

## Available MCP tools

Once the MCP server is configured and loaded, you have access to:

- **localstack-management** — start, stop, restart, and check LocalStack status
- **localstack-deployer** — deploy CDK, Terraform, and SAM infrastructure stacks
- **localstack-logs-analysis** — analyze logs for errors, warnings, and performance issues
- **localstack-iam-policy-analyzer** — generate least-privilege IAM policies from violations
- **localstack-chaos-injector** — inject faults and failures to test system resilience
- **localstack-cloud-pods** — save and restore LocalStack state snapshots
- **localstack-state-management** — export, import, and reset local file-based state
- **localstack-extensions** — manage LocalStack marketplace extensions
- **localstack-ephemeral-instances** — create temporary cloud-hosted LocalStack instances
- **localstack-aws-client** — execute AWS CLI commands directly against LocalStack
- **localstack-aws-replicator** — replicate external AWS resources into LocalStack
- **localstack-app-inspector** — inspect application traces, spans, events, and IAM evaluations
- **localstack-snowflake-client** — execute Snowflake SQL queries and commands against LocalStack
- **localstack-docs** — search LocalStack documentation

---

## Available skills

LocalStack provides six AI skills for common workflows. They can be installed
from https://github.com/localstack/skills:

- **localstack-lifecycle** — manage the LocalStack container (start, stop, status, restart)
- **iac-deployment** — deploy infrastructure using Terraform, CDK, CloudFormation, or Pulumi
- **state-management** — save and restore environment state with Cloud Pods
- **logs-analysis** — examine and troubleshoot LocalStack logs
- **iam-policy-analyzer** — analyze and auto-generate least-privilege IAM policies
- **localstack-extensions** — manage LocalStack extensions and plugins

---

## What to try next

Once LocalStack is running, suggest one of these to get started:

- If the AWS CLI is installed, create an S3 bucket against the active endpoint:
  `aws --endpoint-url=${AWS_ENDPOINT_URL:-http://localhost:4566} s3 mb s3://my-bucket`
- For a local container (interactive or headless), check the emulator and deployed resources: `lstk status`
- Deploy an existing Terraform or CDK project using the iac-deployment skill
- Use the logs-analysis skill to investigate any issues

---

## Resources

- Documentation: https://docs.localstack.cloud
- lstk CLI docs: https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/
- MCP server: https://github.com/localstack/localstack-mcp-server
- Skills: https://github.com/localstack/skills
- Dashboard: https://app.localstack.cloud
- Support: https://docs.localstack.cloud/getting-started/help-and-support/