How it actually works.

Most of Loopback's 117 emulated services run as fast in-process handlers inside the GraalVM-native emulator binary. Shared in-memory state keeps latency low — list-table calls complete in microseconds — and makes snapshots trivial: export serializes the same stores the handlers read and write. This is the default path for S3, DynamoDB, SQS, IAM, Blob Storage, Pub/Sub, and dozens of other wire-compatible APIs.

Services marked with a dot on the Features page escalate to Docker-backed engines when fidelity demands real processes: Lambda runs in containerized runtimes, RDS spins up actual Postgres, OpenSearch launches real nodes, EKS and GKE talk to local cluster APIs, Cosmos DB and Azure SQL use real database containers. The router selects the backend per service at request time; SDKs, CLIs, and IaC see identical API shapes and error codes either way.

The engineering trade-off is explicit: in-process for speed and determinism in CI, Docker when behavioral semantics depend on a real runtime or database engine. Compatibility tests in the repo exercise both paths against production SDKs so regressions surface before users hit them.

The built-in MCP server at /_loopback/mcp exposes 85 tools — 42 AWS, 24 Azure, 19 GCP — grouped by cloud and concern rather than by raw API surface area. Inspect tools list and describe resources with stable, typed arguments. Provision tools create, update, and delete with idempotent-friendly names. Lab tools drive chaos profiles, virtual clock advance/freeze, Cost Lab reads, snapshot export/import, interconnect authorize, and offline GenAI invocation.

Each tool maps to an internal /_loopback/* endpoint or a cloud-native API call the emulator already implements. Responses are structured JSON (resource IDs, ARNs, error codes, meter readings) — never shell stdout — so agents chain operations without regex parsing. A representative sequence: create_bucket → set_chaos on DynamoDB → advance_clock by 30 days → get_costs → export_snapshot.

Design invariant: MCP, the unified console, and direct curl hit the same state. Tool schemas are curated to reduce hallucinated resource names and impossible argument combinations — an intentional trade-off against giving agents unrestricted raw SDK access. See the Science hub for open questions on where that boundary should sit long term.

Cross-cloud traffic is denied at the proxy layer by default. When an AWS Lambda function tries to reach Azure Blob Storage, or a GCP Cloud Function publishes to an AWS SQS queue, the interconnect gateway intercepts the request before it leaves the source cloud's emulator process. Without an active attachment, the caller receives a native-shaped 403 AccessDenied — same shape SDKs expect from a missing VPC endpoint or denied resource policy.

An attachment record links the AWS hub to a peer cloud (azure or gcp). Creating the attachment is not enough: POST /_loopback/interconnects/authorize must mark it active before cross-boundary calls succeed. Revoking authorization returns the link to denied state without tearing down the attachment metadata — useful for testing gradual rollout and rollback.

Chaos profiles apply independently to authorized links: inject latency, drop packets, or sever the link entirely while in-process services on each cloud keep running. This minimal model reproduces partition and failover behavior teams see with ExpressRoute outages or misconfigured peering, without simulating full BGP stacks or requiring real cloud accounts.

Production IAM denials are painful: the API returns AccessDenied with little context, and engineers grep CloudTrail, simulate policies in the console, or binary-search statement blocks. Loopback's /_loopback/why-403 endpoint replays the exact SigV4-signed request against the effective policy set stored in the emulator — identity policy, resource policy, and SCP-style permission boundaries — and returns structured diagnostics synchronously.

The response identifies the failing statement index, the condition key that evaluated false, and whether the block came from an explicit Effect: Deny or a missing Allow. Because policies live in-memory alongside the resources they protect, replay is deterministic and instant — no CloudTrail lag, no simulate API quota.

Why-403 integrates with snapshots: capture state before a policy change, mutate IAM, observe a denial, diagnose it, then restore the snapshot and verify the fix. MCP exposes this as a lab tool so agents can learn from denials instead of retrying blindly. Azure and GCP have parallel permission models on their endpoints; AWS why-403 is the most mature diagnostic path today.

Each cloud emulator maintains a virtual clock independent of wall time, exposed via /_loopback/clock/advance, /_loopback/clock/freeze, and read endpoints on all three ports. Fast-forward advances expiry for STS session tokens, DynamoDB TTL attribute sweeps, SQS visibility timeouts, EventBridge rules, Scheduler tasks, and ACM certificate renewal windows. On Azure, hidden queue messages become visible again after the advanced interval; on GCP, Cloud Scheduler fires pending jobs against the new instant.

Freeze pauses all time-dependent logic — TTL sweepers, token rotation, schedule evaluation — so assertions run against a stable instant. Background sweepers compare resource timestamps against the virtual clock on each tick rather than sleeping on wall clocks, which means CI pipelines never need sleep 86400 to test token expiry.

Design invariant documented in Science working notes: Cost Lab meters, TTL logic, and schedule firing all consult the same clock source. Advancing thirty days in one POST produces consistent cost accrual, expired credentials, and fired schedules in a single deterministic step — a property production clouds cannot offer on a laptop.

The Cost Lab hooks into service-level operation counters maintained by each emulated service — S3 PUT/GET/LIST, Lambda invocations, DynamoDB read/write capacity units, Bedrock token usage through the offline GenAI gateway, and Azure/GCP analogs. Counters multiply against published pricing tables per cloud; /_loopback/costs returns run rate, month-to-date totals, and per-service breakdowns, while /_loopback/costs/whatif projects scaled spend over future months.

Because the meter reads the same virtual clock as TTL and schedule logic, advancing time via /_loopback/clock/advance accrues cost in lockstep with expiry events. Freeze the clock at month-end and the meter shows a full month of spend without waiting on wall time — essential for agent loops that need to learn cost consequences of provisioning decisions.

The broader design goal: agents (and the humans supervising them) should provision, break, and learn against real API shapes with zero blast radius. Every control plane — MCP tools, the unified console, direct /_loopback/* curl, and native SDKs — is a first-class interface to the same emulator state, not an afterthought layered on a CLI wrapper. SigV4, interconnect 403 gates, snapshots, and offline GenAI exist so agent workflows encounter production-shaped constraints locally before they touch a real account.