---
title: "Supervision Trees"
description: "Declare Hew supervisors that own child actors, restart them by strategy, and escalate failures when a restart budget is exhausted."
source: "https://hew.sh/docs/supervision"
---

# Supervision Trees

Supervisors, restart strategies, and restart budgets.

Supervisors build on the [actor model](/docs/actors). For the full lifecycle of a supervised actor, including the `#[on(crash)]` hook, see [Actor Lifecycle and Supervision](/docs/concepts/actor-lifecycle).

## Restart strategies

Supervisors own child actors and manage their lifecycles. When a child , the supervisor decides whether and how to restart it based on the configured strategy:

-   **one\_for\_one:** Only the failed child is restarted
-   **one\_for\_all:** All children are restarted
-   **rest\_for\_one:** The failed child and all children started after it are restarted

Children have restart classifications: `permanent` (always restart), `transient` (restart on abnormal exit), or `temporary` (never restart). The supervisor has a restart budget (`intensity: N within <window>`); exceeding it escalates the failure to the parent supervisor.

Supervision tree

```hew
actor Logger {
    var level: i64 = 0;
    receive fn log(msg: string) { println(msg); }
}
actor CacheActor {
    var capacity: i64 = 0;
    receive fn get(key: string) -> string { "" }
}
actor WorkerActor {
    var id: i64 = 0;
    receive fn work(n: i64) { println(n); }
}
 
supervisor AppSupervisor {
    strategy: one_for_one;
    intensity: 5 within 60s;
 
    child logger: Logger { level: 3 } restart: permanent;
    child cache: CacheActor { capacity: 1024 } restart: permanent;
    child worker: WorkerActor { id: 1 } restart: transient;
}
```

## Accessing supervised children

A supervised child is reached by its declared name through field syntax — `supervisor.child_name`. The compiler resolves the name to a fully typed handle for that child actor at compile time.

Named child access

```hew
actor Counter {
    var start: i64 = 0;
    receive fn tick() { start += 1; println(start); }
}
 
actor Logger {
    var level: i64 = 0;
    receive fn log() { println(f"log level {level}"); }
}
 
supervisor ServiceTree {
    strategy: one_for_one;
    intensity: 5 within 60s;
 
    child counter:   Counter { start: 100 };
    child debug_log: Logger { level: 1 };
    child error_log: Logger { level: 3 };
}
 
fn main() {
    let svc = spawn ServiceTree;
    sleep(50ms);
 
    let c = svc.counter;
    c.tick().expect("actor stopped");
 
    let dlog = svc.debug_log;
    dlog.log().expect("actor stopped");
 
    stop(svc);
    stopped(svc);
}
```

## rest\_for\_one strategy

`rest_for_one` restarts the crashed child and all children declared after it. This models dependency order: if a database connection crashes, the API handler that depends on it must also restart.

rest\_for\_one — dependency-aware restarts

```hew
actor Cache {
    var capacity: i64 = 0;
    receive fn get(key: string) -> string { "" }
}
actor Database {
    var connections: i64 = 0;
    receive fn query(sql: string) -> string { "" }
}
actor ApiHandler {
    var port: i64 = 0;
    receive fn handle(req: string) -> string { "" }
}
 
// Child order matters: cache -> db -> api
// If db crashes, db AND api restart (api depends on db).
// If cache crashes, cache, db AND api restart in declaration order.
supervisor ServiceStack {
    strategy: rest_for_one;
    intensity: 5 within 60s;
 
    child cache: Cache { capacity: 1000 } restart: permanent;
    child db: Database { connections: 4 } restart: permanent;
    child api: ApiHandler { port: 8080 } restart: transient;
}
```

## Nested supervisor trees

A declared child may itself be a supervisor. Each level owns its restart policy and budget; an exhausted inner supervisor reports its failure to its parent. Child access follows the declared tree and returns the current stable role.

Nested supervisors

```hew
actor Worker {
    let id: i64;
    receive fn get() -> i64 { id }
}
 
supervisor WorkerPool {
    strategy: one_for_one;
    intensity: 3 within 60s;
    child first: Worker { id: 1 } restart: permanent;
    child second: Worker { id: 2 } restart: permanent;
}
 
supervisor Application {
    strategy: one_for_one;
    intensity: 5 within 60s;
    child workers: WorkerPool;
}
 
fn main() {
    let app = spawn Application;
    println(app.workers.first.get().expect("worker stopped"));
}
```

## Continue from here

-   Look up exact policies and lifecycle APIs in the [released supervision reference](https://docs.hew.sh/language.supervision.html).
-   Compare the model with Erlang/OTP and Go in the [supervision comparison](/docs/compare/supervision).
-   Try a supervised restart in the [recovery exercise](/try/recovery/).
