Run an agent's tools in the customer's cloud
This example builds tools for a hosted AI agent that read and write a customer's files, without the agent ever holding a credential for their cloud. The agent keeps reasoning in your product; its tool calls run next to the files, and only each result comes back.
Architecture diagram. Left: Your cloud, AI agent. Right: Customer cloud containing worker; files (Storage).
You build a private Worker, serverless code Alien runs in the customer's account, that:
- Exposes
read-fileandwrite-filetools over a bucket there. - Lists its tools for your model with
list-tools. - Runs any tool call through one
execute-toolcommand, a named call from your backend.
The same pattern fits any data or service that must stay with the customer: an internal API, a database on their network, or hardware only they have.
Source: examples/remote-worker-ts.
Why not give the agent a credential
The alternatives move the problem instead of solving it:
- A key in your backend can do anything the key allows, from anywhere. The customer has to trust every system that can read it.
- A copy of their files puts their data in two places under two sets of controls.
With remote tools, the callable surface is a fixed list of handlers you wrote and reviewed. The storage credential never exists outside the customer's account: the Worker uses its own cloud identity.
The bucket and the Worker
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")
.add(worker, "live")
.permissions({
profiles: {
execution: {
"*": ["storage/data-read", "storage/data-write"],
},
},
})
.build()filesis a bucket in the customer's account: S3 on AWS, Cloud Storage on Google Cloud, Blob Storage on Azure.filesis frozen. The customer's admin creates it once, during the initial setup (the one-time step with their own credentials), and later releases can't replace or delete it. The data outlives every code change.workeris live: each release replaces it. See Frozen and live resources..link(files)lets the Worker use the bucket asstorage("files"). Theexecutionprofile grants exactly read and write on it, nothing else.- The Worker has no
.publicEndpoint(). Commands are its only way in.
The tools
Each tool is a function with a description your agent can show to the model:
const tools: Record<string, { description: string; execute: (params: any) => Promise<any> }> = {
"read-file": {
description: "Read a file from the customer's private workspace",
execute: async ({ path }: { path: string }) => {
const store = storage("files")
const object = await store.get(path)
return { content: new TextDecoder().decode(object.data) }
},
},
"write-file": {
description: "Write a file to the customer's private workspace",
execute: async ({ path, content }: { path: string; content: string }) => {
const store = storage("files")
await store.put(path, new TextEncoder().encode(content))
return { written: true, path }
},
},
}storage("files") is the same API on every cloud and locally. The code never sees a bucket name, region, or key.
Making the tools callable
One command dispatches to the table, and a second lists it:
command(
"execute-tool",
z.object({ tool: z.string(), params: z.unknown() }),
async ({ tool, params }) => {
const handler = tools[tool]
if (!handler) {
throw new Error(`Unknown tool: ${tool}. Available: ${Object.keys(tools).join(", ")}`)
}
return handler.execute(params)
},
)
command("list-tools", async () =>
Object.entries(tools).map(([name, t]) => ({ name, description: t.description })),
)The zod schema validates the envelope before the handler runs. A thrown error comes back to the caller as a failed command, so the agent sees Unknown tool: ... instead of a silent empty result.
A third command, where-am-i, reports where the Worker is running. It reads environment variables the runtime sets:
command("where-am-i", async () => ({
deploymentId: process.env.ALIEN_DEPLOYMENT_ID ?? null,
platform: process.env.ALIEN_DEPLOYMENT_TYPE ?? null,
account:
process.env.AWS_ACCOUNT_ID ??
process.env.GCP_PROJECT_ID ??
process.env.AZURE_SUBSCRIPTION_ID ??
null,
region: process.env.AWS_REGION ?? process.env.GCP_REGION ?? process.env.AZURE_REGION ?? null,
timestamp: new Date().toISOString(),
}))Run it locally
alien init remote-worker-ts remote-tools
cd remote-tools
alien devLocally, files is a directory under .alien/, and no cloud credentials are needed. In a second terminal, list the tools:
alien dev commands invoke --deployment local-dev/default --command list-tools[
{ "name": "read-file", "description": "Read a file from the customer's private workspace" },
{ "name": "write-file", "description": "Write a file to the customer's private workspace" }
]Write a file and read it back:
alien dev commands invoke --deployment local-dev/default --command execute-tool \
--params '{"tool": "write-file", "params": {"path": "hello.txt", "content": "Hello!"}}'{ "path": "hello.txt", "written": true }alien dev commands invoke --deployment local-dev/default --command execute-tool \
--params '{"tool": "read-file", "params": {"path": "hello.txt"}}'{ "content": "Hello!" }An unknown tool fails:
alien dev commands invoke --deployment local-dev/default --command execute-tool \
--params '{"tool": "delete-everything", "params": {}}'The CLI reports Command 'execute-tool' failed. The handler's error, Unknown tool: delete-everything. Available: read-file, write-file, travels back as the failure reason.
Simulate a second customer
alien dev deploy --name customer-2 --platform localcustomer-2 gets its own Worker and its own storage. Reading hello.txt from local-dev/customer-2 fails, because the file exists only in default's bucket.
In production, the two are separate cloud accounts.
Test it
tests/worker.test.ts deploys the stack locally and checks the same flow:
list-toolscontains both tools.- A written file reads back as
Hello!. - An unknown tool rejects.
pnpm testCall the tools from your agent
Deploy it the usual way:
alien release
alien onboard customer-1 --allow admin@customer-1.comalien onboard creates a setup link, a URL that opens the setup page Alien hosts for the customer's admin. The admin opens it and runs the initial setup once. The Quickstart uses this exact template.
In your backend, wire the remote tools into your agent's tool loop with @alienplatform/commands:
import { CommandsClient } from "@alienplatform/commands"
const commands = await CommandsClient.forDeployment({
deploymentId: customer.deploymentId,
apiKey: process.env.ALIEN_API_KEY!,
})
const worker = commands.target("worker")
// Describe the tools to the model
const tools = await worker.invoke<{ name: string; description: string }[]>("list-tools", {})
// When the model calls a tool, run it in the customer's cloud
const result = await worker.invoke("execute-tool", {
tool: "read-file",
params: { path: "contracts/2026/q3.txt" },
})The model sees tool descriptions and results. Your backend sees only what the tool returns. Neither ever holds the customer's storage credential.
How it works on each platform
| Platform | worker | files |
|---|---|---|
| AWS | Lambda | S3 bucket |
| Google Cloud | Cloud Run | Cloud Storage bucket |
| Azure | Container Apps | Storage account and Blob container |
alien dev | Native process | Directory on disk |
The Worker's role, service account, or managed identity gets read and write on the one bucket.
Removing the deployment keeps the bucket, so a customer never loses files by uninstalling.
Before production
- Give each tool a parameter schema instead of
z.unknown(), so bad calls fail before they reach storage. - Constrain paths.
read-fileaccepts any key in the bucket; scope it to a prefix per user or task if the agent shouldn't see everything. - Return less. Have tools summarize or filter in the customer's cloud, so large files don't flow back through your backend.
- Make write tools idempotent. Commands are delivered at least once.
Next
- Query a private database: the same pattern with a vault and a cache
- Agent or connector
- Commands
- Storage reference
Agent on employee devices
Run a Rust Daemon on each device that watches files, flags sensitive data, keeps events in an encrypted local database, and answers your backend only through commands.
Run in customer Kubernetes
Ship one Rust service to every customer's Kubernetes cluster, including air-gapped sites, with one Helm install per customer and outbound-only updates.