Docs

Hello world

This example builds the smallest service that runs in a customer's cloud: a Worker (serverless code) with one HTTPS route and one command, a named call your backend makes into the deployment. It goes from your laptop to the customer's AWS, Google Cloud, or Azure account without opening a port into their network.

Architecture diagram. Left: Your cloud, Your backend, alien CLI. Right: Customer cloud containing agent (Worker).

Your backend calls the echo command through Alien. Anyone with the URL can call GET /health on the public endpoint.

What you build:

  • A Worker with a public GET /health route and an echo command.
  • A local run with alien dev and a test with @alienplatform/testing.
  • A release that a customer's admin sets up once, and a call to it from your backend afterwards.

The later examples put real work behind the same path. Source: examples/basic-worker-ts and the Rust variant examples/basic-worker-rs.

The Worker

alien.ts describes what each deployment gets. Here it is one Worker:

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

const agent = new alien.Worker("agent")
  .code({ type: "source", src: "./", toolchain: { type: "typescript" } })
  .commandsEnabled(true)
  .publicEndpoint("api")
  .permissions("execution")
  .build()

export default new alien.Stack("basic-worker")
  .add(agent, "live")
  .permissions({
    profiles: {
      execution: {},
    },
  })
  .build()

Each line is a decision:

  • .code({ type: "source", ... }) tells Alien to build the Worker from this folder. The typescript toolchain bundles src/index.ts; the rust toolchain builds the binary named basic-worker from Cargo.toml.
  • .commandsEnabled(true) lets the Worker receive commands. Without it, command() handlers never run.
  • .publicEndpoint("api") gives the Worker an HTTPS hostname, api.<deployment-domain> by default. Drop it and the Worker is private: reachable only through commands and triggers.
  • .permissions("execution") assigns the execution permission profile. It's empty because the Worker touches no other resources. Alien turns profiles into IAM roles, service accounts, or managed identities per cloud. See Permissions.
  • "live" means Alien replaces the Worker on every release, with no action from the customer's admin. See Frozen and live resources.

The stack declares no .platforms(...), so every platform is allowed.

A Worker is Alien's stateless, event-driven compute. The same Worker can serve HTTP, handle commands, and react to queue messages, storage events, and schedules. See How it runs on each platform.

The handlers

src/index.ts
import { command } from "@alienplatform/sdk"
import { Hono } from "hono"

const app = new Hono()

app.get("/health", c => {
  return c.json({
    status: "ok",
    timestamp: new Date().toISOString(),
  })
})

command("echo", async params => {
  return {
    ...params,
    timestamp: new Date().toISOString(),
  }
})

export default app

The default export is the HTTP app. Any framework with a fetch-style handler works; this example uses Hono.

command() from @alienplatform/sdk registers a handler by name. Its return value goes back to the caller as JSON. echo returns the parameters it received plus a timestamp.

Command or endpoint

The two entry points solve different problems:

  • GET /health is an ordinary HTTPS route. Anyone who can reach the endpoint can call it. Use public routes for traffic that starts outside your product, such as a browser or a webhook sender.
  • echo is a command: a named request from your backend to one deployment. It travels through Alien and runs the handler inside the customer's environment. The customer opens no inbound port, VPN, or network peering, and only the handlers you write can run.

If you remove the public endpoint, echo still works. Commands are one common way in; later examples also start work from queues, file uploads, and schedules.

Run it locally

alien dev runs the whole stack on your machine. You need Docker running, and Bun for TypeScript. No cloud account.

alien init basic-worker-ts my-worker
cd my-worker
alien dev

alien init downloads the template and installs dependencies. If no package manager is found, run pnpm install yourself.

alien dev runs the whole release path on your machine:

  1. Starts a local Alien manager (the service that stores releases and deploys them).
  2. Builds the Worker and creates a release.
  3. Deploys it as a deployment named default in the local deployment group local-dev. A deployment group is Alien's record of one customer or environment.
  4. Prints the Worker's URL. Keep it running.

Call the HTTP route with the printed URL:

curl <url>/health
{ "status": "ok", "timestamp": "2026-10-24T12:00:00.000Z" }

In a second terminal, invoke the command:

alien dev commands invoke \
  --deployment local-dev/default \
  --command echo \
  --params '{"hello": "world"}'
{
  "hello": "world",
  "timestamp": "2026-10-24T12:00:01.000Z"
}

--deployment takes <group>/<name> or a deployment ID. The CLI waits up to 60 seconds for the result (--timeout changes it) and prints it as JSON.

The Rust Worker returns { "hello": "world" }.

Test it

Both variants include the same test. @alienplatform/testing deploys the stack to a local manager, then calls both entry points:

tests/agent.test.ts
import { type Deployment, deploy } from "@alienplatform/testing"
import { afterAll, beforeAll, describe, expect, it } from "vitest"

describe("basic-worker-ts", () => {
  let deployment: Deployment

  beforeAll(async () => {
    deployment = await deploy({ app: ".", platform: "local" })
  }, 300_000)

  afterAll(async () => {
    await deployment?.destroy()
  })

  it("should respond to health check", async () => {
    const response = await fetch(`${deployment.url}/health`)
    expect(response.ok).toBe(true)

    const data = await response.json()
    expect(data.status).toBe("ok")
    expect(data.timestamp).toBeDefined()
  })

  it("should execute echo command", async () => {
    const result = await deployment.invokeCommand("echo", { message: "hello" })
    expect(result.message).toBe("hello")
    expect(result.timestamp).toBeDefined()
  })
})

Run it with:

pnpm test

The first deploy() builds the Worker, so the setup timeout is five minutes. See Testing.

Deploy to a customer

To run the same Worker in a real account, you play two roles: the developer who releases, and the customer's admin who runs the initial setup: the one-time step in their account, with their own credentials.

alien login
alien link
alien release
alien onboard customer-1 --allow admin@customer-1.com
  1. alien release builds the Worker for each platform and moves the production release channel to the new release. Deployments follow a channel.
  2. alien onboard customer-1 creates a deployment group for the customer and prints a setup link, a URL for the customer's admin.
  3. The link opens the deployment portal, the branded setup page Alien hosts. The admin picks a cloud and runs the initial setup with their own credentials.

You can also start initial setup from your own product, where your backend creates setup links through the API. See Deployment UX for the options. After the initial setup, the Worker runs in that account as Lambda, Cloud Run, or Container Apps, and the CLI reaches it the same way:

alien commands invoke \
  --deployment customer-1/customer-1 \
  --command echo \
  --params '{"hello": "from my backend"}'

From then on, Alien manages the deployment: later releases reach it without the admin doing anything. The Quickstart walks through this flow step by step.

Call it from your backend

The CLI is for testing and support. Your product calls the same API with @alienplatform/commands:

backend/echo.ts
import { CommandsClient } from "@alienplatform/commands"

const commands = await CommandsClient.forDeployment({
  deploymentId: customer.deploymentId,
  apiKey: process.env.ALIEN_API_KEY!,
})

const result = await commands
  .target("agent")
  .invoke("echo", { hello: "from my backend" })

.target("agent") names the resource that hosts the handler. Keep the API key on your server. Create one with alien api-keys create --for deployments.

How it runs on each platform

Platformagent runs asPublic endpoint
AWSLambda (ARM64 container image)api.<deployment-domain>
Google CloudCloud Runapi.<deployment-domain>
AzureContainer Appsapi.<deployment-domain>
KubernetesDeployment and Serviceapi.<deployment-domain>
alien devNative processLocal URL printed by alien dev

Commands reach the Worker in one of two ways:

  • Push deployments: Alien invokes the Worker through the cloud's API.
  • Pull deployments, such as Kubernetes: the Operator (a small Alien process in the environment) relays the command.

Either way the customer's environment accepts no inbound connection from you. See Push, pull, and air-gapped and How delivery works.

Before production

  • Replace echo with a narrow operation, such as search-documents or generate-report, that does the work next to the customer's data and returns only the fields your product needs.
  • Validate parameters with a schema: command("name", z.object({...}), handler). See Commands.
  • Remove .publicEndpoint("api") if nothing outside your backend needs HTTP. A public route is reachable by anyone who can reach the customer's endpoint, so authenticate it yourself.

Next

On this page