Connect your backend
The part of your product that runs in a customer's environment, the deployment, talks to the rest of your product in your cloud in three directions. Only browser traffic needs an endpoint there, and it can stay on the customer's private network.
| Direction | Mechanism | Carries |
|---|---|---|
| Deployment → your backend | Outbound HTTPS to your API | Usage counts, status, events |
| Your backend → deployment | Send commands to your code, or read and write resources with remote bindings | Instructions and small results |
| Browser → deployment | A public or private endpoint with a short-lived token | Customer content |
Deployment to your backend
Code in the deployment calls your API like any other client. Give it your API's URL and a credential as inputs you provide for each deployment:
import * as alien from "@alienplatform/core"
const config = alien.inputs({
acmeApiUrl: alien.string({
providedBy: "developer",
required: true,
label: "Acme API URL",
description: "Where this deployment reports usage and status.",
env: "ACME_API_URL",
}),
acmeApiToken: alien.secret({
providedBy: "developer",
required: true,
label: "Acme API token",
description: "Authenticates this deployment to your API.",
env: "ACME_API_TOKEN",
}),
})Pass config to the stack with .inputs(config). Your code reads process.env.ACME_API_URL. See Inputs and secrets.
Send metadata, not content: counts, IDs, and status. If you wouldn't store it in your own database, don't send it.
Your backend to the deployment
Commands
Your backend sends a command, by name, to a handler in your deployed code. Alien carries it; the deployment picks it up over its outbound connection, runs it, and returns the result.
import { CommandsClient } from "@alienplatform/commands"
const commands = await CommandsClient.forDeployment({
deploymentId: customer.deploymentId,
apiKey: process.env.ALIEN_API_KEY!,
})
const summary = await commands.invoke("monthly-summary", { month: "2026-09" })Return the smallest result your backend needs, such as a total or a status. The data stays where it is. See Commands.
Remote bindings
Your backend can also read or write a resource in the customer's account directly, for example to push a setting to the deployment. Mark the resource with remoteAccess: true:
const policies = new alien.Kv("policies").build()
export default new alien.Stack("acme-docs")
.add(policies, "frozen", { remoteAccess: true })
.build()Your backend then gets short-lived cloud credentials scoped to that one resource, and calls it through the cloud's own APIs:
import { Bindings } from "@alienplatform/bindings"
const bindings = await Bindings.forRemoteCustomer({
project: "acme-docs",
externalId: customer.id,
token: process.env.ALIEN_REMOTE_BINDINGS_KEY!,
})
const policy = { maxBytes: 50_000_000 }
await bindings.kv("policies").setJson("ingest", policy)No network path into the customer's environment is involved, and only resources you mark are reachable. See Remote bindings.
Browser to the deployment
Customer content can reach the user's browser without passing through your cloud: the browser calls the deployment directly.
Sequence diagram. Lanes: Browser (customer's user), Your backend (your cloud), Deployment (customer's cloud). Steps: 1 · sign in; 2 · short-lived token; no content here; 3 · verify token.
- The user signs in to your product as usual.
- Your backend issues a short-lived token, signed with your private key, naming the customer and the user.
- The browser calls the deployment's endpoint with that token. The deployment verifies the signature with your public key, which you pass as a developer input.
The endpoint can be public or reachable only from the customer's network. See Networking and endpoints.
Uploads
To accept files:
- The deployment creates a signed upload URL for its own storage and returns it to the browser.
- The browser uploads straight into the customer's bucket.
Your backend sees the job, not the file.
Next
- Commands: send commands to code in a deployment.
- Remote bindings: read and write a deployment's resources from your backend.
- Deployment UX: how customers deploy, from a setup link to your own setup screen.