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:
- You create a setup link for the customer that allows the
machinesplatform. - Their admin opens it in the portal and clicks Set up machines.
- The portal shows the join command. The admin runs it on each machine.
- 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.
Send the customer a setup link
From the CLI:
alien onboard customer-1 --platforms machinesWith --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:
- Picks On-prem, then Compute → Your machines.
- Clicks Set up machines.
- 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.
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:
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.
drainRequestedAtis set anddrainedAtisn'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:
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_64orarm64, and root orsudo. 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 withdnf install -y containerd wireguard-tools nftables.- Outbound HTTPS to Alien and to your package domain. No inbound port from the internet.
- UDP
51820open between their machines. - The CPU, memory, and disk your pool requires.
joinchecks them, andjoin --dry-runprints the plan without installing anything.
Test the flow yourself
- Run
alien onboard test-customer --platforms machinesand open the link. - Click Set up machines and run the command on a Linux VM you own.
- Confirm your product lists the machine as
ready, then runsudo acmectl leave --purgeon the VM and watch it disappear from the list.
Next
- Releases and operations: what happens after the machines join
- Brand the portal: your name, colors, and domain on the portal and the CLI
- Deployment portal: every step the admin sees
Quickstart
Build a Rust job worker from source, run it on a Linux machine you own, then ship a new version while a job runs and roll back.
Workloads
What runs on bare metal and on-prem machines: daemons with host access, stateless containers, pools, data resources, and public endpoints with managed TLS.