coleam00/Archon · error · Error

Invalid container.network '${network}' in .archon/config.yam

Error message

Invalid container.network '${network}' in .archon/config.yaml — must be 'bridge' or 'none'. Host networking is not allowed for container isolation.

What it means

resolveContainerBackendConfig() validates the optional `container.network` setting from .archon/config.yaml before constructing a ContainerBackendConfig. Only 'bridge' and 'none' are accepted because container isolation depends on it; 'host' and any other value are rejected with this error at workflow start rather than producing a later docker error.

Source

Thrown at packages/cli/src/commands/workflow.ts:390

 * dev-vs-binary version string. Operators pin `container.image` for reproducibility.
 */
const DEFAULT_RUNNER_IMAGE = 'archon-runner:latest';

/**
 * Resolve the container backend config from the merged `container` config,
 * applying Phase B defaults (bridge network, 4 GiB memory, 512 pids).
 *
 * `container.*` comes from hand-parsed YAML (not Zod), so the values are
 * untrusted at runtime despite their static types — validate them here. In
 * particular `network` must be `bridge`/`none`: a stray `host` would otherwise
 * flow straight to `docker run --network host` and drop the network isolation.
 */
export function resolveContainerBackendConfig(
  cfg: { image?: string; network?: string; memoryMb?: number; pidsLimit?: number } | undefined
): ContainerBackendConfig {
  const network = cfg?.network;
  if (network !== undefined && network !== 'bridge' && network !== 'none') {
    throw new Error(
      `Invalid container.network '${network}' in .archon/config.yaml — must be ` +
        "'bridge' or 'none'. Host networking is not allowed for container isolation."
    );
  }
  // Positive INTEGERS — `docker run --memory`/`--pids-limit` reject fractions,
  // and Number.isFinite alone would let `512.5` through to a runtime docker error.
  const memoryMb = cfg?.memoryMb;
  if (memoryMb !== undefined && (!Number.isInteger(memoryMb) || memoryMb <= 0)) {
    throw new Error(
      `Invalid container.memoryMb '${String(memoryMb)}' — must be a positive integer (MiB).`
    );
  }
  const pidsLimit = cfg?.pidsLimit;
  if (pidsLimit !== undefined && (!Number.isInteger(pidsLimit) || pidsLimit <= 0)) {
    throw new Error(
      `Invalid container.pidsLimit '${String(pidsLimit)}' — must be a positive integer.`
    );
  }

View on GitHub (pinned to 0773b97458)

Solutions

  1. Edit .archon/config.yaml and set `container.network: bridge` (default) or `container.network: none`.
  2. Remove the `container.network` key entirely to get the default 'bridge'.
  3. If you intended host networking, use --no-worktree / non-container execution instead — container isolation never allows host mode.

Example fix

// .archon/config.yaml (before)
container:
  network: host
// after
container:
  network: bridge
Defensive patterns

Strategy: validation

Validate before calling

const cfg = yaml.parse(readFileSync('.archon/config.yaml', 'utf-8'));
const n = cfg?.container?.network;
if (n !== undefined && n !== 'bridge' && n !== 'none') {
  throw new Error(`container.network must be 'bridge'|'none', got: ${n}`);
}

Type guard

function isAllowedNetwork(n: unknown): n is 'bridge' | 'none' {
  return n === 'bridge' || n === 'none';
}

Try / catch

try {
  await runWorkflow(name, opts);
} catch (e) {
  if (String((e as Error).message).includes("Invalid container.network")) {
    console.error('Fix container.network in .archon/config.yaml (bridge|none only).');
  }
}

Prevention

When it happens

Trigger: Calling resolveContainerBackendConfig (via cfg/containerConfig during workflow run setup) with config.yaml containing `container.network: host`, a typo like `container.network: bridged`, or any string other than 'bridge' or 'none'.

Common situations: User copies a docker-compose-style config with `network: host` into .archon/config.yaml; typos such as 'default' or 'bridged'; misunderstanding that host networking is deliberately disallowed for isolation safety.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/ffec89338559f8e7. Report an issue: GitHub.