Stargate

Stargate is Alloy's gateway pattern for connecting Alloy to systems that live behind a customer's VPN, firewall, private network, or other restricted environment.

Instead of requiring the internal system to expose an inbound public endpoint, a Stargate process runs inside or near the restricted environment. It opens an outbound connection to Alloy, polls for work assigned to a named internal system, executes that work against the internal service, and reports the result back to Alloy.

Use Stargate when Alloy needs to trigger actions or read data from an internal system that should not be exposed directly to the public internet.

Common examples:

- Customer systems reachable only through a VPN or private network. - Internal admin tools that should stay behind a firewall. - Legacy services that cannot safely receive public webhooks. - Environments where outbound traffic is allowed but inbound traffic is not.

Do not use Stargate when the target system already exposes a safe public API, an MCP server, or a normal webhook endpoint that Alloy can call directly.

Stargate has three moving parts:

- **Alloy**: stores routed tasks and exposes the private Stargate API. - **Stargate gateway**: runs in the restricted environment and polls Alloy. - **Internal system**: the private service the gateway calls on Alloy's behalf.

The gateway needs two kinds of credentials:

- An Alloy organization private API key for polling and reporting tasks. - Optional internal-service authorization for requests from the gateway to the internal system.

The internal system does not need to accept inbound traffic from Alloy. It only needs to be reachable from the gateway process.

1. Alloy creates or queues a task for a named internal system. 2. The gateway polls Alloy with that system name. 3. Alloy returns pending tasks for that system. 4. The gateway executes each task against its configured internal system URL. 5. The gateway reports the status, response body, and any error back to Alloy.

Tasks contain the method, URI, optional JSON body, and routing metadata. `GET` and `HEAD` tasks are sent without a body; other methods send the body as JSON.

A Stargate gateway is configured with:

| Setting | Purpose | |---------|---------| | `ALLOY_API_URL` | Alloy API base URL used for polling and reporting. | | `ALLOY_API_KEY` | Organization private API key sent as the `api-key` header. | | `INTERNAL_SYSTEM` | Routing key that tells Alloy which tasks this gateway receives. | | `INTERNAL_SYSTEM_URL` | Base URL of the private internal service. | | `INTERNAL_AUTHORIZATION_HEADER_NAME` | Optional header name for internal-service auth. Defaults to `Authorization`. | | `INTERNAL_AUTHORIZATION_HEADER_VALUE` | Optional header value for internal-service auth. |

If the Alloy URL, Alloy API key, or internal system name is missing, the gateway should stay idle rather than polling.

Stargate reduces public exposure by making the connection outbound from the restricted environment to Alloy. The internal service stays private, and Alloy does not need direct network access to it.

Security still depends on correct configuration:

- Treat the Alloy private API key as an organization-level secret. - Use a distinct `INTERNAL_SYSTEM` routing key per internal target or boundary. - Keep internal-service authorization separate from the Alloy API key. - Run the gateway in the narrowest network location that can reach the target service. - Log task IDs and statuses, but do not log secrets or sensitive response data.

The Stargate API lives under `/api/private/stargate` and uses the same `api-key` authentication as the rest of Alloy's private API.

For exact route shapes and payload fields, see `private-api.md`.