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 four moving parts:

• Alloy AI teammate: calls `stargate.execute_task` when it needs a private

system that Alloy cannot reach directly.

• Alloy backend: 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. An Alloy AI teammate calls `stargate.execute_task` with a `system`, `uri`,

HTTP `method`, and optional JSON `body`.

1. Alloy creates a task for the named internal system.
2. The gateway long-polls Alloy with that system name.
3. Alloy returns pending tasks for that system and marks them as `requested`.
4. The gateway executes each task against its configured internal system URL.
5. The gateway reports the result back to Alloy.
6. Alloy records that response, and the tool call returns the recorded result to

the AI teammate or times out if no gateway response arrives in time.

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.

`stargate.execute_task` is the Alloy runtime tool that creates work for a Stargate gateway. It is available both to AI teammates and as a structured-workflow tool-step option. For private-network systems only; for internet-reachable APIs, use the regular `http.http_request` tool instead.

Tool inputs:

Current runtime behavior:

• The tool creates the task and then polls Alloy for up to `120` seconds.
• If no gateway response arrives in time, Alloy marks the task as `failed`.
• Do not auto-retry after a timeout without user confirmation; the gateway may

already have executed the internal request.

• The current public Stargate gateway reports a JSON envelope with:
• `ok`
• `status`
• `body`
• optional `error`
• Alloy currently stores that posted payload verbatim as text, so the tool

returns the recorded Stargate response body rather than a normalized parsed result.

The gateway implementation is open source and available in the public [`Alloy-Systems/stargate`](https://github.com/Alloy-Systems/stargate) repository on GitHub. It is licensed under Apache 2.0.

Current gateway behavior:

• Starts an HTTP server on `PORT` (default `4300`).
• Exposes `GET /health` returning `{ status: "ok" }`.
• Exposes `GET /metrics` returning current in-process counters and health booleans for proxy traffic, polling, task handling, and startup time.
• Proxies `/api/*` to `${ALLOY_API_URL}/api/*` and injects the Alloy `api-key`

header.

• Starts a background Stargate daemon that polls

`/api/private/stargate/?system={INTERNAL_SYSTEM}`.

• On polling errors, retries with backoff of `1s`, `2s`, `5s`, `10s`, then

`30s`.

• If `ALLOY_API_URL`, `ALLOY_API_KEY`, or `INTERNAL_SYSTEM` is missing, the

Stargate daemon logs `stargate_disabled` and stays idle.

• The current starter logs uncaught exceptions and unhandled rejections without

terminating the process.

• When `HTTP_PROXY` or `HTTPS_PROXY` is configured, the gateway installs a

global undici proxy dispatcher, so outbound fetches also honor proxy routing.

A Stargate gateway is configured with:

The current repo also ships:

• `.env.example`
• `docker-compose.yml.example`
• `Dockerfile`

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.
• If proxy routing is enabled, verify `NO_PROXY` covers any internal hosts that

must bypass the corporate proxy.

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`.