Docs

Stacks

A stack is what you deploy into each remote environment, written in one file, alien.ts. Alien deploys the same stack everywhere, mapped to each environment's native services.

alien.ts
import * as alien from "@alienplatform/core"

// The customer's documents. Created once, at initial setup.
const documents = new alien.Storage("documents").versioning(true).build()

// Search index the processor writes and the search command reads.
const index = new alien.Kv("index").build()

// Settings your backend writes from your own cloud.
const policies = new alien.Kv("policies").build()

// Extracts text from each new document and indexes it.
const processor = new alien.Worker("processor")
  .code({ type: "source", src: "./processor", toolchain: { type: "typescript" } })
  .trigger({ type: "storage", storage: documents.ref(), events: ["created"] })
  .link(documents)
  .link(index)
  .link(policies)
  .commandsEnabled(true)
  .permissions("processor")
  .build()

Each resource is a builder: new alien.X(id), chained options, then .build(). The id is how permission profiles and your code refer to the resource.

alien.ts default-exports a built Stack. It adds each resource, marks it frozen or live, and grants the Worker access:

alien.ts
export default new alien.Stack("acme-docs")
  .add(documents, "frozen")
  .add(policies, "frozen", { remoteAccess: true })
  .add(index, "live")
  .add(processor, "live")
  .permissions({
    profiles: {
      processor: {
        documents: ["storage/data-read"],
        index: ["kv/data-write"],
        policies: ["kv/data-read"],
      },
    },
  })
  .build()

Frozen resources are created once, at initial setup: the one-time step the customer's admin runs in their account. Alien manages live ones on every release. See Frozen and live.

The running example

The pages in this guide build on this stack, acme-docs, which indexes documents inside each customer's cloud account:

Architecture diagram. acme-docs deployment (documents (Storage), processor (Worker), index (KV), policies (KV)) exchanges traffic with the Your backend (Sign-in, billing, UI, Search page, Policy editor), via via Alien, no inbound.

Your backend reaches each deployment through Alien. Customer documents never leave the customer's account.
  1. Customers upload files to the documents bucket in their account.
  2. The processor Worker extracts the text and writes a search index next to the data.
  3. Your backend, which stays in your cloud, sends the deployment a search command and writes settings into policies.

Sign-in, billing, and the UI stay in your cloud. A hosted backend with a small deployed piece is a common design, not the only one; see Architecture design.

Later pages in this guide change or extend this file.

What a stack declares

PartMethodPage
Computenew alien.Worker, Container, DaemonChoose compute
Resources and linksnew alien.Storage, Kv, Queue, .link()Using resources
Initial setup or ongoing management.add(resource, "frozen" | "live")Frozen and live resources
Per-deployment values.inputs(alien.inputs({...}))Inputs and secrets
Runtime access.permissions({ profiles })Permissions
Access from your backend.commandsEnabled(true), { remoteAccess: true }Commands, Remote bindings
Target platforms.platforms(["aws", "gcp", "azure"])Platforms

Omit .platforms() to allow every platform. Network layout, instance types, and endpoint access are chosen at initial setup, not in alien.ts. See Networking and endpoints.

Project layout

A typical project keeps alien.ts at the root and one folder per compute resource:

alien.ts
package.json
package.json
index.ts

For a TypeScript source, Alien uses main from the folder's package.json, or src/index.ts if main is not set.

Add @alienplatform/core to the root package.json for type checking. The CLI evaluates alien.ts with Bun if it is installed, otherwise with Node.

Readable stacks

The stack is also what your customer's security team reviews. Write it for them:

  • Declare each resource as a named constant, with a one-line comment on why it exists.
  • Name every linked resource in a permission profile, so the grants are explicit. See Permissions.
  • Keep the stack to what must run in the customer's environment. Everything else stays in your own cloud. See Architecture design.

Every builder method and option is listed in the stack reference.

Prompt
Read https://alien.dev/docs/guide/stacks.md and https://alien.dev/docs/guide/design.md. Propose an alien.ts for the part of this codebase that must run next to customer data. Use named constants with comments, and name every linked resource in a permission profile.

Next

Connect your backend

How your backend and each deployment talk to each other, and how browsers reach a deployment without customer content passing through your cloud.

Bring an existing app

Move a product that ships as a Helm chart, docker-compose file, or container images onto Alien, so it deploys and updates in every customer environment from one alien.ts.

On this page

The running exampleWhat a stack declaresProject layoutReadable stacksNext