process

cwd?: string

Working directory for the child process.

When omitted, the child inherits the parent's current working directory. If the directory cannot be entered during spawn setup, construction throws before a child process is returned.

import type { ProcessOptions } from 'fino:process';

const opts: ProcessOptions = { cwd: '/srv/app' };

env?: Record<string, string>

Environment passed to the spawned process.

When omitted, the runtime startup environment snapshot is used. Supplying this object replaces, rather than merges with, the inherited environment.

import type { ProcessOptions } from 'fino:process';

const opts: ProcessOptions = { env: { PATH: '/usr/bin', NODE_ENV: 'test' } };

sandbox?: ProcessSandboxOptions

Optional sandbox request for this child process.

The sandbox API is capability-reported. strict mode requests an OS-enforced security boundary installed before the child runs and fails closed when the platform cannot enforce every requested category. bestEffort mode may spawn the child without enforcing requested policy categories, but the returned Process.sandboxReport records exactly what happened.

import { Process, type ProcessOptions } from 'fino:process';

const opts: ProcessOptions = {
  sandbox: {
    mode: 'bestEffort',
    resources: { memoryBytes: 64 * 1024 * 1024 }
  }
};
const proc = new Process('/bin/echo', ['hello'], opts);
console.log(proc.sandboxReport.enforced.length);

mode: 'strict' | 'bestEffort'

Requested sandbox mode.

strict is a security-boundary request and fails closed unless a strict backend can enforce the policy before child code runs. bestEffort is not a security boundary; it only reports the platform/backend subsets that were enforced.

resources?: ProcessSandboxResources

Resource limits requested for the child and descendants.

filesystem?: ProcessSandboxFilesystem

Filesystem access policy requested for the child.

network?: ProcessSandboxNetwork

Network access policy requested for the child.

process?: ProcessSandboxProcessPolicy

Process creation and execution policy requested for the child.

syscalls?: ProcessSandboxSyscalls

Syscall policy requested for the child.

memoryBytes?: number

Maximum resident or cgroup memory in bytes when the backend supports an enforcing memory limit.

pids?: number

Maximum process count when the backend supports PID-count limits.

cpu?: number

CPU quota as a fraction where 1 means one full CPU.

writable?: string[]

Writable absolute paths requested inside the sandbox view.

readonly?: string[]

Readonly absolute paths requested inside the sandbox view.

outbound?: ProcessSandboxNetworkRule[]

Outbound connect rules.

inbound?: ProcessSandboxNetworkRule[]

Inbound bind/listen rules.

action: 'allow' | 'deny'

Whether matching traffic should be allowed or denied.

destination?: string

Destination host, IP, CIDR, or *, depending on backend support.

port?: number

TCP or UDP port.

protocol?: 'tcp' | 'udp'

Network protocol covered by the rule.

allowFork?: boolean

Whether the child may fork or clone additional processes.

allowExec?: boolean

Whether the child may exec a different binary after startup.

allowedBinaries?: string[]

Executable basenames or paths allowed by an enforcing backend.

mode: 'allowlist' | 'denylist'

Syscall policy mode.

names: string[]

Syscall names in the selected policy mode.

mode: 'none' | 'strict' | 'bestEffort'

Requested mode, or none when no sandbox was requested.

backend: 'none' | 'linuxNative' | 'macosSeatbelt'

Backend selected for the spawn.

securityBoundary: boolean

Whether the process is protected by a security boundary.

supported: ProcessSandboxCapability[]

Policy categories supported by the selected backend.

enforced: ProcessSandboxCapability[]

Policy categories that were enforced.

unsupported: ProcessSandboxCapability[]

Requested categories that were not enforced.

diagnostics: string[]

Backend and platform diagnostics that explain capability decisions.

violationBehavior: ProcessSandboxViolationBehavior[]

Claimed behavior for denied operations.

category: 'resources' | 'filesystem' | 'network' | 'process' | 'syscalls'

Policy category covered by this report entry.

reason: string

Human-readable explanation suitable for diagnostics.

category: ProcessSandboxCapability['category']

Policy category covered by this behavior.

behavior: 'kill' | 'eperm' | 'denySpawn' | 'auditOnly'

Observable behavior when the backend denies an operation.

reason: string

Human-readable explanation suitable for diagnostics.

platform: string

Platform identifier used by the current runtime.

strictAvailable: boolean

Whether ProcessOptions.sandbox.mode = 'strict' can currently enforce a security boundary.

bestEffortAvailable: boolean

Whether reporting-only best-effort sandbox metadata can be attached to a spawned process.

backends: ProcessSandboxBackendCapability[]

Backends known to this runtime and their current availability.

features: ProcessSandboxNativeFeature[]

Native platform features probed by the host runtime before JS startup.

name: string

Stable feature name.

available: boolean

Whether the feature appeared available at startup.

reason: string

Human-readable explanation for the feature state.

name: ProcessSandboxReport['backend']

Backend name used by ProcessSandboxReport.backend.

available: boolean

Whether the backend can currently be selected.

reason: string

Human-readable reason for the current availability state.

supported: ProcessSandboxCapability['category'][]

Policy categories this backend can enforce when available.

code: number | null

Numeric exit code for a normally exited child.

The value is null when the child was killed by a signal or when the status could not be decoded as a normal exit.

import { Process } from 'fino:process';

const result = await new Process('/bin/true', []).wait();
console.log(result.code);

signal: number | null

Signal number that terminated the child.

The value is null for normal exits. Use exported signal constants such as SIGTERM when comparing known signals.

import { Process, SIGTERM } from 'fino:process';

const result = await new Process('/bin/sleep', ['1']).wait();
console.log(result.signal === SIGTERM);

pid: number

rssBytes: number

heapUsedBytes?: number

heapTotalBytes?: number

externalBytes?: number

eventLoopLagMs: number

timestamp: number

constructor(command: string, cmdArgs: string[], opts?: ProcessOptions)

Spawn a child process.

The command should be an executable path accepted by posix_spawnp(3). Arguments exclude argv[0]; the constructor prepends command. opts.env replaces the inherited environment snapshot, and opts.cwd is applied by libc spawn file actions when supported by the platform.

Standard input, output, and error are always exposed as pipes on the returned object. This constructor does not interpret Node-style shell, stdio, detached, ipc, uid, or gid options.

import { Process } from 'fino:process';

const proc = new Process('/bin/echo', ['hello'], { cwd: '/tmp' });
const result = await proc.wait();

get stdin()

Writer connected to the child's stdin.

Close this writer when no more input will be sent so programs waiting for EOF can exit. The writer is backed by a non-blocking pipe fd.

import { Process } from 'fino:process';

const proc = new Process('/usr/bin/cat', []);
await proc.stdin.write(new TextEncoder().encode('hello\n'));
proc.stdin.close();

get stdout()

Reader connected to the child's stdout.

The reader yields Uint8Array chunks until the child closes stdout. It is backed by a non-blocking pipe fd.

import { Process } from 'fino:process';

const proc = new Process('/bin/echo', ['hello']);
for await (const chunk of proc.stdout) console.log(chunk.byteLength);

get stderr()

Reader connected to the child's stderr.

The reader yields Uint8Array chunks until the child closes stderr. Drain it when running commands that may write enough stderr to fill the pipe.

import { Process } from 'fino:process';

const proc = new Process('/bin/sh', ['-c', 'echo error >&2']);
for await (const chunk of proc.stderr) console.log(chunk.byteLength);

get pid()

Child process ID returned by posix_spawnp().

The PID is available immediately after construction and remains the same after the child exits.

import { Process } from 'fino:process';

const proc = new Process('/bin/sleep', ['1']);
console.log(proc.pid);

get sandboxReport(): ProcessSandboxReport

Effective sandbox report for this child process.

The report describes what was actually enforced, not just what was requested in ProcessOptions.sandbox. When no sandbox was requested the report uses mode: 'none'. bestEffort reports are diagnostic only and do not indicate a security boundary.

import { Process } from 'fino:process';

const proc = new Process('/bin/echo', ['hello'], {
  sandbox: { mode: 'bestEffort' }
});
console.log(proc.sandboxReport.securityBoundary);

async wait(): Promise<WaitResult>

Wait for the child process to exit using kernel notifications.

• macOS: registers EVFILT_PROC via kqueue - zero-latency, zero-CPU wait.
• Linux: opens a pidfd via pidfd_open(2) and polls it with loop.readable() - the pidfd becomes readable the moment the child exits.

After the kernel signals exit, a single waitpid(pid, 0) reaps the zombie.

Calling wait() more than once is not supported because the first call reaps the process. The promise rejects if the platform wait primitive cannot be created.

import { Process } from 'fino:process';

const proc = new Process('/bin/true', []);
const result = await proc.wait();
console.log(result.code);

kill(signal: number = _SIGTERM): void

Send a signal to the child process.

Defaults to SIGTERM. This method does not wait for the child to exit and throws when the underlying kill(2) call fails, for example after the child has already been reaped.

import { Process, SIGTERM } from 'fino:process';

const proc = new Process('/bin/sleep', ['10']);
proc.kill(SIGTERM);