!random

The !random Atmos YAML function generates a cryptographically secure random integer within a specified range. This is particularly useful for generating random port numbers, IDs, or other numeric values in your devcontainer and stack configurations.

Usage

The !random function accepts 0, 1, or 2 parameters for maximum flexibility:

  # Generate a random integer between 0 and 65535 (default range)
  !random

  # Generate a random integer between 0 and max
  !random <max>

  # Generate a random integer between min and max
  !random <min> <max>

Arguments

min (optional)

Minimum value (inclusive). Must be an integer less than max. Defaults to 0 if not specified.

max (optional)

Maximum value (inclusive). Must be an integer greater than min. Defaults to 65535 if not specified.

The function generates a cryptographically secure random integer in the range [min, max] (both bounds inclusive).

Default Behavior:

• !random → Random number from 0 to 65535
• !random 100 → Random number from 0 to 100
• !random 1024 65535 → Random number from 1024 to 65535

Examples

Simple Random Values

Use !random without arguments for quick random number generation:

vars:
  # Generate any random number in the full range
  random_id: !random

  # Generate random number from 0 to 100
  percentage: !random 100

  # Generate random number from 1 to 10
  priority: !random 1 10

Random Port Numbers

Generate random ports for devcontainer configurations:

components:
  devcontainer:
    backend-api:
      spec:
        image: mcr.microsoft.com/devcontainers/go:1.24
        forwardPorts:
          - !random 1024 65535  # Specific range
          - !random 9999        # 0 to 9999
        workspaceFolder: /workspace

Random Ports in Stack Configurations

vars:
  # Generate a random ephemeral port
  app_port: !random 49152 65535

  # Generate a random port in registered port range
  service_port: !random 1024 49151

  # Generate a random ID
  worker_id: !random 1000 9999

Common Use Cases

DevContainer Port Forwarding

Automatically assign random ports to avoid conflicts when running multiple devcontainer instances:

components:
  devcontainer:
    geodesic:
      spec:
        image: cloudposse/geodesic:latest
        forwardPorts:
          - !random 8080 8099  # Web server
          - !random 3000 3099  # Dev server
          - !random 5432 5442  # Database
        workspaceFolder: /workspace

Viewing Actual Devcontainer Ports

When using !random for devcontainer port forwarding, the container is created with specific random ports that remain fixed for that container's lifetime. To see which ports your running container is actually using:

# Shows actual runtime ports for running containers
atmos devcontainer list

# Or use docker/podman directly
docker ps

The atmos devcontainer config command shows the configuration (which regenerates random values), not the actual runtime ports.

Load Balancer Configuration

Generate random ports for backend services:

vars:
  backend_ports:
    api: !random 10000 10999
    metrics: !random 11000 11999
    health: !random 12000 12999

Port Ranges

Common port ranges for different purposes:

• System Ports: 0-1023 (requires root/admin privileges)
• Registered Ports: 1024-49151 (commonly used application ports)
• Ephemeral Ports: 49152-65535 (typically used for dynamic/private port allocation)

For devcontainers and local development, use registered or ephemeral port ranges to avoid privilege requirements and conflicts with system services.

Cryptographic Security

The !random function uses Go's crypto/rand package to generate cryptographically secure random numbers. This ensures:

• Unpredictability: Values cannot be guessed or predicted
• No collisions: Multiple calls produce different values (statistically)
• Suitable for security: Safe for generating ports, tokens, or other security-sensitive values

Error Handling

The function will fail with a clear error message if:

• Less than 2 arguments provided
• More than 2 arguments provided
• Arguments are not valid integers
• min >= max

Example error:

invalid number of arguments. The function requires exactly 2 arguments (min max): !random 1024

Important: Values Are Not Persisted

The !random function generates a new random value every time Atmos processes your configuration. This means:

• Not saved: Random values are never persisted to disk
• Regenerated: Each atmos command generates new random values
• Devcontainer ports: When using !random for devcontainer ports:
  • The container is created with specific port values at creation time
  • Running atmos devcontainer list shows the actual runtime ports the container is using
  • Running atmos devcontainer config shows new random values (not the ones the container uses)
  • To see which ports a running container is using, use atmos devcontainer list or docker ps

For consistent values: Use !env with a pre-generated value or hardcode specific ports in your configuration.