Docker.Network reference

Network

Source: packages/docker/src/Network.ts

A Docker network managed through the active Docker context.

Existing same-name networks are treated as foreign unless the engine is explicitly allowed to adopt them with --adopt or adopt(true).

Network: Creating Networks

const network = yield* Docker.Network("app-network", {
  name: "app-network",
});

Network: Isolation and address allocation

const network = yield* Docker.Network("private-network", {
  internal: true,
  attachable: true,
  enableIPv4: true,
  driverOpts: { "com.docker.network.driver.mtu": "1420" },
  ipam: {
    config: [{
      subnet: "10.50.0.0/24",
      gateway: "10.50.0.1",
      ipRange: "10.50.0.128/25",
      auxAddresses: { reserved: "10.50.0.5" },
    }],
  },
});

An internal network restricts external connectivity through that network; additional container network attachments can still provide external routes. If IPAM is omitted, Docker allocates a subnet and gateway. Alchemy does not treat those automatically assigned values as configuration drift. IPAM subnet and range values must be valid CIDR network prefixes (for example, 10.50.0.0/24, not 10.50.0.1/24). Declared IPv4/IPv6 subnets require the corresponding address family to be enabled. Alchemy validates address containment and overlapping subnets before a destructive replacement, and compares IPv6 addresses by their network value rather than text. Invalid options fail with InvalidNetworkOptions, whose path identifies the rejected field (for example, ipam.config[0].gateway). Labels beginning with alchemy:: are reserved for resource ownership and cannot be overridden by user-supplied labels.

Network: IPv6-only networks

const network = yield* Docker.Network("ipv6-only", {
  enableIPv4: false,
  enableIPv6: true,
});

Network: Dual-stack networks

const network = yield* Docker.Network("dual-stack", {
  enableIPv6: true,
  ipam: {
    config: [
      { subnet: "10.51.0.0/24", gateway: "10.51.0.1" },
      { subnet: "fd51:3456:789a::/64", gateway: "fd51:3456:789a::1" },
    ],
  },
});

Network: Driver-specific IPAM options

const network = yield* Docker.Network("ipam-network", {
  ipam: {
    driver: "default",
    options: { "my-option": "my-value" },
  },
});

Network driver and IPAM driver options are passed to Docker without interpreting driver-specific semantics.

Network: Adoption

const network = yield* Docker.Network("app-network", {
  name: "shared-app-network",
}).pipe(adopt(true));

Network: Looking up an existing network

Network.lookup references a network Alchemy doesn’t manage (created with the Docker CLI, Compose or another stack). It is read during plan/deploy, never created, updated or removed.

const shared = Docker.Network.lookup({ name: "compose_default" });
const api = yield* Docker.Container("Api", {
  image: "nginx:alpine",
  networks: [{ name: shared.name }],
});

Network: Replacement

Network creation settings are immutable. Changing them replaces the network. Docker refuses to delete a network while it has attached endpoints; Alchemy does not forcibly disconnect unrelated containers to complete replacement. A managed network deleted outside Alchemy is recreated on the next deploy. If another network takes over its name, Alchemy refuses to claim it: the recorded Docker ID must still match, even if the network’s settings do. Replacement is not transactional: a custom network or IPAM driver may reject a configuration after Docker has already removed the old network. Alchemy validates known IPAM constraints ahead of time, but the network driver determines which settings take effect. Some drivers may accept options without applying them; inspect the resulting network for advanced settings.