> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idyl.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Target a fleet or node

> Constrain a workload to a fleet you own or to a single node inside its subnet.

By default a workload can run on any eligible node in its subnet, which gives the scheduler the widest capacity pool. Some workloads need a narrower boundary: dedicated capacity you operate as a fleet, or one specific device. Placement targets express that intent, and the scheduler enforces it every time it places or replaces an instance.

The three selectors are mutually exclusive:

```bash theme={null}
idyl apply -f workload.yaml --subnet <subnet>
idyl apply -f workload.yaml --fleet <fleet-id>
idyl apply -f workload.yaml --node <node-id>
```

Every workload still belongs to exactly one subnet. A fleet or node target narrows scheduling inside that subnet — it never moves the workload across subnets, and it never changes routing or policy.

## Target a fleet

A fleet target restricts scheduling to the current members of a fleet you own. Membership is dynamic: nodes added to the fleet become eligible, nodes removed stop receiving new instances, and running instances are not moved.

```bash theme={null}
idyl deploy example.com/inference:1.0 --name inference --replicas 3 --fleet 391742608215
```

The fleet must be yours, active, and assigned to a subnet you can deploy to. The workload is created in that subnet:

```text theme={null}
✓ Deployment inference created
  3 replicas · example.com/inference:1.0 · subnet 100000000001 (fleet 391742608215)
```

In a manifest, placement lives in the pod template spec:

```yaml theme={null}
spec:
  template:
    spec:
      placement:
        fleet: "391742608215"
```

## Target a node

A node target pins the workload to a single device. You do not need to own the node — you need deploy access to a subnet the node serves. This is useful for reproducing a node-specific problem, validating a new device, or diagnostics on capacity another account contributes to your subnet.

Always target the node by its canonical node ID. A provider-defined display
name is presentation metadata and is never a valid value for `--node` or a
manifest placement target.

```bash theme={null}
idyl apply -f node-check.yaml --node <node-id>
```

Node placement trades away scheduling flexibility: if the node is offline or full, the workload stays pending until the node can host it. The scheduler never falls back to the rest of the subnet.

If a node serves more than one of your subnets, pass `--subnet` as well to select which one the workload belongs to.

## Pending targets converge on their own

Acceptance checks only that your request is well formed and that you can deploy to the subnet. Whether the target currently has capacity, compatible runtimes, or any eligible members is a scheduling condition: the workload is accepted, reports why it is pending, and starts without further action once the condition clears.

That makes pre-staging natural — you can target a fleet before assigning it to the subnet, and the workload starts the moment the assignment lands. Pending workloads report placement-specific reasons in their status:

```bash theme={null}
idyl get deployment inference
```

```text theme={null}
Fleet 391742608215 currently has no eligible nodes in subnet 100000000001.
```

## Change a target

Deployments and cron jobs can change placement with a normal edit; the change rolls out as a new revision. Pods, jobs, sandboxes, and virtual machines keep their placement for life — recreate them to retarget. A running instance is never moved just because fleet membership changed; placement is enforced when instances are placed or replaced.