How Alien works
Your customer's admin sets up your software once, and every release after that reaches their environment without them. Those are the two phases of every deployment: initial setup, run once by the admin with their own credentials, and ongoing management, run by Alien.
Everything on this page applies to deployments. Customer-managed keys and local AI models used from your hosted product work through hosted gateways instead; see Hosted gateways.
Architecture diagram. Left: Customer's admin containing Setup package; Your side containing Alien manager. Right: customer-1's AWS account containing Isolated area containing Created at initial setup containing IAM role; files; Managed by Alien containing worker.
This page follows that example, a worker next to a files bucket in customer-1's AWS account, from alien.ts to a running deployment.
The stack
You describe what runs in each customer's environment once, in alien.ts. That description is a stack:
import * as alien from "@alienplatform/core"
const files = new alien.Storage("files").build()
const worker = new alien.Worker("worker")
.code({ type: "source", src: "./", toolchain: { type: "typescript" } })
.commandsEnabled(true)
.link(files)
.permissions("execution")
.build()
export default new alien.Stack("remote-worker")
.platforms(["aws", "gcp", "azure"])
.add(files, "frozen") // created at initial setup
.add(worker, "live") // updated on every release
.permissions({ profiles: { execution: { files: ["storage/data-read", "storage/data-write"] } } })
.build()Each resource becomes the cloud's native service. files is an S3 bucket on AWS, a Cloud Storage bucket on Google Cloud, and a Blob Storage container on Azure.
"frozen" and "live" decide which phase owns each resource. See Frozen and live.
Your code
Your code runs inside the customer's environment, so it reaches what only exists there: the bucket, a database in their VPC, an internal API.
import { command, storage } from "@alienplatform/sdk"
import { z } from "zod"
const CountInput = z.object({ prefix: z.string() })
command("count-files", CountInput, async ({ prefix }) => {
const objects = await storage("files").list(prefix)
return { count: objects.length }
})storage("files") is the same call on every cloud and on your laptop. alien dev runs the whole stack locally. See Local development.
Initial setup
Initial setup happens once per deployment. It's the only step that needs the customer's admin.
Create a setup link
A setup link is a URL that starts initial setup for one customer.
alien onboard customer-1The dashboard's Onboard a customer creates the same link, and your backend can create it through the API.
The admin picks a method
The link opens the deployment portal, a branded setup page Alien hosts for the admin. The admin picks CloudFormation, Terraform, Helm, Google login, or a CLI named after your product.
Initial setup runs with the admin's credentials
It creates, inside an isolated area:
- The frozen resources, here the
filesbucket. - A management identity: a cross-account IAM role on AWS, a service account Alien can impersonate on Google Cloud, or a managed identity on Azure. Its permissions come from your stack.
Alien never sees or stores the admin's credentials.
Alien takes over
Alien uses the management identity to create the live resources, here the worker. From now on the deployment is in ongoing management.
It works like sharing one folder in a shared drive. The customer shares the area, Alien manages what's inside, and the customer can revoke access at any time.
Ongoing management
Everything after initial setup is ongoing management. You run one command:
alien releaseAlien then, without the admin:
- Builds your code for every platform in
.platforms(...)and uploads it to the Alien manager, the server that stores releases and tracks every deployment. - Moves the
productionchannel to the new release. Every deployment that follows the channel updates to it. - Creates, updates, and deletes live resources with the management identity.
- Reports health, status, and logs, and runs the commands your backend sends.
The manager runs on alien.dev, or as a Private Manager, a manager you run in your own cloud.
Compare that with handing a customer a Helm chart: every customer ends up on a different version, you see no logs, and every fix waits for them to redeploy.
The two phases
| Initial setup | Ongoing management | |
|---|---|---|
| Who | The customer's admin | Alien |
| When | Once per deployment | Every release, and continuously |
| Credentials | The admin's own, never stored | The management identity created at initial setup |
| Creates or changes | The isolated area, frozen resources, the management identity | Live resources and your code |
| Admin involved | Yes | No |
Your code has a third set of permissions, used at runtime: only what it needs, here read and write on one bucket. See Permissions.
When the admin is needed again
A release that changes what initial setup owns waits for the admin:
- adding, changing, or removing a frozen resource
- changing a permission profile or the management identity's permissions
Alien holds that release for the deployment, which keeps running the previous one. The admin reruns initial setup the same way they ran it the first time, and the release continues. See Changes that need initial setup again.
The isolated area
The customer's account already holds their own databases, services, and networks. Your stack doesn't touch them. Initial setup gives it an isolated area, and your resources live only inside it.
| Platform | Isolated area | What keeps the rest out of reach |
|---|---|---|
| AWS | The resources that share the stack's name prefix | IAM policies scoped to ARNs with that prefix |
| Google Cloud | A project, usually a dedicated one | Project-level IAM |
| Azure | A resource group | Role assignments on that resource group |
| Kubernetes | The namespace the chart is installed in | A namespaced role for the Operator, Alien's agent in the cluster. Cluster-wide only when the chart is built for it. |
Your code can still reach the customer's other systems, such as a database or an internal API, when they allow it. See Network.
Push and pull
A deployment receives releases by push or by pull. You can mix them across customers.
Architecture diagram. Alien manager manages 3 remote environments: push (customer-1 · AWS account), scoped role; pull (customer-2 · Kubernetes), https 443; pull (customer-3 · Linux servers), https 443.
| Push | Pull | |
|---|---|---|
| Who applies the release | The manager, through the cloud's own APIs | The Operator, a small container inside the environment |
| Connection | Cloud APIs with the management identity | Outbound HTTPS from the environment, about every 30 seconds |
| Inbound access | None to the network. Cross-account access to the cloud APIs. | None. No cross-account access either. |
| Used for | AWS, Google Cloud, Azure accounts | Kubernetes clusters, including EKS, GKE, and AKS, and Linux servers |
Both get the same features: releases, health, logs, and commands. If a customer's security team won't allow any outside identity in their account, use pull. For networks with no internet access, see air-gapped deployments.
Calls from your backend
import { CommandsClient } from "@alienplatform/commands"
const commands = await CommandsClient.forDeployment({
deploymentId,
apiKey: process.env.ALIEN_API_KEY!,
})
const input = { prefix: "invoices/" }
const { count } = await commands.invoke<{ count: number }>("count-files", input)A command is a function you wrote, not a shell. The deployment picks it up over an outbound connection, runs your handler next to the bucket, and returns only what the handler returns.
To use a deployment's resources directly from your backend, use remote bindings.
Alien doesn't host your product. Your backend keeps its own stack and calls Alien through the REST API or the TypeScript client.
What Alien can and can't do
Initial setup sets the rules. Alien can:
- Create and update live resources inside the isolated area, within the permissions your stack declares.
- Run your code's commands, invoked by your backend.
- Collect health, logs, and metrics, unless telemetry is turned off for the deployment.
- Run approved operations. With Remote Operator, an outbound-only container in the environment, your team runs named operations, such as restarting a pod, under a time-boxed access request. Every operation is logged.
Alien can't:
- Reach anything outside the isolated area.
- Change or delete frozen resources, or grant itself new permissions.
- Read the customer's secrets. Secrets the customer provides go straight into their own secret store.
- Open a connection into the environment. Every connection starts from inside it, or goes through the cloud's own APIs.
Where data lives
| Data | Where it is stored |
|---|---|
| Customer data in your resources | The deployment, in the customer's environment |
| Customer-provided secrets | The customer's secret store (AWS SSM Parameter Store, Google Secret Manager, Azure Key Vault) |
| Releases and container images | The manager |
| Deployment state and heartbeats | The manager |
| Logs and metrics | The manager, unless telemetry is turned off for that deployment |
Hosted gateways
When your product stays in your cloud, it uses the customer's key, AI models, or sandboxes through APIs Alien hosts. Unlike a deployment, these see the data that passes through them:
| Gateway | What passes through Alien | What Alien records |
|---|---|---|
| Customer-managed keys | The plaintext you encrypt and the plaintext it returns on decrypt. AWS Virtual Keys pass only encrypted data keys. | Request metadata, never values |
| AI Gateway | Prompts and responses, on their way to the customer's provider | Model, provider, status, latency, and token counts, never bodies |
| Sandbox Gateway | Commands, their output, and file contents | Request logs, searchable with alien logs --source remote-sandbox |
When the data itself must not pass through Alien or your cloud, run the code that handles it in a deployment in the customer's environment.
When Alien is unreachable
Deployments keep running if they lose their connection to the manager. Code, resources, and data are unaffected. New releases, commands, and operations wait until the connection returns.
Next
- Quickstart: run initial setup yourself and ship an update.
- Frozen and live: choose which phase owns each resource.
- Deployment UX: what your customer's admin sees during initial setup and after.