Store files in each customer's own bucket
This example builds "bring your own bucket" for a hosted product: each customer's files live in a bucket in their own cloud account. The customer gets data residency, their own retention policies, and one bucket to delete; you get one Storage API across S3, Google Cloud Storage, and Azure Blob Storage.
Architecture diagram. Left: Your cloud containing Your backend, @alienplatform/bindings, short-lived credentials. Right: Customer 1's cloud account containing byob-storage deployment containing uploads bucket.
What you build:
- A dedicated bucket in each customer's account, created once during their initial setup (the one-time step their admin runs with their own credentials), plus a role that can only work with objects in it.
- Backend code that writes, reads, lists, and deletes files with short-lived credentials.
- No Worker, Container, or sidecar in the customer's cloud.
Source: examples/byob-storage-ts.
The common alternative is an access key per customer. The customer creates a bucket and an IAM user or service account, then pastes the credentials into your settings page. You then store long-lived credentials for every customer, maintain three storage clients, and debug a hand-written bucket policy per customer.
The bucket
import * as alien from "@alienplatform/core"
const uploads = new alien.Storage("uploads").build()
export default new alien.Stack("byob-storage")
.add(uploads, "frozen", { remoteAccess: true })
.build()alien.Storage("uploads") is a portable object store: an S3 bucket on AWS, a Cloud Storage bucket on Google Cloud, and a Blob Storage container on Azure.
The bucket is "frozen" (created at initial setup, never replaced by a release) because the customer owns it. The initial setup creates it with the customer admin's credentials.
A release from you can't replace or delete it, so a bad release can't destroy a customer's files. Changing its configuration later requires the admin to run initial setup again. See Frozen and live.
{ remoteAccess: true } is an explicit security choice. It tells the initial setup to create a separate cloud identity for remote bindings in the customer's account, trusted by Alien, with object permissions on this one bucket:
| Cloud | Bucket | Remote role permissions |
|---|---|---|
| AWS | S3 bucket | s3:ListBucket, s3:GetBucketLocation, s3:ListBucketMultipartUploads on the bucket; s3:GetObject, s3:PutObject, s3:DeleteObject, s3:AbortMultipartUpload, s3:ListMultipartUploadParts on its objects |
| Google Cloud | Cloud Storage bucket | storage.objects.get, .list, .create, .delete on the bucket |
| Azure | Blob container | Blob read, write, and delete data actions on the container |
The role can't change the bucket's policy, lifecycle, or encryption, and it can't reach any other resource in the customer's account. The admin can read the exact grants first: the Terraform package ships them in PERMISSIONS.md, and the CloudFormation template shows them inline.
The initial setup always creates a new bucket. This example can't attach a bucket the customer already has.
Use it from your backend
src/vendor.ts is the backend side. It runs wherever your product runs:
import { Bindings } from "@alienplatform/bindings"
function requiredEnvironmentVariable(name: string): string {
const value = process.env[name]
if (!value) {
throw new Error(`${name} is required`)
}
return value
}
const bindings = await Bindings.forRemoteDeployment({
deploymentId: requiredEnvironmentVariable("ALIEN_DEPLOYMENT_ID"),
token: requiredEnvironmentVariable("ALIEN_API_TOKEN"),
})
const uploads = bindings.storage("uploads")
const objectPath = "hello.txt"
await uploads.put(objectPath, new TextEncoder().encode("hello from the vendor backend"))
const head = await uploads.head(objectPath)
const object = await uploads.get(objectPath)
const objects = await uploads.list()
console.log({
head,
contents: new TextDecoder().decode(object.data),
objects,
})
await uploads.delete(objectPath)Bindings.forRemoteDeployment finds the deployment's manager and prepares bindings for it. bindings.storage("uploads") uses the resource ID from alien.ts.
On the first call, the binding asks Alien for credentials for the remote role: an AWS session, a Google Cloud access token, or an Azure storage token. It then talks to the bucket with them. Credentials last about an hour, and the binding refreshes them five minutes before they expire, so a long-running backend can keep one Bindings object.
A remote Storage binding supports these operations:
| Method | Returns |
|---|---|
put(path, data, options?) | { eTag?, version? }. options.attributes sets content type, cache control, and custom metadata. options.condition: "absent" writes only if the path doesn't exist. |
get(path) | { data, meta, attributes }, where data is a Buffer |
head(path) | { meta, attributes } without downloading the object |
list(prefix?) | An array of { location, size, lastModified, eTag?, version? } |
delete(path) | Nothing |
copy and signedUrl are not available on remote bindings. They exist on the Storage binding inside a deployment.
Alien checks every credential request before it issues anything. It refuses a read-only Alien token, a token for another deployment, a resource that isn't running, and a resource without remoteAccess.
Release and onboard a customer
Scaffold the example and publish a release:
alien init byob-storage-ts customer-storage
cd customer-storage
pnpm install
alien releaseYou can't run this example with alien dev. Remote bindings exist only on AWS, Google Cloud, and Azure deployments, because the point is a bucket in another account. Use a test cloud account as your first customer.
Create a setup link and send it to the customer's cloud admin. A setup link is a URL that opens the deployment portal, the setup page Alien hosts for the admin. --external-id is the ID your own product uses for this customer:
alien onboard "Customer 1" --allow admin@customer-1.com --external-id customer-1The admin creates a deployment from your release and runs the initial setup with the method that fits them:
alien-deploywith their cloud credentials;- the generated Terraform module; or
- on AWS, the generated CloudFormation stack.
Every method creates one bucket or container and one remote bindings identity, then registers them with Alien. The bucket must reach running before your backend can use it. See Follow a deployment.
Run the backend script
Find the deployment ID with alien deployments ls, create a token for it, and run the script:
alien deployments token <deployment-id>
export ALIEN_DEPLOYMENT_ID=<deployment-id>
export ALIEN_API_TOKEN=<token>
pnpm run run:vendorrun:vendor compiles the TypeScript with tsc and runs dist/src/vendor.js. The script:
- Writes
hello.txt. - Prints its metadata, its contents (
hello from the vendor backend), and the bucket listing. - Deletes it.
Open the bucket in the customer's cloud console while the script runs to see the object appear and disappear.
Per-cloud behavior
| AWS | Google Cloud | Azure | |
|---|---|---|---|
| Resource | S3 bucket | Cloud Storage bucket | Blob Storage container |
| Credentials your backend receives | AWS session for the remote role | Access token for the remote bindings identity | Storage-audience access token |
put with contentEncoding: "gzip" | Stored as sent | Rejected: Cloud Storage transcodes gzip on read | Stored as sent |
version and eTag in head and list results are optional: they are set only when the provider reports them.
Before production
- Store one deployment per customer. Save the deployment ID next to the customer in your database. Or address customers by your own ID with
Bindings.forRemoteCustomer({ project, externalId, token })and a project API key created withalien api-keys create --for remote-bindings. - Keep tokens on the server. Never send the Alien token, or the cloud credentials it returns, to a browser, mobile app, or logs. Since
signedUrlisn't available remotely, stream uploads and downloads through your backend. - Decide the bucket's settings up front. The bucket is frozen, so settings such as
.versioning(true),.lifecycleRules([...]), and.encryptionKey(key)take another run of the initial setup to change. Set them before the first customer. - Encrypt with the customer's key. Add a frozen
alien.KeywithoutremoteAccessand pass it to.encryptionKey(key). The bucket is then encrypted at rest with a key in the customer's key service. See Customer-managed keys. Don't also publish the key withremoteAccesshere: a remote key must be its stack's only remote resource, as in Customer keys. - Handle a missing deployment. Treat "no running deployment" as a normal state for customers who haven't finished the initial setup, and keep using your own storage for them.
The storage setup item deploys a stack equivalent to this example: one frozen Storage resource opted into remote access. See Customer storage settings.
The customer can remove your access at any time by deleting what initial setup created.
Adapt it
Next
Use the customer's models
Release a stack with one AI resource, let each customer connect Bedrock or Vertex AI, and call their models from your hosted backend through the AI Gateway.
Custom Remote Operator operations
Write a Rust plugin with one read-only and one mutating operation against your application's admin API, then publish it and run it in customer deployments.