> ## Documentation Index
> Fetch the complete documentation index at: https://yukta.infenia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Control a run
> Pause, resume, step, set breakpoints, skip, stop, restart and retry a live run through one ordered, audited command path, and run the server in the console or in the background.
**Use this when** a run is live and you need to act on it. Every change to a running execution is a **command**. People, supervisors, REST, MCP, the CLI and the web UI all send the same commands through the same pipeline: commands for one run are applied **in the order sent**, the caller's answer arrives after the command was applied, and each one is recorded in the run log with its actor (`key:`, a supervisor id or the UI user).
Pausing freezes every time limit, so a pause never causes a timeout. A stop picks one of three strengths.
**Prerequisites:** add `-H "X-API-Key: $YUKTA_API_KEY"` to every `curl` if your server has keys. Before a command runs, [supervisors](https://yukta.infenia.com/concepts/supervisors.md) may refuse it; a refusal answers `403` and is logged.
## Steps
**1. Create a run that lasts long enough**
Save as `steer.json`. The `wait` node holds each message for 45 seconds, then `go` shapes it:
```json steer.json theme={"system"}
{
"sessionId": "steer", "name": "Steer",
"description": "A slow workflow to practise run controls", "initiator": "docs", "projectPath": "/tmp",
"workflows": {
"slow": {
"workflowId": "slow", "description": "Waits 45 seconds, then finishes",
"nodes": [
{ "nodeId": "start", "type": "API_TRIGGER", "config": {} },
{ "nodeId": "wait", "type": "DELAY", "config": { "delayMs": 45000, "timeoutSeconds": 60 } },
{ "nodeId": "go", "type": "MAPPER",
"config": { "mode": "PROJECTION", "mapping": { "done": "true" } } },
{ "nodeId": "end", "type": "CONSOLE_TERMINAL", "config": {} }
],
"edges": [
{ "source": "start", "target": "wait" },
{ "source": "wait", "target": "go" },
{ "source": "go", "target": "end" }
]
}
}
}
```
```bash theme={"system"}
curl -X POST localhost:9858/api/sessions -H 'Content-Type: application/json' -d @steer.json
EXEC=$(curl -s -X POST localhost:9858/api/workflow/start -H 'Content-Type: application/json' \
-d '{"sessionId":"steer","workflowId":"slow"}' | jq -r .data.executionId)
```
**2. Pause and resume**
Pausing stops the run, or one node, from taking new messages; the message in hand finishes. **All time limits freeze while paused.**
```bash theme={"system"}
curl -s -X POST localhost:9858/api/executions/$EXEC/pause
curl -s -X POST localhost:9858/api/executions/$EXEC/resume
curl -s -X POST localhost:9858/api/executions/$EXEC/nodes/go/pause # one node
```
**3. Step, or stop at a breakpoint**
Step mode holds a node's input so you see one message at a time: enable it, call `step` once per message, disable it to return to normal flow. A breakpoint holds a node **before** the first message whose `payload`, a path such as `payload.order.id`, or a `metadata.key` equals a given text.
```bash theme={"system"}
N=localhost:9858/api/executions/$EXEC/nodes/go
curl -s -X POST $N/step/enable ; curl -s -X POST $N/step ; curl -s -X POST $N/step/disable
curl -s -X POST "$N/breakpoint?field=payload.id&equals=42"
curl -s -X DELETE $N/breakpoint
```
Resume the node to continue past a breakpoint. The call is in the [control API](https://yukta.infenia.com/api/control.md).
**4. Skip a node**
Skipping a **processor** passes messages through it without calling its plugin, from the next message on; a message already inside finishes. Other node kinds reject it. A second call unskips.
```bash theme={"system"}
curl -s -X POST localhost:9858/api/executions/$EXEC/nodes/go/skip
```
**5. Stop the way you mean to**
| Mode | Effect |
| - | - |
| `DRAIN` (default) | Stops the triggers and lets work in flight finish, within `yukta.stop.drain-timeout` (30 s); then it is cancelled |
| `CANCEL` | Cancels every node's subscription at once so plugins can clean up |
| `KILL` | Ends the run at once and removes it; no further commands are accepted for it |
```bash theme={"system"}
curl -s -X POST "localhost:9858/api/executions/$EXEC/stop?mode=CANCEL"
curl -s -X POST "localhost:9858/api/workflow/steer/slow/stop?mode=DRAIN" # every run of a workflow
```
A single node can be stopped too: `POST /api/executions/{id}/nodes/{node}/stop`.
**6. Restart, or retry a node**
| Action | What it does |
| - | - |
| Restart | Runs the whole workflow again with its original start payload |
| Restart from a node | Re-runs that node and everything after it; the recorded outputs of its parents are replayed |
| Retry a node | The same for a node that ended `FAILURE` or `TIMED_OUT`, as a new run |
```bash theme={"system"}
curl -s -X POST localhost:9858/api/executions/$EXEC/restart
curl -s -X POST localhost:9858/api/executions/$EXEC/nodes/go/retry
```
Recent finished runs stay restartable (the newest 10 by default). A node over the replay caps makes a restart refuse rather than replay half. After a server restart, resume instead ([Durability](https://yukta.infenia.com/concepts/durability-and-high-availability.md)). A restart takes a slot like a new start, so it can queue or answer `429`.
## Verify it worked
```bash theme={"system"}
curl -s localhost:9858/api/control/audit
```
lists the commands you sent with their actor and whether each was applied or rejected. A paused run shows `controlState` `PAUSED` in its progress, and its `wait` node does not finish while paused: the 45 seconds do not elapse until you resume. The CLI has the node commands (`yukta-cli workflow node pause|resume|stop|skip|retry|breakpoint|step`) and `workflow executions stop|restart`; MCP has `control_workflow` and `control_node`.
## Who can do what
| Role | Commands |
| - | - |
| `VIEWER` | None, read only |
| `OPERATOR` | Start, pause, resume, step, skip, stop, restart, retry, signal, recover, change a queued priority |
| `ADMIN` | Everything, including defining sessions and changing scheduler limits |
A node that waits for a person is answered through an [input request](https://yukta.infenia.com/concepts/who-decides.md) rather than a control command ([Ask for approval](https://yukta.infenia.com/learn/ask-for-approval.md)).
## Variations
* **Let a supervisor own it.** [Assign a supervisor](https://yukta.infenia.com/guides/supervise/assign-a-supervisor.md) decides who may send which command.
* **Change the queue.** Scheduler limits and a queued run's priority can change while the server runs ([Tune capacity and limits](https://yukta.infenia.com/guides/operate/tune-capacity-and-limits.md)).
## Run the server in the console or in the background
`yukta` shows itself three ways, picked in this order: `--plain`, then `--mode=console|plain|daemon`, then `YUKTA_MODE`.
| Mode | What you get | Default when |
| - | - | - |
| `console` | A full-screen dashboard: version, URL, uptime, health, run counts, recent runs and a log pane | stdin and stdout are a terminal |
| `plain` | Log lines on stdout | not a terminal (service, container, pipe) |
| `daemon` | A detached background process managed with the commands below | only through `yukta start` |
In the console, `q` stops the server, `l` shows full-screen logs, `r` the longer run list, `f` cycles the log level filter and `?` helps. Set `NO_COLOR` for plain text.
```bash theme={"system"}
yukta start # detached, plain mode; waits until /actuator/health answers
yukta status # running or not, pid, URL, health (exit status 3 when stopped)
yukta logs -f # the last 100 lines, then follow
yukta stop # drain, then SIGTERM, then SIGKILL after 30 s
```
State is kept in `$YUKTA_HOME`, else `$XDG_STATE_HOME/yukta`, else `~/.local/state/yukta` (`yukta.pid` and `yukta.log`, not rotated). Use systemd or the container image on servers; do not run `yukta start` inside either ([Deploy](https://yukta.infenia.com/guides/operate/deploy.md)). The daemon commands are for Linux and macOS.
## Related
* [Runs](https://yukta.infenia.com/concepts/runs.md) for the life of a run and its statuses.
* [Control API](https://yukta.infenia.com/api/control.md) and [Status values](https://yukta.infenia.com/reference/status-values.md) for every call and value.
* [Supervisors](https://yukta.infenia.com/concepts/supervisors.md) for who reviews commands.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.