application · orchestration · cloud

One binary to run it all,Nomad.

HashiCorp's lightweight, flexible workload orchestrator — a single binary that schedules and scales containers, plain executables, Java apps, and batch jobs across a cluster with a fraction of the operational overhead of Kubernetes. This guide covers the architecture, installation, job specs, and the essential CLI.

ArchitectureInstallJob specsCLI cheatsheet

Simplicity over sprawl

Nomad slots into the HashiCorp stack — Consul for service discovery, Vault for secrets — and orchestrates far more than containers while staying a single, small binary.

• Servers — hold state and elect a Raft leader.
• Clients — run allocations and report health.
• Drivers — docker, exec, java, and qemu workloads.

~100MBBinary size

3 or 5HA quorum

docker · exec · javaDrivers

4646Dev UI port

FeaturesFAQRelated

On this page

What this guide covers

Architecture

Server and client roles from one binary — jobs, tasks, groups, and allocations explained.

Install

Grab the single binary via Homebrew or apt, then start a local dev agent with UI.

Jobs

Declare workloads in an HCL job spec — service, batch, and system types with Docker drivers.

Cheatsheet

The nomad CLI commands you reach for daily — run, status, logs, nodes, and server members.

Start here

Overview

Nomad is HashiCorp’s easy, flexible, and powerful workload orchestrator. It ships as a single binary that can schedule and scale containers, plain executables, Java applications, and batch jobs across a cluster — often with a fraction of the operational overhead of Kubernetes.

Nomad slots into the HashiCorp stack: Consul for service discovery, Vault for secrets. A production high-availability control plane holds quorum with an odd number of server nodes (3 or 5); a full HA stack of Vault, Consul, and Nomad means 3 instances of each — 9 total — though Nomad runs standalone too.

This guide covers the architecture, installation, job specs, and the CLI cheatsheet.

Two roles, one binary

Architecture

Nomad has two node roles running from the same binary:

Role	Responsibility
Server	Holds cluster state, runs the scheduler, elects a leader via Raft. Run 3 or 5 for HA.
Client	Registers with servers, runs allocations, reports health and resource usage.

Key terms:

• Job — your declarative desired state (what to run, how many).
• Task — a single unit of work run by a driver (docker, exec, java, qemu).
• Group — a set of tasks scheduled together on one node.
• Allocation (alloc) — a group’s tasks placed on a specific client. The rough equivalent of a Pod in Kubernetes.

Up in minutes

Install

Nomad is a single binary — download it or use a package manager.

1. Install the binary

   # macOS
   brew tap hashicorp/tap && brew install hashicorp/tap/nomad
   
   # Linux (Debian/Ubuntu)
   wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
   echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
   sudo apt update && sudo apt install nomad

2. Verify the install

   nomad version

3. Start a dev agent A single node acting as both server and client — perfect for local testing.

   sudo nomad agent -dev

   Open the UI at http://localhost:4646.

Declare, submit, scale

Jobs

Nomad workloads are declared in an HCL job specification. A minimal Docker service:

job "web" {
  datacenters = ["dc1"]
  type        = "service"

  group "app" {
    count = 3

    network {
      port "http" { to = 8080 }
    }

    task "server" {
      driver = "docker"

      config {
        image = "nginx:alpine"
        ports = ["http"]
      }

      resources {
        cpu    = 100
        memory = 128
      }
    }
  }
}

Submit and inspect it:

nomad job run web.nomad.hcl
nomad job status web

Tip

type = "service" keeps a job running and reschedules it on failure. Use type = "batch" for run-to-completion tasks and type = "system" to run one alloc on every client (like a Kubernetes DaemonSet).

Daily drivers

Cheatsheet

Command	Purpose
nomad agent -dev	Start a local single-node agent
nomad job run <file>	Submit or update a job
nomad job status <job>	Show job, group, and allocation state
nomad alloc logs <alloc>	Stream logs from an allocation
nomad alloc logs -f <alloc>	Follow logs live
nomad status <id>	Look up any object by its 8-char ID
nomad node status	List client nodes and health
nomad job stop <job>	Stop and garbage-collect a job
nomad server members	List server peers and the Raft leader

Note

The {$allocation} ID is a unique reference to a group of tasks on a node; the {$identifier} used by nomad status is an 8-character alphanumeric prefix — you only need enough characters to be unambiguous.

Questions

Frequently asked

What is HashiCorp Nomad?

Nomad is a lightweight, single-binary workload orchestrator from HashiCorp that schedules and manages containers, standalone binaries, Java apps, and batch jobs across a cluster. It pairs naturally with Consul for service discovery and Vault for secrets.

How is Nomad different from Kubernetes?

Nomad is a single ~100MB binary that orchestrates more than just containers (raw executables, Java, QEMU VMs), with far less operational overhead than Kubernetes. Kubernetes is a larger, container-focused platform with a bigger built-in ecosystem. Nomad favors simplicity and flexible workload types; Kubernetes favors breadth and a rich API surface.

What is an allocation in Nomad?

An allocation (alloc) is a set of tasks from a job placed and running on a single client node — the rough equivalent of a Pod in Kubernetes. Each allocation gets a unique ID you use to inspect status and stream logs with nomad alloc logs.

How many servers does a Nomad cluster need for high availability?

A production HA control plane needs an odd number of server nodes to hold quorum, typically 3 or 5. A full HashiCorp stack with Vault and Consul also at HA means 3 instances of each, for 9 total, though Nomad itself can run standalone.

What is a Nomad job specification?

A job spec is an HCL (or JSON) file that declares what to run — the job, its groups, tasks, driver (docker, exec, java), resources, and count. You submit it with nomad job run, and the scheduler places allocations onto healthy clients that meet the constraints.

Keep exploring

Related applications

KubernetesThe heavyweight alternative — container orchestration at platform scale.DockerThe container runtime behind Nomad's most common task driver.TerraformHashiCorp's infrastructure-as-code sibling to Nomad.