kiri-aws Documentation

Ultra-fast local AWS Emulator with deterministically accurate Billing Engine & Time Machine API for offline development & testing.

⚡ Sub-millisecond Latency ⏱️ Virtual Time Advancement 💰 AWS Cost Explorer Emulation 🛡️ 100% Offline & Local

⚡ Quickstart

Run kiri-aws locally in seconds. Zero cloud dependencies, zero external credentials needed.

Bash / Terminal

# 1. Run kiri-aws locally via Go or Docker
go run ./cmd/kiri

# 2. Configure AWS CLI to point to kiri
export AWS_ACCESS_KEY_ID="test"
export AWS_SECRET_ACCESS_KEY="test"
export AWS_DEFAULT_REGION="us-east-1"
export AWS_ENDPOINT_URL="http://localhost:4566"

# 3. Create S3 Bucket & DynamoDB Table
aws s3 mb s3://my-billing-bucket
aws dynamodb create-table --table-name Orders --attribute-definitions AttributeName=ID,AttributeType=S --key-schema AttributeName=ID,KeyType=HASH --billing-mode PAY_PER_REQUEST

🐳 Docker Setup

Run kiri-aws as a background daemon container in your docker-compose or CI pipeline.

docker-compose.yml

version: '3.8'
services:
  kiri:
    image: kiri-aws:latest
    ports:
      - "4566:4566"
    environment:
      - KIRI_PORT=4566
      - KIRI_LOG_LEVEL=info

⏱️ Time Machine API (Time Travel)

Simulate hours, days, or months of infrastructure uptime instantly to trigger recurring billing calculations.

💡 How it works: Calling POST /_kiri/time/advance?days=30 advances the internal virtual clock by 30 days without sleeping. All provisioned S3 buckets, DynamoDB tables, and KMS keys accrue billing ledger records deterministically.

cURL

# Advance virtual time by 30 days
curl -X POST "http://localhost:4566/_kiri/time/advance?days=30"

# Response
{
  "status": "success",
  "advanced_by": "720h0m0s",
  "current_virtual_time": "2026-08-21T05:13:21Z"
}

💰 Cost Explorer (CE) Integration

Query exact simulated cost invoices using the standard AWS Cost Explorer API endpoint.

cURL - Cost Explorer Query

curl -X POST "http://localhost:4566/" \
  -H "Content-Type: application/x-amz-json-1.1" \
  -H "X-Amz-Target: AWSInsightsIndexService.GetCostAndUsage" \
  -d '{
    "TimePeriod": {"Start": "2026-01-01", "End": "2026-12-31"},
    "Granularity": "MONTHLY",
    "Metrics": ["UnblendedCost"]
  }'

🐼 Lightpanda MCP Server (Plug-and-Play AI Module)

A standalone Model Context Protocol (MCP) server for Lightpanda — enabling any AI Agent (Claude Code, Google Antigravity, Cursor, Windsurf, LangChain) to browse, execute JS, and extract Markdown/AX-Tree at 16x lower memory footprint.

1. Build MCP Binary

go build -o bin/lightpanda-mcp ./cmd/lightpanda-mcp

2. Plug into AI Agent Config (mcpServers)

{
  "mcpServers": {
    "lightpanda": {
      "command": "/path/to/bin/lightpanda-mcp",
      "env": {
        "LIGHTPANDA_HOST": "127.0.0.1",
        "LIGHTPANDA_PORT": "9222"
      }
    }
  }
}

🐹 AWS SDK Go v2 Example

main.go

package main

import (
	"context"
	"fmt"
	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
	ctx := context.Background()
	cfg, _ := config.LoadDefaultConfig(ctx,
		config.WithRegion("us-east-1"),
		config.WithEndpointResolverWithOptions(aws.EndpointResolverWithOptionsFunc(
			func(service, region string, options ...interface{}) (aws.Endpoint, error) {
				return aws.Endpoint{URL: "http://localhost:4566"}, nil
			},
		)),
	)

	s3Client := s3.NewFromConfig(cfg)
	out, _ := s3Client.ListBuckets(ctx, &s3.ListBucketsInput{})
	fmt.Printf("Buckets: %d\n", len(out.Buckets))
}