A self-hosted, AWS-compatible cloud in one binary: point your real Terraform, AWS CLI and SDK code at it, and it runs on real containers and VMs on your machine.
Website · Live demo console · Quick start · AWS compatibility · Terraform modules · Testing & CI · vs. LocalStack, moto, MinIO… · Discord
Latest: v0.4.0: VM instances, a container image, a GitHub Action and testcontainers, 17/17 Terraform modules passing.
- Your AWS code, unchanged. HomeCloud speaks the AWS wire protocols (SigV4, awsJson, awsQuery, REST). Set
AWS_ENDPOINT_URLand the AWS CLI, boto3 and the Terraform AWS provider work against it, with IAM policies enforced as on AWS. - Real compute, not mocks. Lambda runs on AWS's official runtime images, RDS is a real PostgreSQL/MySQL/MariaDB, S3 is MinIO, EC2 instances are containers you can shell into or full VMs under QEMU/KVM, load balancers are nginx, security groups are iptables rules. Your integration tests hit the same kind of thing production does.
- See what happened. A web console modeled on AWS's, CloudWatch logs and metrics for every resource, and a CloudTrail record of every AWS API call, so a failed test run can be inspected instead of guessed at.
Built for developers who want a real AWS-compatible target for local development and CI. It also suits college labs teaching AWS without accounts or bills, and small teams and homelabs that want AWS tooling on their own hardware.
You need Docker (Docker Engine on Linux, Docker Desktop or OrbStack on macOS and Windows).
curl -fsSL https://homecloud.pages.dev/scripts/install.sh | sh # Linux / macOS
homecloud serveWindows (PowerShell)
irm https://homecloud.pages.dev/scripts/install.ps1 | iex
homecloud serveOn first start HomeCloud creates your account, prints the root console password once, and writes CLI credentials to ~/.homecloud/credentials. Open http://127.0.0.1:8080 and sign in as root. The first start pulls container images (MinIO, and later the engines you use), so it takes longer than the next ones.
Then, in another terminal, use your normal AWS tools:
eval "$(homecloud aws-env)" # sets AWS_ENDPOINT_URL, access keys and region
aws sts get-caller-identity
aws s3 mb s3://demo && echo hi | aws s3 cp - s3://demo/hello.txt
aws sqs create-queue --queue-name jobsOr with Docker only, nothing to install:
docker run -d --name homecloud -p 127.0.0.1:8080:8080 \
-v /var/run/docker.sock:/var/run/docker.sock -v homecloud-data:/data \
ghcr.io/solinode/homecloud
docker logs homecloud # the root console password (once)
eval "$(docker exec homecloud homecloud aws-env)" # point the AWS CLI at itHomeCloud starts its services as containers next to its own on the same Docker host; mounting the socket gives it control of that host, as running the binary does. See Docker in the server guide for exposing it, TLS and upgrades.
Other ways to install: build from source with Go 1.25+ and Node.js 22+ (make, binary in bin/homecloud), or follow Install on a server for a VPS or home server (system service, TLS, firewall, backups).
HomeCloud's own end-to-end job runs it on a stock GitHub Actions runner. The same pattern works for your tests:
curl -fsSL https://homecloud.pages.dev/scripts/install.sh | sh
nohup homecloud serve > homecloud.log 2>&1 &
for i in $(seq 1 60); do curl -fsS localhost:8080/api/v1/health && break; sleep 2; done
eval "$(homecloud aws-env)"
# ... terraform apply / pytest / your test suite ...S3 starts in the background on first boot; if your tests use S3 right away, wait for s3: MinIO ready in the log (see .github/workflows/ci.yml).
Or use the ready-made pieces in docs/integrations.md: a GitHub Action that does the above in one step, and testcontainers modules for Go and Python.
| Tool | Status |
|---|---|
| AWS CLI v2 | Tested: the compatibility test suite drives the real aws CLI in CI |
| boto3 (Python SDK) | Tested: the compatibility test suite runs boto3 in CI, including Cognito SRP sign-in through pycognito |
Terraform / OpenTofu (hashicorp/aws provider) |
Tested: opt-in Terraform tests in the suite (IAM, S3, Route 53, CloudFormation and more; HC_TEST_TERRAFORM=1), and examples/terraform/shop applies, re-plans clean and destroys on a fresh install. Nightly: 17 of 17 popular terraform-aws-modules scenarios apply, re-plan clean and destroy (results). |
CloudFormation (aws cloudformation deploy) |
Tested: stacks, change sets and the boto3 waiters (details) |
| AWS CDK | Partly: CDK-synthesized templates deploy through CloudFormation change sets; cdk bootstrap / cdk deploy end to end is not yet verified |
| Other AWS SDKs (JavaScript, Go, Java, …) and Pulumi | Expected to work (same protocols and SigV4), not yet covered by tests. Reports welcome |
Run homecloud aws-env to get the environment variables. For Terraform, point the provider's endpoints {} block at HomeCloud and use s3_use_path_style = true; the shop example shows a complete provider block.
"AWS API" means the AWS CLI, SDKs and Terraform can manage it; every service is also in the console, the homecloud CLI and the native REST API. The notes name the main gaps; docs/aws-compat.md lists operations and differences per service.
| Service | AWS equivalent | Status | Notes |
|---|---|---|---|
| Compute | EC2, EBS, AMIs | AWS API | Instances are containers; ami-ubuntu-24-04-vm and ami-debian-12-vm boot real virtual machines (QEMU, KVM when the host has /dev/kvm, emulated otherwise) on the same VPC networking, with extra volumes, snapshots, images, run-command and a serial console. Key pairs, user data, volumes, snapshots, launch templates, Elastic IPs (records only), IMDSv1/v2, browser shell |
| Auto Scaling | EC2 Auto Scaling | AWS API | Target tracking on CPU; scheduled actions and lifecycle hooks are not implemented |
| Networking | VPC, security groups | AWS API | Security groups enforced inside the VPC; network ACLs recorded, not enforced; no peering; IPv4 only |
| Load balancing | ELB v2 | AWS API | Application load balancers (HTTP/HTTPS, path/host rules). No network load balancers |
| DNS | Route 53 | AWS API | Public and private zones served by CoreDNS; no routing policies or health checks |
| Certificates | ACM | AWS API | Issued from HomeCloud's private CA, not a public one |
| Object storage | S3 | AWS API | MinIO underneath; versioning, lifecycle expiry, presigned URLs, bucket policies, websites |
| Shared files | EFS | AWS API | Docker volumes mounted into instances and tasks; no NFS endpoint |
| Containers | ECS (Fargate), ECR | AWS API | One container per task definition |
| Databases | RDS | AWS API | PostgreSQL, MySQL, MariaDB; no Multi-AZ, read replicas or Aurora |
| Caches | ElastiCache | AWS API | Redis, Valkey, Memcached; one node per cluster, no TLS |
| Document DB | DocumentDB-style MongoDB | Native API only | MongoDB through the console, CLI and native API |
| Functions | Lambda | AWS API | AWS runtime images, versions, aliases, layers, async invoke, SQS and DynamoDB stream triggers, function URLs |
| HTTP APIs | API Gateway v2 | AWS API | HTTP APIs with Lambda/HTTP proxy and JWT authorizers; REST and WebSocket APIs are not supported |
| Queues | SQS | AWS API | Standard and FIFO, DLQs and redrive |
| Pub/sub | SNS | AWS API | SQS, Lambda and HTTP(S) subscriptions with filter policies; e-mail and SMS messages are written to the server log, not sent |
| Key-value | DynamoDB | AWS API | Expressions, GSIs/LSIs, transactions, PartiQL, TTL, streams |
| Workflows | Step Functions | AWS API | Lambda, SQS and SNS tasks; no activities |
| Events | EventBridge, Scheduler | AWS API | Buses, rules, schedules; no archives or replays |
| Identity | IAM, STS | AWS API | Policies with conditions, roles, temporary credentials, permissions boundaries, simulator |
| App identity | Cognito user pools | AWS API | SRP and password sign-in, JWTs; no MFA or hosted UI; codes go to the server log instead of e-mail/SMS |
| Secrets and keys | Secrets Manager, KMS, SSM Parameter Store | AWS API | Single region, so replication and multi-Region replicas are refused |
| Monitoring | CloudWatch, CloudWatch Logs | AWS API | Metrics, metric math, alarms, Logs Insights; anomaly bands are a statistical approximation, not AWS's model |
| Infrastructure as code | CloudFormation | AWS API | Change sets, updates with rollback; no nested stacks, custom resources or AWS::Serverless |
| Audit | CloudTrail | AWS API | Every AWS-protocol call and every mutating or denied native call; trails deliver to S3 |
Overall limits: HomeCloud runs on one Docker host and serves one region (us-east-1) and one account. Multi-node clusters are a design (#55), not a feature.
Built into the binary: run homecloud serve and open http://127.0.0.1:8080, or try the demo in your browser (sample data, runs entirely client-side, nothing to install).
 EC2: instances in your VPCs |
 Lambda: functions, versions, aliases, in-browser editor |
 S3: buckets, objects, presigned links |
 IAM: users, roles and policies |
 DynamoDB: tables, queries, item editor |
 CloudWatch: metrics, alarms and logs |
Besides the AWS tools, HomeCloud has its own shorter CLI for every service:
homecloud ec2 run --name web --image ami-nginx --sg sg-xxxx # an instance
homecloud rds create orders-db --engine postgres --public # a database, password in Secrets Manager
homecloud lambda create resize --runtime python3.12 --code ./resize
homecloud sqs create jobs --dlq jobs-dlq && homecloud lambda trigger resize jobs
homecloud cfn create pipeline docs/examples/pipeline.yaml -p Env=dev
homecloud api GET /api/v1/cloudwatch/alarms # anything else, rawRun homecloud --help or homecloud <service> --help for every command. Operations: homecloud service install (launchd or systemd), homecloud backup / restore, homecloud upgrade, homecloud doctor.
To reach the server from other machines, bind it to a LAN or Tailscale address with TLS:
homecloud serve --addr 0.0.0.0:8080 --public-host homelab.tailnet.ts.net --tls-self-signed- AWS compatibility: supported operations per service, IAM behavior, differences from AWS
- Comparison with LocalStack, moto, MinIO, OpenStack and the AWS free tier
- Architecture: how each service is built, where state lives, limits
- Install on a server: VPS or home server, TLS, firewall, backups, upgrades
- Native API reference
- Security audit, October 2026 and the security policy
- Designs: multi-node clusters, edge compute
- Changelog
HomeCloud needs the Docker socket, which is root-equivalent on the host: treat HomeCloud administrators as host administrators. The API binds to 127.0.0.1 by default. Findings and fixes from the audits are in docs/security-audit-2026-10.md and docs/security-audit-vm-2026-10.md. Report vulnerabilities privately as described in SECURITY.md.
- Shipped in 0.4.0: VM-backed EC2 instances (QEMU, KVM when available), the container image
ghcr.io/solinode/homecloud, a GitHub Action and testcontainers modules for Go and Python, a nightly Terraform modules compatibility suite (17 of 17 pass), and fixes from two security audits (platform, VM instances). - Next: signed releases with SBOMs, safer upgrades with automatic backup and rollback, Prometheus metrics for HomeCloud itself, a guided first run in the console, testcontainers for Java and Node, and passt networking for VMs on Ubuntu 24.04 hosts (#90).
- Planned: multi-node clusters (#55, design), edge compute and hardware integrations (#56, design).
See the open issues for everything planned.
Start with CONTRIBUTING.md: how to build, run the tests and pick up a good first issue. Missing an AWS operation your code needs? Open a compatibility gap issue. By contributing you agree to the Contributor License Agreement and the Code of Conduct.
Chat with us on Discord.
GNU AGPL-3.0. If you run a modified HomeCloud as a service for others, share your changes.