GitHub – SethPyle376/hiraeth · GitHub

Hiraeth is a local AWS emulator focused on fast integration testing. The first
release target is SQS: signed AWS SDK requests go through a local HTTP endpoint,
state is stored in SQLite, and an optional web UI exposes the local emulator
state for debugging.

This project is early. It is intended for local development and test
environments, not as a production AWS replacement.

• AWS SigV4 header authentication with a seeded local test credential.
• SQLite-backed principals, access keys, queues, messages, attributes, and tags.
• SQS-compatible endpoint for common queue and message operations.
• Web admin UI on a separate port for inspecting local emulator state.
• Docker and Docker Compose support.
• SQLx offline query metadata for checked SQL builds.

Start Hiraeth with Docker Compose:

docker compose up --build

The AWS-compatible endpoint listens on http://localhost:4566. The admin UI
listens on http://localhost:4567.

The default seeded credential is:

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

Create and inspect a queue with the AWS CLI:

aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name local-orders
aws --endpoint-url http://localhost:4566 sqs list-queues
aws --endpoint-url http://localhost:4566 sqs send-message \
  --queue-url http://localhost:4566/000000000000/local-orders \
  --message-body "hello from hiraeth"
aws --endpoint-url http://localhost:4566 sqs receive-message \
  --queue-url http://localhost:4566/000000000000/local-orders \
  --message-attribute-names All

Compose stores SQLite data in the named volume hiraeth-data.

Release images are published to GitHub Container Registry:

docker pull ghcr.io/sethpyle376/hiraeth:v0.1.0

Release maintainers can publish a multi-architecture image for linux/amd64
and linux/arm64 from a local Docker Buildx environment:

docker login ghcr.io
scripts/publish-image.sh v0.1.0

The publish script pushes ghcr.io/sethpyle376/hiraeth:. Tags must match
the release format v*.*.*.

mkdir -p .local
HIRAETH_DATABASE_URL=sqlite://.local/db.sqlite cargo run -p hiraeth_runtime

Defaults:

When running from source, prefer setting HIRAETH_DATABASE_URL to a path under
.local/ or another directory that already exists.

The web UI is an admin/debug surface for local emulator state. It currently
supports SQS queue browsing, queue details, message inspection, attributes, tags,
purge, delete queue, and delete message.

The web UI does not use SigV4 authentication. Keep HIRAETH_WEB_HOST bound to a
trusted interface unless you intentionally want to expose local test state.

The current UI uses CDN-hosted Tailwind, DaisyUI, and htmx assets. A fully
self-contained/offline UI asset pipeline is still future work.

Status labels:

• Supported: implemented and covered by unit and/or AWS SDK integration tests.
• Partial: implemented, but known AWS edge behavior is incomplete.
• Not implemented: requests currently return UnsupportedOperation.

• IAM and queue policy enforcement are not implemented yet.
• Error responses are SDK-compatible for common paths, but not exhaustively
  identical to AWS.
• Request validation is pragmatic and still needs a deeper AWS parity pass.
• FIFO behavior stores FIFO fields, but does not yet fully model ordering,
  deduplication windows, or throughput behavior.
• The web UI is a local admin preview and is not authenticated.

AI tools are used as part of this project’s development workflow for code
generation, refactoring, test writing, documentation drafts, and design
discussion.

Most runtime code has been written by hand, most test code has been generated.
Regardless, all changes are reviewed, edited, and accepted by a human maintainer,
and the project relies on normal engineering checks such as tests, SQLx query
checking, and manual review rather than treating AI output as authoritative.

Hiraeth is licensed under the MIT License.

Format and test:

Prepare the local database used by SQLx query checking:

cargo run -p xtask -- prepare-db

Refresh SQLx offline metadata:

DATABASE_URL=sqlite://.local/db.sqlite cargo sqlx prepare --workspace -- --all-targets

Check SQLx metadata in CI-style mode:

DATABASE_URL=sqlite://.local/db.sqlite cargo sqlx prepare --workspace --check -- --all-targets

The checked SQL metadata under .sqlx/ should be committed when queries or
migrations change.