Gateway

Gateways let a Stackie stack expose local cloud-provider API endpoints from a gateway.<provider> block. A gateway block does not run a user process and does not require a local source path:. Instead, stackied builds an embedded Gateways router for the declared provider, binds it to the block’s served port, and owns the HTTP serving task until the stack stops.

Use a Gateway when application code expects AWS, Cloudflare, Azure, or GCP endpoints but you want those calls routed to local Stackie-managed backing services during development.

Stack Declaration

Gateway blocks are typed stack nodes. The YAML is only the serialization surface for the Rust stack model:

my-project:
  mode: managed
  blocks:
    gateway.cloudflare:
      provider: cloudflare
      serves:
        API: { port: 4569, type: api }

The typed rules are:

• block names start with gateway.
• provider: is required and must be one of the compiled Gateways providers
• path: is not allowed
• command: is not allowed
• serves: publishes the local endpoint that application blocks consume

Those rules are enforced by the stack parser and are reflected in the generated stack-format specification.

Runtime Lifecycle

When a stack declares a gateway.<provider> block, stackied does not spawn a child process. Instead it asks the embedded Gateways runtime to build a single-provider axum::Router, binds that router to a TCP listener on the allocated port, and owns the serving future for the lifetime of the block.

The GatewayRegistry tracks every live gateway by name, holding both the tokio::task::JoinHandle (so it can be awaited or aborted on shutdown) and a tokio_util::sync::CancellationToken (so graceful shutdown can be signalled through axum’s with_graceful_shutdown future).

The env field shown in the lifecycle request is daemon-internal resolved stack state. It can include local credentials for backing services such as Postgres or MinIO, so it is not a public user API and must not be logged, copied into examples, or exposed outside the trusted local daemon boundary.

Provider Compatibility

The provider table is generated from Gateways provider metadata, which derives from the same provider descriptors that build runtime routers and settings UI.

Generated from Gateways provider metadata; do not edit this table by hand.

Health Check

Every Gateway exposes GET /gateway/health on its served port. The response reports the Gateways runtime version, configured region/account, registered provider, and which optional backing services are configured.

Runtime Boundaries

Gateways are local development emulators. They are not a security boundary and do not validate real cloud signatures before accepting requests. Bind and expose them only in trusted development environments.

Gateway blocks run in-process inside stackied, not inside a sandboxed block. They can still route to Stackie-managed backing services through the block endpoint registry when those services are configured.

Limitations

Gateways emulate provider APIs for local development and compatibility testing. They are not a cloud-provider control plane, and per-operation behavior depends on the provider service family listed above and the backing services available in the current stack.