Container

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

Handle to a single container — lifecycle methods + live state.

Role

Consumed — obtain from ContainerRuntime.create or ContainerManager.create. Not implemented by user code.

Remarks

The handle owns one kernel-per-container (Decision #10): calling start() builds the namespace, constructs a fresh kernel, and spawns PID 1. Transitions are validated against the state machine (see state-machine.ts); invalid calls throw ContainerStateError.

The handle is AsyncDisposable — await using c = await mgr.create(...) will stop-then-remove on scope exit.

Invariant

state transitions only via methods on this interface; reading it is a synchronous snapshot and safe at any time.

Invariant

exitCode is undefined until PID 1 exits, then stable for the remainder of the handle’s lifetime.

Invariant

spec is immutable; field-level overrides require a new ContainerRuntime.create call.

Caveat

After remove(), all methods throw (except remove() itself, which is idempotent). The manager also drops the name from its registry, so future get() calls return undefined.

Example

import { createContainerManager, nodeRuntime } from '@fishnet/runtime'

const mgr = createContainerManager((await nodeRuntime()).caps)
const c = await mgr.create(image, { bin: 'ls', argv: ['-la', '/'] })
await c.start()
const code = await c.wait()
c.remove()

See

• ContainerImpl
• ContainerManager
• ContainerState

Extends

• AsyncDisposable

Extended by

• RootContainer

Properties

createdAt

readonly createdAt: number

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

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

---

exitCode

readonly exitCode: ExitCode | undefined

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

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

---

name

readonly name: string

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

Container name — unique within the manager registry.

---

spec

readonly spec: ContainerSpec

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

The spec this container was created from. Frozen.

---

state

readonly state: ContainerState

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

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

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>

Overrides

AsyncDisposable.[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>

---

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.

---

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.

---

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.

---

logs()

logs(): string

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

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

Returns

string

---

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.

---

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>

---

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.

---

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.

---

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.