GENESIS-6

Ephemeral preview environments, managed as infrastructure. Create an EC2-backed preview for a branch, tear it down when you're done, snapshot if you want to bring it back later. Runs as a single Cloudflare Worker — there's no control-plane server to operate.

# Create a preview env tied to your branch.
$ cli/genesis6.sh create --branch feat/profile --context "Issue #42"
# → https://morpheus.preview.example.com

# Later, download its config by branch name — no need to track env ids.
$ cli/genesis6.sh lookup-config feat/profile > .env.local
$ ./your-deploy-script

GENESIS-6 manages infrastructure lifecycle only; application build and deployment stay external.

What makes it different

• Stateless status. D1 stores only identity and timestamps. Every GET resolves live status from CloudFormation plus a health check, so the database never disagrees with reality — there is no status column to drift.
• Config-as-URL. GET /api/environments/:id/frontend.env returns a merged .env file. Deploy scripts curl -o .env.local $URL — the template can change without re-provisioning.
• Three-layer config merge. Base template → dynamic per-environment vars → caller overrides, merged on read. A null override deletes a key from the output.
• Lifecycle beyond create/destroy. stop/start pause the EC2 instance without tearing down the stack. destroy --snapshot captures an AMI for later restore.
• Branch-indexed. lookup feat/foo returns the active environment tied to that branch; lookup-config feat/foo returns its .env. No id bookkeeping.
• Boring AWS. One CloudFormation stack per environment: EC2 + target group + ALB listener rule. Wildcard DNS to a shared ALB, no per-env DNS changes.
• Three front-ends. REST API, shell CLI, and a cyberpunk terminal web UI — all over the same Worker.

Architecture

Component	Technology
Runtime	Cloudflare Workers
Framework	Hono
Database	Cloudflare D1
Language	TypeScript
Infrastructure	AWS CloudFormation, EC2, ALB listener rules
CLI	Bash + curl

GENESIS-6 expects a wildcard preview domain, such as *.preview.example.com, to route to an existing AWS Application Load Balancer. Each environment creates one EC2 instance, one target group, and one ALB listener rule.

Requirements

• Cloudflare Workers and D1.
• AWS VPC, subnet, security group, ALB listener, and an AMI that boots your preview runtime.
• AWS credentials with permissions for CloudFormation, EC2, ELBv2, and AMI snapshot operations.
• A wildcard DNS record for your preview domain.
• An external access-control layer for deployed services, such as Cloudflare Access.

Quick Start

pnpm install
cp wrangler.example.toml wrangler.toml
cp .dev.vars.example .dev.vars

Create a D1 database and update wrangler.toml with the returned database_id:

wrangler d1 create genesis-6-db
wrangler d1 migrations apply genesis-6-db --remote

Set production secrets before deploy:

wrangler secret put AWS_ACCESS_KEY_ID
wrangler secret put AWS_SECRET_ACCESS_KEY
wrangler deploy

For local development:

wrangler d1 migrations apply genesis-6-db --local
pnpm dev
pnpm test
pnpm typecheck

Configuration

Runtime configuration is read from Worker vars and secrets. See docs/configuration.md for the full list.

Important values:

• PREVIEW_DOMAIN: parent domain for generated preview hostnames.
• BASE_AMI_ID: source AMI for new environments.
• AWS_REGION, AWS_VPC_ID, AWS_SUBNET_ID, AWS_SECURITY_GROUP_IDS, AWS_ALB_LISTENER_ARN: AWS placement and routing resources.
• STACK_PREFIX: CloudFormation stack and AMI name prefix.
• FRONTEND_BASE_TEMPLATE_JSON: optional JSON object used as the base frontend env template.

CLI

Set the service URL explicitly:

export GENESIS6_URL=https://genesis-6.example.com
export CF_ACCESS_CLIENT_ID=...
export CF_ACCESS_CLIENT_SECRET=...

Commands:

cli/genesis6.sh create --branch feat/profile --context "Issue #42"
cli/genesis6.sh list
cli/genesis6.sh get <env-id>
cli/genesis6.sh lookup <branch>
cli/genesis6.sh config <env-id> > .env.local
cli/genesis6.sh lookup-config <branch> > .env.local
cli/genesis6.sh config-update <env-id> --set KEY=VALUE
cli/genesis6.sh destroy <env-id> [--snapshot]
cli/genesis6.sh restore <env-id>
cli/genesis6.sh stop <env-id>
cli/genesis6.sh start <env-id>

Security

GENESIS-6 does not implement built-in authentication. Protect non-local deployments with Cloudflare Access, API Gateway authentication, or an equivalent upstream control. The web UI's write-operation mode is only a client-side guard against accidental clicks; it is not an authorization boundary.

Do not commit real cloud identifiers, access keys, service tokens, frontend secrets, commercial license keys, or private generated .env files.

Documentation

• DESIGN.md: architecture and lifecycle design.
• docs/configuration.md: configuration reference.
• SECURITY.md: disclosure and deployment security notes.
• SKILL.md: generic agent/CLI integration reference.

License

MIT. See LICENSE.