Docs

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).

The agent reasons in your cloud and sends tool calls as commands. The worker runs them next to the files, and only the result comes back.

You build a private Worker, serverless code Alien runs in the customer's account, that:

  • Exposes read-file and write-file tools over a bucket there.
  • Lists its tools for your model with list-tools.
  • Runs any tool call through one execute-tool command, 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

alien.ts
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()
  • files is a bucket in the customer's account: S3 on AWS, Cloud Storage on Google Cloud, Blob Storage on Azure.
  • files is 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.
  • worker is live: each release replaces it. See Frozen and live resources.
  • .link(files) lets the Worker use the bucket as storage("files"). The execution profile 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:

src/index.ts
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:

src/index.ts
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:

src/index.ts
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 dev

Locally, 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 local

customer-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-tools contains both tools.
  • A written file reads back as Hello!.
  • An unknown tool rejects.
pnpm test

Call the tools from your agent

Deploy it the usual way:

alien release
alien onboard customer-1 --allow admin@customer-1.com

alien 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:

backend/agent-tools.ts
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

Platformworkerfiles
AWSLambdaS3 bucket
Google CloudCloud RunCloud Storage bucket
AzureContainer AppsStorage account and Blob container
alien devNative processDirectory 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-file accepts 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

On this page