Backend connections
Your backend stays in your cloud, and each deployment, the part of your product running in a customer's environment, needs to hear from it. None of the ways they talk needs an inbound port in the customer's network.
Architecture diagram. Left: Your side containing Your backend; Alien manager. Right: customer-1's cloud account containing acme-docs deployment containing processor (Worker); policies (KV); api (Worker).
Options
| Way | Direction | Carries | Use it for |
|---|---|---|---|
| Releases | Alien → deployment | Your code and its resources | Every change to what runs |
| Commands | Your backend → your code, and back | A call and its result | Questions answered next to the data, actions that return a result |
| Remote bindings | Your backend → one resource | Reads and writes | Settings, entitlements, and other data your backend owns |
| Queued jobs | Your backend → a queue → your code | A message, no result | Work that can run later |
| Calls to your API | Deployment → your backend | Usage, status, events | Reporting what the deployment did |
| Status and logs | Deployment → Alien → your backend | Health, logs, webhooks | Watching every deployment |
| Browser access | Browser → deployment | Customer content | Content that must not pass through your cloud |
Releases
A release is a version of your stack. After initial setup, the one-time step the customer's admin runs, Alien rolls out each release without the admin. This is ongoing management; see Frozen and live.
How a release reaches the deployment depends on its deployment model:
- Push: Alien's manager calls the cloud provider's APIs with the management identity that initial setup created. Used on AWS, Google Cloud, and Azure.
- Pull: an agent in the environment connects out over HTTPS and applies the release: the Operator on Kubernetes, the machine agent on Linux servers.
- Air-gapped: an admin carries the release in a folder.
Your backend doesn't call either one. You publish with alien release, and Alien rolls the release out to every deployment that follows its channel. See Releases and Push, pull, and air-gapped.
Commands
Your backend calls a named handler in your deployed code and waits for its result:
const input = { prefix: "contracts/", limit: 20 }
const { results } = await commands.invoke<{ results: string[] }>("search", input)Use a command when the answer must be computed next to the data, or when your backend needs to know the action finished. The deployment polls for commands over outbound HTTPS, and Workers on AWS, Google Cloud, and Azure can also receive them by push. See Commands.
Remote bindings
Your backend reads and writes one resource in the customer's account directly, with short-lived credentials scoped to it.:
const policies = bindings.kv("policies")
await policies.setJson("ingest", { maxBytes: 50_000_000 })bindings is the remote binding client for one customer; Remote bindings shows how to create it.
Use a remote binding when your backend owns data that the deployment reads locally. No handler runs, and the call goes to the cloud provider's API, so it needs AWS, Google Cloud, or Azure. See Remote bindings.
Queued jobs
To hand work to the deployment without waiting for it, send a message to a Queue with a remote binding. A Worker in the deployment handles it with onQueueMessage:
const jobs = bindings.queue("jobs")
await jobs.send({ type: "reindex", prefix: "contracts/" })Mark the queue with remoteAccess: true in alien.ts, like any remote binding. Messages are limited to 64 KiB.
Your backend gets no result. If you need one, have the Worker call your API. See Send from your hosted software.
Calls to your API
Code in the deployment calls your API over outbound HTTPS, like any other client. Pass your API's URL and a credential as developer-provided inputs.
Send metadata, not content: counts, IDs, and status. See Deployment to your backend for the full example.
Status and logs
Every deployment reports its status, heartbeats, and logs to Alien over outbound HTTPS. Your backend reads them instead of building its own reporting:
- Webhooks: a signed request when a deployment starts running, fails, or stops reporting.
- Deployment status:
GET /v1/deployments/{id}for a page your customer is watching. - Logs and metrics: search any deployment's logs, or forward them to your own tools.
Browser access
When customer content must reach a user without passing through your cloud, the browser calls the deployment's endpoint directly, with a short-lived token your backend issues. See Browser to the deployment and Networking and endpoints.
Next
- Commands: call a handler in a deployment and get its result
- Remote bindings: read and write a resource in the customer's account
- Networking and endpoints: every path in or out of a deployment
Networking and endpoints
Expose a Worker or Container over HTTPS, keep services private inside the stack, and know which network choices belong to initial setup.
Send commands
Run code in a customer's environment from your backend and get the result back, with zero inbound networking and no ports to open.