Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
AGENTS.md
Instructions for AI coding agents working in MiniStack. Read CONTRIBUTING.md
before changing a service; it has the contribution process and examples.
Where to work
ministack/app.pyowns service registration, dispatch, and reset.ministack/core/router.pydetects services;ministack/core/responses.pycontains shared response and account/region helpers.ministack/services/contains service implementations. Start with the existing service module or package and its neighboring code.tests/test_<service>.pyis the usual test location; established services may have several test files.tests/conftest.pyholds client fixtures and the_SERIAL_TESTSlist.
Before changing behavior
- New AWS services and infrastructure changes (Dockerfiles, CI workflows,
pyproject.toml, dependencies) need a scoped GitHub issue before code is written. Check for overlapping work. Follow the scope agreed in the issue. - Keep additions focused on operations needed by a real use case. Do not add speculative API coverage or operations that return placeholder results.
- Check the behavior and wire format against available evidence. Never claim behavior was validated against AWS unless it was actually run against a real AWS account. Label the evidence precisely as a real AWS observation (record region and account context when relevant), official AWS documentation, botocore service model inspection, existing tests or code, or inference; documentation, model inspection, and tests are not AWS validation. Match errors, status codes, and retry behavior.
- If AWS has one fixed behavior, implement that behavior directly rather than adding a MiniStack setting. Add configuration only for choices MiniStack itself must make.
Service contracts
- For routing and response formats, inspect the existing handler,
core/router.py, and the relevant botocore model. Some services support multiple protocols. Preserve the wire format used by the operation being changed; seeCONTRIBUTING.mdfor examples. - A new service needs an entry in
SERVICE_REGISTRYinapp.pyand the routing needed incore/router.py. Follow an established service's module layout when extending it; not every helper or submodule needs its own routing pattern. - Every registered service module, including registered submodules, must
define
get_state(),load_persisted_state(data), andreset(). The registry andtests/test_persistence.pyenforce this contract. - Keep resources isolated by account and region where AWS does. Follow the existing scoped-state helpers and check that persistence saves all tenants, not only the current request's tenant.
- Keep AWS SDK clients out of service implementations. Use them in tests or for shape inspection during development. Follow nearby code for blocking Docker calls and avoid adding service locks without checking reentrant calls.
Working and validation
- Python 3.10+ is supported; CI uses 3.13. Install test dependencies with
uv pip install --system -e ".[test]" -r requirements.txt. - Start MiniStack with
python -m hypercorn ministack.app:app --bind 0.0.0.0:4566; checkhttp://localhost:4566/_ministack/health. Most tests require the server atlocalhost:4566. - Run the relevant test file, then
pytest tests/when routing, registry, or service behavior changed. Runruff check ministack/, the CI lint gate. - Test AWS permission behavior with SDK/HTTP clients in the service's test
file, marked
@pytest.mark.auth_contract. Useiam_user(policy=...)for caller credentials andauth_enabledfor mode-dependent assertions. CI runs these contracts with bothAUTH=falseandAUTH=true; permission changes need strict enforcement and permissive compatibility assertions. Do not patchapp.AUTHor IAM enforcement in new permission contracts. Keep focused evaluator unit tests for policy logic. SeeCONTRIBUTING.mdfor local runs. - Tests that alter global server state or depend on ordering belong in
_SERIAL_TESTSintests/conftest.py; keep them out of parallel runs.
Before opening a PR
- Brand-new GitHub accounts can only open issues, not PRs.
- A contributor can have at most 5 open PRs. If the work was agreed beforehand in an issue, the maintainers may lift the limit temporarily.
- Every behavior change should be backed by real AWS evidence: a response captured from a real AWS account. PRs based on documentation, botocore model reading, LocalStack or other third-party recordings, or inference that turn out to differ from AWS will be closed. PRs that are not in line with AWS are closed and the maintainers implement the behavior themselves.
- If you can't run against AWS, open an issue describing the behavior and your workflow instead of a PR, and the maintainers will take it from there.
- Update the supported-services table in
README.mdfor a new service and follow the existingCHANGELOG.mdformat for user-facing changes. - Preserve explanatory dependency comments in
pyproject.tomlwhen changing dependencies. Avoid new lint suppressions without a reason. - Keep each PR focused. Describe every behavior change in the diff, how it was validated, and any issue that the change fulfills.
- Confirm the relevant tests, broader suite when needed, and lint pass.