Nomad CLI for coding agents

When a coding agent edits a Nomad job file, it can run nomad job plan to ask a Nomad cluster how the change would affect the workload before anyone submits it. Nomad is HashiCorp’s workload orchestrator: it schedules and manages services, batch jobs, and other workloads. The plan command compares a proposed job with the job the cluster currently knows about and reports the planned changes.

The CLI lets an agent ask Nomad to plan a change, but the command contacts a Nomad server. The agent needs access to the intended cluster and, when access control lists (ACLs) are enabled, credentials that the cluster accepts. A plan does not submit the job.

What the plan shows

A Nomad job file describes a workload, including its task groups and the number of instances to run. After an agent changes that file, nomad job plan asks the server to evaluate the proposed version against the cluster’s current state. The command reports the planned differences and a job modify index. That index identifies the version of the job the plan used.

The index matters if someone later submits the change: Nomad can check that the job has not changed since the plan was made. If another operator submits an update in the meantime, the index check prevents applying a plan based on stale job state. HashiCorp documents the command and this plan-and-apply behavior in the nomad job plan reference.

Nomad does not provide a special coding-agent mode for this command. An agent with shell access invokes the same CLI a developer would use. For example, an agent can edit a job’s instance count and run a plan; it can then report the proposed change for a person to review.

Set up a plan

Install the Nomad CLI using HashiCorp’s official Nomad repository, which supports macOS, Windows, and Linux. Check that the executable is available with:

nomad version

Before planning, configure the CLI to reach the intended Nomad server. If Nomad ACLs are enabled, the agent also needs credentials accepted by that cluster. Keep credentials in the agent’s protected environment or credential store; do not paste tokens into its prompt. The plan command documents connection options, including -address and -token, in its command reference.

For a small example, save the following as agent-preview.nomad. Replace dc1 with a datacenter name in your cluster. This example uses Nomad’s Docker task driver, which runs tasks in Docker containers. The cluster needs clients configured to run Docker tasks.

job "agent-preview" {
  datacenters = ["dc1"]

  group "worker" {
    count = 1

    task "worker" {
      driver = "docker"

      config {
        image   = "busybox:latest"
        command = "sh"
        args    = ["-c", "sleep 3600"]
      }

      resources {
        cpu    = 100
        memory = 64
      }
    }
  }
}

To preview a change, ask the agent to change count from 1 to 2, then run:

nomad job plan ./agent-preview.nomad

The agent edits the file locally. The plan command contacts the configured Nomad server to evaluate the proposed job; it does not launch two tasks or submit the job. Review the reported differences and modify index. The exact plan depends on the job already registered with that cluster and its current state, so do not treat example output as a prediction of what your cluster will report.

Apply only after review

If a person approves the change, nomad job run submits the job. Use the modify index from the plan with the documented -check-index option so Nomad rejects the submission if the job changed after planning. The plan documentation describes this check. A successful plan alone does not mean the cluster has received the job.

Know the limits

A plan describes what Nomad expects when it compares the proposed job with the cluster state it evaluated. It does not prove that a task will start successfully or that its application will behave correctly. Those outcomes depend on the cluster and workload, including whether the required task driver and resources are available.

Nomad is a general workload orchestrator, so the CLI is useful when the agent is changing Nomad job definitions or inspecting Nomad-managed workloads. It does not provide a general-purpose sandbox for running arbitrary agent-generated code. For a job change, the agent can edit locally and request a plan, while a separate approved command submits the job.