Kumo: A Go-Based AWS Emulator That Covers 82 Services Without Authentication

What Kumo Solves and Who Needs It

Kumo addresses a specific pain: testing AWS integrations without paying for or provisioning real AWS resources. It is aimed at developers who run CI/CD pipelines and need a fast, disposable stand-in for AWS services. The README states that no authentication is required, which is a deliberate design choice for CI environments where credentials are often unavailable or undesirable. It also works as a local development server, letting you run code against a mock AWS endpoint on your machine. The target user is a Go developer using the AWS SDK v2, as the examples show direct client configuration with BaseEndpoint. If you are not using Go, you may still benefit, but the documentation leans heavily on Go examples.

The Architecture: A Single Binary, Many Services

Kumo is a single binary written in Go. The repository layout and README indicate that it runs an HTTP server on port 4566, the same port used by LocalStack. It implements service handlers for 82 AWS services, each with a Meta() function that provides service metadata. The README includes a table of supported services, auto-generated from these Meta() functions, which suggests a modular design where each service is a separate package. The absence of authentication means the emulator does not validate AWS credentials, so any request with a static access key works. Data persistence is optional and controlled by the KUMO_DATA_DIR environment variable. When set, the emulator stores state to disk, allowing it to survive restarts. Without it, data is ephemeral and lost on shutdown.

Getting It Running: Docker, Binary, and Compose

The quick start shows three ways to run Kumo. The simplest is Docker: docker run -p 4566:4566 ghcr.io/sivchari/kumo:latest. For persistence, add -e KUMO_DATA_DIR=/data and mount a volume. The binary path requires a build first: make build, then run ./bin/kumo. Persistence with the binary uses KUMO_DATA_DIR=./data ./bin/kumo. Docker Compose is also supported, with a minimal service definition and an optional volume for data. The examples use the AWS SDK v2 in Go, configuring a client with credentials.NewStaticCredentialsProvider("test", "test", "") and setting o.BaseEndpoint to http://localhost:4566. For S3, the example also sets UsePathStyle to true, which is a common requirement for emulators that do not support virtual-hosted-style requests.

Data Persistence: A Key Differentiator

The optional data persistence is a notable feature. Many emulators, including LocalStack in its default mode, lose state on restart unless you configure a volume. Kumo's KUMO_DATA_DIR makes persistence explicit: set the environment variable, mount a directory, and your data survives. This is useful for local development where you want to keep test data between runs, or for CI caches. The README does not specify the storage format, so you cannot know if it is a database, JSON files, or something else. That is a limitation: you cannot inspect or migrate the data easily. The trade-off is simplicity: a single environment variable controls persistence, and it works identically in Docker and binary modes.

Limitations and Failure Modes

The most obvious limitation is the lack of detail on implementation completeness. The README lists 82 services, but it does not say which API operations are implemented for each. A service like DynamoDB has many operations, and an emulator may only support a subset. The same applies to Lambda, which involves runtime execution, and CloudFormation, which requires a resource model. The README also does not mention how errors are handled or whether unsupported operations return a clear error or a generic 404. Another failure mode is the lack of authentication. While this is a feature for CI, it means Kumo is not suitable for any environment where you need to test IAM policies or credential validation. Finally, the port 4566 is shared with LocalStack, so if you run both, you will have a conflict. The README does not offer a way to change the port, so you must stop one or the other.

Alternative: LocalStack and the Difference in Approach

The primary alternative is LocalStack, which also emulates AWS services on port 4566. The difference is in scope and philosophy. LocalStack is a Python-based project with a larger community and a broader feature set, including a pro tier with advanced features like Lambda execution and API Gateway. Kumo is a Go binary, which means it starts faster and has a smaller footprint, as the README claims. Kumo also has no authentication by default, while LocalStack often requires setting a dummy access key. The real difference is the implementation language and the deployment model: Kumo is a single static binary that you can drop into any environment, while LocalStack typically runs as a Docker container with more moving parts. If you need a quick, lightweight emulator for Go CI, Kumo is simpler. If you need deep service fidelity or a mature ecosystem, LocalStack is the safer bet.

Maintenance and License Considerations

Kumo is licensed under the MIT license, which is permissive and allows commercial use, modification, and distribution without copyleft obligations. The repository is not archived, and the last push was in August 2026, with a recent release v0.28.1. The release cadence appears active, with three releases in a few weeks, which suggests ongoing maintenance. However, the README does not document upgrade procedures or migration steps between versions. Since data persistence is a feature, you should verify that data stored with an older version is compatible with a newer one. The project uses GitHub Actions for linting and integration tests, as shown by badges in the README, but the exact test coverage is not disclosed. For a tool like this, the maintenance cost is low if you use it as a disposable test dependency, but higher if you rely on persistent data across upgrades.

Editorial conclusion

Adopt Kumo if you need a fast, unauthenticated AWS emulator for CI pipelines or local development, especially if you work with Go and the AWS SDK v2. Skip it if you require deep fidelity for complex services like DynamoDB streams or Lambda, or if you need production-grade parity. Before adopting, verify that the specific service operations you rely on are implemented, check the release notes for v0.28.1, and test your exact SDK calls against the emulator, since the README does not document which operations are stubbed or incomplete.

Official sources

1. Official README
2. Project repository
3. Release notes