RootContainer

Defined in: packages/runtime/src/container/types.ts:595

Top-level container that owns a live UnixInstance and a ContainerRegistry of child containers.

Role

Consumed — built by the RuntimeAware builder chain. A RootContainer extends Container with nested-container spawn APIs (run(), create()) and direct access to the underlying image / instance.

See

• Container
• ContainerRegistry

Extends

• Container

Properties

containers

readonly containers: ContainerRegistry

Defined in: packages/runtime/src/container/types.ts:601

Child container registry.

---

createdAt

readonly createdAt: number

Defined in: packages/runtime/src/container/types.ts:383

Epoch ms when the handle was constructed (independent of start()).

Inherited from

Container.createdAt

---

exitCode

readonly exitCode: ExitCode | undefined

Defined in: packages/runtime/src/container/types.ts:379

PID-1 exit code. undefined until PID 1 exits.

Inherited from

Container.exitCode

---

image

readonly image: UnixImage

Defined in: packages/runtime/src/container/types.ts:603

The image this root was booted from.

---

instance

readonly instance: UnixInstance

Defined in: packages/runtime/src/container/types.ts:605

The live UnixInstance backing this root container.

---

name

readonly name: string

Defined in: packages/runtime/src/container/types.ts:375

Container name — unique within the manager registry.

Inherited from

Container.name

---

spec

readonly spec: ContainerSpec

Defined in: packages/runtime/src/container/types.ts:381

The spec this container was created from. Frozen.

Inherited from

Container.spec

---

state

readonly state: ContainerState

Defined in: packages/runtime/src/container/types.ts:377

Current lifecycle state. Snapshot — may change concurrently with async ops.

Inherited from

Container.state

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

Defined in: packages/runtime/src/container/types.ts:443

await using cleanup: stop if running, remove if not already removed.

Returns

Promise<void>

Inherited from

Container.[asyncDispose]

---

commit()

commit(): Promise<Layer>

Defined in: packages/runtime/src/container/types.ts:441

Freeze the writable upper layer into a new image layer (Docker commit).

Returns

Promise<Layer>

Inherited from

Container.commit

---

create()

create(image, opts?): Promise<Container>

Defined in: packages/runtime/src/container/types.ts:599

Create a child container (in created state) in this root’s registry.

Parameters

image

UnixImage

opts?

ContainerShorthand

Returns

Promise<Container>

---

drain()

drain(timeout?): Promise<void>

Defined in: packages/runtime/src/container/types.ts:412

Send SIGUSR1 to PID 1 for in-process draining, then fall back to kill on timeout.

Parameters

timeout?

number

Returns

Promise<void>

Invariant

Transitions running → draining → stopped. Timeout defaults to 5000 ms.

Inherited from

Container.drain

---

exec()

exec(bin, argv?, opts?): Promise<ExitCode>

Defined in: packages/runtime/src/container/types.ts:430

Spawn a one-shot process inside the running container.

Parameters

bin

string

argv?

string[]

opts?

ExecOpts

Returns

Promise<ExitCode>

Invariant

Valid only from running. Env layers over the container’s merged env; output is teed into the container log buffer.

Invariant

tty: true toggles raw mode on /dev/cons around the call and restores cooked mode in a finally — safe against mid-exec exit.

Inherited from

Container.exec

---

kill()

kill(): Promise<void>

Defined in: packages/runtime/src/container/types.ts:406

Immediate SIGKILL to PID 1 and all descendants. No grace period.

Returns

Promise<void>

Invariant

Valid from running or draining.

Inherited from

Container.kill

---

logs()

logs(): string

Defined in: packages/runtime/src/container/types.ts:439

Snapshot of the container’s merged stdout/stderr log buffer.

Returns

string

Inherited from

Container.logs

---

remove()

remove(): void

Defined in: packages/runtime/src/container/types.ts:421

Dispose namespace resources and log buffer; transitions to removed.

Returns

void

Invariant

Not valid while running or draining — stop first.

Invariant

Idempotent on removed.

Inherited from

Container.remove

---

restart()

restart(): Promise<void>

Defined in: packages/runtime/src/container/types.ts:414

Stop (if running) then start again. Used by restart policies.

Returns

Promise<void>

Inherited from

Container.restart

---

run()

run(image, opts?): Promise<ExitCode>

Defined in: packages/runtime/src/container/types.ts:597

Shorthand: create + start + wait + remove a child.

Parameters

image

UnixImage

opts?

ContainerShorthand

Returns

Promise<ExitCode>

---

start()

start(): Promise<void>

Defined in: packages/runtime/src/container/types.ts:393

Build the namespace, construct a kernel, spawn PID 1.

Returns

Promise<void>

Invariant

Valid from created, stopped, or failed. Throws from any other state.

Invariant

On restart (from stopped/failed), the prior namespace is disposed and a fresh one is built — log buffer persists.

Inherited from

Container.start

---

stop()

stop(timeout?): Promise<void>

Defined in: packages/runtime/src/container/types.ts:400

Graceful shutdown: SIGTERM → wait timeout ms → SIGKILL on holdouts.

Parameters

timeout?

number

Returns

Promise<void>

Invariant

Idempotent on stopped / failed (returns immediately).

Invariant

Valid from running or draining.

Inherited from

Container.stop

---

wait()

wait(): Promise<ExitCode>

Defined in: packages/runtime/src/container/types.ts:437

Resolve with PID-1’s exit code.

Returns

Promise<ExitCode>

Invariant

If PID 1 already exited, resolves with the cached code. If never started, throws. Otherwise waits for PID 1 to exit.

Inherited from

Container.wait