MiniStack とは｜MIT・無料のAWSローカルエミュレータをLocalStack代替に使う

LocalStackがBusiness Source License（BSL）に移行してコアサービスを有料プランの裏側に移したことで、「完全無料でMITの代替」を求める動きが広がった。ministackorg/ministack はその需要に直球で応えるOSSで、Python製、60+のAWSサービスを単一ポート4566でエミュレートする。最新リリースは v1.4.1（2026-07-09）で、v1.4.0ではリージョン／アカウント単位でstateを分離し、BedrockもOllama・llama.cpp経由の実LLMプロキシに対応した。

この記事ではMiniStackのAWSローカル開発活用法を解説します。AI時代の自動化ツール全体像はAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方をご覧ください。

MiniStackとは：LocalStackの無料・軽量な代替

pip install ministack か docker run ですぐ起動する。一言で言えば、AWSを丸ごとローカルに立て、開発とCIのAWS課金・待ち時間・事故リスクを消し、有償化したLocalStackを無料で置き換えるものだ。README冒頭も「LocalStack recently moved its core services behind a paid plan.」と、この文脈を正面から掲げている。

READMEは末尾で「MIT — free to use, modify, and distribute. No restrictions.」と言い切っている。商用での再販も含めて自由で、ライセンス変更に振り回された層への強いメッセージになっている。

実コンテナを起動する設計と、対応する60+サービス

MiniStackが解くのは「APIモックだけでは本番と乖離する」問題だ。

ほかにECSは RunTask で実Dockerコンテナを起動し、LambdaはPython/Node.jsハンドラをwarm worker poolで実行する。RDSを作ると裏で本物のPostgresが立ち上がり、実際の host:port（既定で localhost:15432 起点）が返ってくる。対応エンジンは postgres / mysql / mariadb / aurora-postgresql / aurora-mysql。

# RDSをcreateすると、実Postgresコンテナが裏で起動する
import boto3, psycopg2
rds = boto3.client("rds", endpoint_url="http://localhost:4566",
                   aws_access_key_id="test", aws_secret_access_key="test",
                   region_name="us-east-1")
resp = rds.create_db_instance(
    DBInstanceIdentifier="mydb", DBInstanceClass="db.t3.micro",
    Engine="postgres", MasterUsername="admin",
    MasterUserPassword="password", DBName="appdb", AllocatedStorage=20)

ep = resp["DBInstance"]["Endpoint"]         # {"Address": "localhost", "Port": 15432}
conn = psycopg2.connect(host=ep["Address"], port=ep["Port"],
                        user="admin", password="password", dbname="appdb")
# ↑ 本物のPostgresに接続でき、実際のSQLが通る

LocalStack無料版ではSQLが実際に通るかを確かめられなかったが、MiniStackならローカル・CI・本番Postgresの3層で同じSQLが通る。

60+はLocalStackの70+より少ないが、Lambdaの provided.al2023 ランタイムやDurable Functions、API GatewayのWebSocket APIやJWTオーソライザまで対応し、個別サービスの機能深度は高い。Direct ConnectやMainframe Modernizationのような特殊サービスは対象外だ。

軽さの根源は、全サービスを単一Pythonプロセスで動かす設計にある。ゲートウェイ（:4566）がサービスルーターに渡し、RDSやLambdaなど一部だけがDocker API経由で実コンテナに委譲する。各サービスは ministack/services/<service_name>.py という独立したファイルで、READMEのContributingは「async def handle_request(...) と reset() を持つ1ファイルを作り、SERVICE_REGISTRY に追加し、ルーターに検出パターンを足す」だけと明記している。2026年4月ローンチのS3 Filesが同月中に取り込まれたのも、この設計あってのことだ。

MiniStackのインストールとdocker-compose統合

# pip（PoC・個人開発）。GATEWAY_PORT=XXXX でポート変更可
pip install ministack
ministack

# Docker（チーム・CI）
docker run -p 4566:4566 ministackorg/ministack

# 起動確認とAWS CLIからの接続（認証情報は test でよい）
curl http://localhost:4566/_ministack/health
export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:4566 s3 ls

実コンテナ機能を使うにはDockerソケットをマウントする。DuckDBによるAthenaの実SQLは :full イメージ（Debian/glibcベース、約360MB）でのみ有効で、light版（約110MB）では SELECT 1+1 がモック結果を返す。

# 本格運用：実コンテナ + full image
docker run -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ministackorg/ministack:full

チームの共通環境にするなら docker-compose.yml に組み込む。

services:
  ministack:
    image: ministackorg/ministack:latest
    container_name: ministack
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ministack-data:/data
    environment:
      - PERSIST_STATE=1
      - STATE_DIR=/data/ministack-state
      - LAMBDA_EXECUTOR=docker
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4566/_ministack/health"]
      interval: 5s
      timeout: 3s
      retries: 30

  app:
    build: .
    depends_on:
      ministack:
        condition: service_healthy
    environment:
      - AWS_ENDPOINT_URL=http://ministack:4566
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
      - AWS_REGION=us-east-1
    command: ["npm", "start"]

volumes:
  ministack-data:

PERSIST_STATE=1 でコンテナを再起動してもデータが残る。全サービス対応で、書き込みは「tmpに書いてrename」のアトミック方式なのでクラッシュ時の破損を防ぐ。CIで毎回まっさらにしたいときは、PERSIST_STATE を切るか POST /_ministack/reset を beforeEach で叩く。

Terraform・CI/CDへの組み込み

AWS_ENDPOINT_URL を設定するか、Terraformの endpoints ブロックをMiniStackに向けるだけで、既存のIaCがほぼそのまま動く。CloudFormation（SAMトランスフォーム含む・full image）、CDK、Pulumiも同様に通る。

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    rds      = "http://localhost:4566"
    lambda   = "http://localhost:4566"
    # ... 必要なサービス分
  }
}

resource "aws_db_instance" "test" {
  identifier        = "test-db"
  engine            = "postgres"
  instance_class    = "db.t3.micro"
  allocated_storage = 20
  username          = "admin"
  password          = "password"
}

terraform apply するとRDSインスタンスが作られ、裏で実Postgresコンテナが起動して、接続できるエンドポイントが返ってくる。

起動が数秒以内なので、PRごとに何度もテストを回せる。

# .github/workflows/test.yml
name: Test against MiniStack
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      ministack:
        image: ministackorg/ministack:latest
        ports:
          - 4566:4566
        options: >-
          --health-cmd "curl -f http://localhost:4566/_ministack/health"
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10

    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3

      - name: Apply infrastructure
        run: |
          terraform init
          terraform apply -auto-approve
        env:
          AWS_ENDPOINT_URL: http://localhost:4566
          AWS_ACCESS_KEY_ID: test
          AWS_SECRET_ACCESS_KEY: test
          AWS_REGION: us-east-1

      - name: Run integration tests
        run: pytest tests/integration/
        env:
          AWS_ENDPOINT_URL: http://localhost:4566

LocalStack向けのワークフローは、localstack/localstack を ministackorg/ministack に書き換えるだけで大半が動く。ヘルスチェックも /_localstack/health と /health が互換提供されている。

LocalStack・kumo・Vercel Emulateとの使い分け

kumoはLocalStackの重さを解くGo製バイナリのドロップイン代替、Vercel EmulateはSlack・GitHub・GoogleまでをDocker不要で扱うJS/TS向けのモック、MiniStackは「本物のPostgresがないとSQLが通るか確かめられない」不満に応える実コンテナ型だ。本番に近い実DBやEKS/ECSの動作確認ならMiniStack、Goプロジェクトや依存ゼロを求めるならkumo、ユニットテストやAWS以外のSaaSならVercel Emulate、Snapshotなど厳密互換のPro機能が要るならLocalStack Pro、という棲み分けになる。

マルチテナンシー・StackPort・AIエージェントでの使い方

12桁のAccess Key IDが、そのまま12桁のAccount IDになる。設定は要らない。

# Team A → account 111111111111
export AWS_ACCESS_KEY_ID=111111111111
aws --endpoint-url http://localhost:4566 sts get-caller-identity
# → { "Account": "111111111111", ... }

# Team B → account 222222222222（別ターミナル）
export AWS_ACCESS_KEY_ID=222222222222
aws --endpoint-url http://localhost:4566 sts get-caller-identity
# → { "Account": "222222222222", ... }

ARNとリソース状態（SQS・Lambda・IAM・S3・DynamoDB等）がアカウント単位で分離され、同名リソースも衝突しない。test のような非数値キーは既定の 000000000000 に落ちる。1つのインスタンスを複数の開発者やCIで共有しつつ、クロスアカウントロールや組織の権限テストをローカルで回せる。

コミュニティ製の StackPort（README公認の Community Integrations）は、MiniStack上のリソースをAWSコンソール風のUIで見せるダッシュボードだ。pip install stackport && stackport で、S3のオブジェクト、DynamoDBのデータ、Lambda関数、IAMユーザー/ロールをブラウザから確認できる。.NET Aspire向けには McDoit.Aspire.Hosting.Ministack もある。

Claude Code・Codex・Gemini CLIにAWSリソースの作成を任せると、エージェントは何度もインフラを作っては壊す。本番AWSでこれを許すとコストと事故の両面でリスクがあるが、MiniStackに向けておけば何度作り直しても課金も本番影響もない。AWS_ENDPOINT_URL=http://localhost:4566 で terraform apply を試行錯誤させ、動いたコードだけを本番に出す、という使い方だ。エージェント運用全体の文脈は Claude Managed Agents の議論とつながる。

参照ソース

• ministackorg/ministack — GitHub
• MiniStack 公式サイト（ministack.org）
• MiniStack on PyPI
• Docker Hub: ministackorg/ministack
• StackPort（コミュニティ製 MiniStack GUI）— GitHub