Docs

Add to your product

A customer's on-prem machines join a deployment the same way your own machines do, but their admin runs the join command. You send the admin to the deployment portal, the branded setup page Alien hosts for your customers, and the portal gives them the command for your white-labeled setup CLI.

curl -fsSL 'https://pkg.acme.dev/acme/edge/install.sh' | sudo bash -s -- join --token 'aj1_...'

The flow, with a link you send or a button in your product:

  1. You create a setup link for the customer that allows the machines platform.
  2. Their admin opens it in the portal and clicks Set up machines.
  3. The portal shows the join command. The admin runs it on each machine.
  4. Each machine connects out to Alien, and your product lists it.

Sequence diagram. Lanes: Your backend (your product), Alien (api.alien.dev), Customer machines (their network). Steps: 1 · create setup link; admin opens the portal; 2 · join, outbound; 3 · releases, pulled; 4 · machines, health.

The customer's admin never gives you SSH keys, VPN access, or an inventory. Their machines only open outbound HTTPS to Alien.

Brand the setup CLI

The join command installs your setup CLI: the Alien deploy CLI, white-labeled and built for each release under your command name. These docs call it acmectl. On the customer's machine, the admin runs acmectl join and later acmectl leave.

In project Settings → Artifacts → CLI, set:

  • Command name, such as acmectl, and Display name, which the CLI's help shows.
  • Under Advanced → Platforms, Linux · x64 and Linux · ARM64.

With a custom domain, the install script is served from pkg.<your domain>, as in the command above. See Setup packages.

From the CLI:

alien onboard customer-1 --platforms machines

With --platforms machines, the link offers only machines, not a cloud account or a cluster. Onboard a customer in the dashboard creates the same link.

In the portal, the admin:

  1. Picks On-prem, then Compute → Your machines.
  2. Clicks Set up machines.
  3. Copies the command from Connect machines and runs it on each machine, as root or with sudo.

Connect machines lists each machine as it joins, with its zone and last heartbeat. Generate new command issues another token and keeps the existing ones working.

Open the portal from your product

This runs on your backend, in the route behind a button such as Connect machines. Create the setup link with only machines allowed, then open it in a new tab. The client comes from Set up a client.

lib/connect-machines.ts
import { alien, PROJECT } from "./alien"

export async function connectMachinesLink(org: { id: string; slug: string }) {
  const link = await alien.setupLinks.create({
    project: PROJECT,
    externalId: org.id, // from the session, never from the request
    name: org.slug,
    maxDeployments: 1,
    setupItems: [{ item: "deployment", required: true }],
    deploymentSetupConfig: { policy: { allowedPlatforms: ["machines"] } },
  })
  return { deploymentGroupId: link.deploymentGroup.id, url: link.deploymentLink }
}

Save deploymentGroup.id on the organization. Add a Deploy button covers the rest of this option: who clicks, expired links, and finding the deployment when they come back.

Show their machines

This runs on your backend. Once the deployment exists, list its machines with GET /v1/deployments/{id}/machines:

lib/machines.ts
import { alien } from "./alien"

export async function listMachines(deploymentId: string) {
  const { machines } = await alien.deployments.listMachines({ id: deploymentId })
  return machines.map((m) => ({
    id: m.machineId,
    status: m.status,
    zone: m.zone,
    lastHeartbeat: m.lastHeartbeat,
    draining: Boolean(m.drainRequestedAt && !m.drainedAt),
  }))
}
  • No machines yet. The deployment is waiting-for-machines. Show the admin the portal link again, where the join command is.
  • Stale heartbeat. A machine without a heartbeat for 5 minutes is offline. It keeps running its last release, so say "not reporting", not "down".
  • Draining. drainRequestedAt is set and drainedAt isn't. The machine is moving its work off before it leaves.

Give a new join command

To let an admin add machines later from your product, create a token with POST /v1/machines/deployments/{id}/join-tokens. Existing tokens keep working:

lib/join-command.ts
import { alien } from "./alien"

export async function joinCommand(deploymentId: string) {
  const t = await alien.machines.createJoinToken({ id: deploymentId })
  return t.cliInstallScriptUrl
    ? `curl -fsSL '${t.cliInstallScriptUrl}' | sudo bash -s -- join --token '${t.joinToken}'`
    : `sudo ${t.cliCommandName ?? "alien-deploy"} join --token '${t.joinToken}'`
}

The token is returned once and works for up to 100 machines for 7 days, or until it's revoked. Show the command only to signed-in members of that organization, and revoke the token with DELETE /v1/machines/deployments/{id}/join-tokens/{tokenId} once their machines have joined. See Join tokens.

What the customer's IT team needs

Send this to the customer's IT team before they run the command:

  • Linux with systemd, on x86_64 or arm64, and root or sudo.
  • containerd, wireguard-tools, nftables, and the WireGuard kernel module. On Debian and Ubuntu, the machine agent installs the packages. On Fedora, RHEL, or Amazon Linux, install them first with dnf install -y containerd wireguard-tools nftables.
  • Outbound HTTPS to Alien and to your package domain. No inbound port from the internet.
  • UDP 51820 open between their machines.
  • The CPU, memory, and disk your pool requires. join checks them, and join --dry-run prints the plan without installing anything.

Test the flow yourself

  1. Run alien onboard test-customer --platforms machines and open the link.
  2. Click Set up machines and run the command on a Linux VM you own.
  3. Confirm your product lists the machine as ready, then run sudo acmectl leave --purge on the VM and watch it disappear from the list.

Next

On this page