---
slug: cli/spawn
title: afy spawn — starting an Aetherfy child agent from a parent
kind: reference
surface: cli
summary: Reference for afy spawn in the Aetherfy CLI — the two required arguments, the mutually exclusive --payload, --payload-file and --stdin flags, the four spawn requirements, the output keys, and why spawned runs do not appear in afy agents runs.
sources:
  - aetherfy-cli:cmd/spawn.go
  - aetherfy-cli:internal/api/agents.go
---

# afy spawn

## Spawning an Aetherfy child agent

`afy spawn <parent-agent> <child-agent>` starts a `type: job` agent on behalf of
a parent agent. It takes exactly two positional arguments: the parent first, the
child second.

```bash
afy spawn orchestrator page-worker
```

The spawned Aetherfy agent runs once and terminates. This is the fan-out
primitive: a long-running parent dispatches units of work to short-lived
children, each with its own payload.

## Flags accepted by afy spawn in the Aetherfy CLI

| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| `--payload` | `-p` | string | empty | JSON payload to pass to the spawned agent |
| `--payload-file` | `-f` | string | empty | Read payload from JSON file |
| `--stdin` | | bool | false | Read payload from stdin |

All three payload flags are **mutually exclusive** — pass at most one.

There is no `--wait` flag on `afy spawn`. Unlike `afy agents run --wait`, the
Aetherfy CLI cannot block on a spawned run; it returns as soon as the spawn is
accepted.

## Passing a payload to an Aetherfy spawned agent

```bash
# Inline JSON
afy spawn orchestrator page-worker --payload '{"url":"https://example.com/4","depth":2}'

# From a file
afy spawn orchestrator page-worker --payload-file ./task.json

# From stdin — useful when the payload is generated upstream
echo '{"url":"https://example.com/4"}' | afy spawn orchestrator page-worker --stdin
```

Spawning with no payload at all is valid:

```bash
afy spawn orchestrator page-worker
```

## Requirements for an Aetherfy spawn to succeed

Four conditions must hold, or Aetherfy rejects the spawn.

| Requirement | Detail |
|---|---|
| Parent has spawning enabled | `spawn.enabled: true` in the parent's `aetherfy.yaml` |
| Child is a task agent | The child must be declared `type: job` |
| Neither agent is paused | A parent or child paused with `afy agents stop` cannot spawn or be spawned |
| Child is an allowed worker | If the parent declares `spawn.workers`, the child must appear in that list |

The parent side of the contract, in `aetherfy.yaml`:

```yaml
name: orchestrator
type: service
runtime: python3.12
entrypoint: main.py
spawn:
  enabled: true
  workers:
    - page-worker
    - summariser
```

Spawning can also be enabled at creation time with
`afy agents create <name> --spawn-enabled`, and the current setting is shown as
`Spawn Enabled` in `afy agents status <name>`. See [/cli/agents](/cli/agents).

## Output of afy spawn in the Aetherfy CLI

`afy spawn` honours the global `-o json`.

| Key | Meaning |
|---|---|
| Spawn ID | The identifier of this spawn |
| Deployment ID | The child deployment the spawn ran against |
| Machine ID | The machine running the spawned agent — printed only when present |
| Status | The state of the spawn as accepted by Aetherfy |

```bash
afy spawn orchestrator page-worker -o json
```

## Observing an Aetherfy spawned run

Spawned runs are deliberately **not** listed by `afy agents runs <child>`. They
belong to the parent's history, not the child's, so the child's run list stays a
record of its own scheduled and manual runs.

To see what a spawned Aetherfy agent did, read its logs:

```bash
afy logs page-worker
afy logs page-worker --follow
afy logs page-worker --level ERROR --since 30m
```

Log filters and the follow-mode caveats are documented on
[/cli/logs](/cli/logs).

## Choosing between afy spawn and afy agents run on Aetherfy

Both start a `type: job` Aetherfy agent once. They differ in who is doing the
starting and in whether you can wait.

| | `afy spawn <parent> <child>` | `afy agents run <agent>` |
|---|---|---|
| Arguments | Parent and child | One agent |
| Requires a parent relationship | Yes | No |
| Requires `spawn.enabled` on a parent | Yes | No |
| Payload flags | `--payload`, `--payload-file`, `--stdin` | `--payload`, `--payload-file` |
| Can block on the result | No — there is no `--wait` | Yes — `--wait`, polling up to 30 minutes |
| Appears in `afy agents runs` for that agent | No | Yes |

Use `afy agents run` to trigger a task agent yourself. Use `afy spawn` to model
fan-out, where one Aetherfy agent dispatches work to another.

Note that `afy spawn` prints an `Error:` line and still exits 0 on failure, so a
script must inspect the output rather than the exit status. The full exit-code
table for the Aetherfy CLI is on [/cli](/cli).