---
layout: docs
page_title: 'nomad agent command reference'
description: |
  The `nomad agent` command starts the Nomad agent, which handles client or server functionality, including exposing interfaces for client consumption and running jobs. The agent runs until it receives an interrupt signal.
---

# `nomad agent` command reference

The `nomad agent` command starts the Nomad agent, which handles client or server
functionality, including exposing interfaces for client consumption and running
jobs. The agent runs until it receives an interrupt signal.

Refer to [Operating Nomad agents] and [Nomad agent configuration] for more
information on how to use this command and the options it has.

## Usage

If you are running Nomad on Linux, you need to run client agents as root, or
with `sudo`, so that cpuset accounting and network namespaces work correctly.

```plaintext
nomad agent [options]
```

## Options

We recommend configuring a Nomad agent with configuration files. Refer to [Nomad
agent configuration] for details.

You may, however, may pass the following configuration options as CLI arguments:

- `-alloc-dir=<path>`: Equivalent to the Client [alloc_dir][] config
  option.

- `-acl-enabled`: Equivalent to the ACL [enabled][] config option.

- `-acl-replication-token`: Equivalent to the ACL [replication_token][] config
  option.

- `-bind=<address>`: Equivalent to the [bind_addr][] config option.

- `-bootstrap-expect=<num>`: Equivalent to the
  [bootstrap_expect][] config option.

- `-client`: Enable client mode on the local agent.

- `-config=<path>`: Specifies the path to a configuration file or a directory of
  configuration files to load. Can be specified multiple times.

- `-consul-address=<addr>`: Equivalent to the [address][] config option.

- `-consul-auth=<auth>`: Equivalent to the [auth][] config option.

- `-consul-auto-advertise`: Equivalent to the [auto_advertise][] config option.

- `-consul-ca-file=<path>`: Equivalent to the [ca_file][] config option.

- `-consul-cert-file=<path>`: Equivalent to the [cert_file][] config option.

- `-consul-checks-use-advertise`: Equivalent to the [checks_use_advertise][]
  config option.

- `-consul-client-auto-join`: Equivalent to the [client_auto_join][] config
  option.

- `-consul-client-service-name=<name>`: Equivalent to the [client_service_name][]
  config option.

- `-consul-client-http-check-name=<name>`: Equivalent to the
  [client_http_check_name][] config option.

- `-consul-client-failures-before-critical=<num>`: Equivalent to the
  [client_failures_before_critical][] config option.

- `-consul-client-failures-before-warning=<num>`: Equivalent to the
  [client_failures_before_warning][] config option.

- `-consul-key-file=<path>`: Equivalent to the [key_file][] config option.

- `-consul-server-service-name=<name>`: Equivalent to the [server_service_name][]
  config option.

- `-consul-server-http-check-name=<name>`: Equivalent to the
  [server_http_check_name][] config option.

- `-consul-server-serf-check-name=<name>`: Equivalent to the
  [server_serf_check_name][] config option.

- `-consul-server-rpc-check-name=<name>`: Equivalent to the
  [server_rpc_check_name][] config option.

- `-consul-server-auto-join`: Equivalent to the [server_auto_join][] config
  option.

- `-consul-server-failures-before-critical=<num>`: Equivalent to the
  [server_failures_before_critical][] config option.

- `-consul-server-failures-before-warning=<num>`: Equivalent to the
  [server_failures_before_warning][] config option.

- `-consul-ssl`: Equivalent to the [ssl][] config option.

- `-consul-token=<token>`: Equivalent to the [token][] config option.

- `-consul-verify-ssl`: Equivalent to the [verify_ssl][] config option.

- `-data-dir=<path>`: Equivalent to the [data_dir][] config option.

- `-dc=<datacenter>`: Equivalent to the [datacenter][] config option.

- `-dev`: Start the agent in development mode. This enables a pre-configured
  dual-role agent (client + server) which is useful for developing or testing
  Nomad. No other configuration is required to start the agent in this mode,
  but you may pass an optional comma-separated list of mode configurations:

- `-dev-connect`: Start the agent in development mode, but bind to a public
  network interface rather than localhost for using Consul Connect. It may be
  used with `-dev-consul` to configure default workload identities for Consul.
  This mode is supported only on Linux as root.

- `-dev-consul`: Starts the agent in development mode with a default Consul
  configuration for Nomad workload identity. It may be used with `-dev-connect`
  to configure the agent for Consul Service Mesh.

- `-dev-vault`: Starts the agent in development mode with a default Vault
  configuration for Nomad workload identity.

- `-encrypt`: Set the Serf encryption key. See the [Encryption Overview][] for
  more details.

- `-join=<address>`: Address of another agent to join upon starting up. This can
  be specified multiple times to specify multiple agents to join.

- `-log-level=<level>`: Equivalent to the [log_level][] config option.

- `-log-include-location`: Equivalent to the [log_include_location][] config option.

- `-log-json`: Equivalent to the [log_json][] config option.

- `-meta=<key=value>`: Equivalent to the Client [meta][] config option.

- `-network-interface=<interface>`: Equivalent to the Client
  [network_interface][] config option.

- `-node=<name>`: Equivalent to the [name][] config option.

- `-node-class=<class>`: Equivalent to the Client [node_class][]
  config option.

- `-node-pool=<node-pool>`: Equivalent to the Client [node_pool][]
  config option.

- `-plugin-dir=<path>`: Equivalent to the [plugin_dir][] config option.

- `-region=<region>`: Equivalent to the [region][] config option.

- `-rejoin`: Equivalent to the [rejoin_after_leave][] config option.

- `-retry-interval`: Equivalent to the [retry_interval][] config option.

- `-retry-join`: Similar to `-join` but allows retrying a join if the first
  attempt fails.

  ```shell-session
  $ nomad agent -retry-join "127.0.0.1:4648"
  ```

  `retry-join` can be defined as a command line flag only for servers. Clients
  can configure `retry-join` only in configuration files.

- `-retry-max`: Similar to the [retry_max][] config option.

- `-server`: Enable server mode on the local agent.

- `-servers=<host:port>`: Equivalent to the Client [servers][] config
  option.

- `-state-dir=<path>`: Equivalent to the Client [state_dir][] config
  option.

- `-vault-enabled`: Whether to enable or disabled Vault integration.

- `-vault-address=<addr>`: The address to communicate with Vault.

- `-vault-token=<token>`: The Vault token used to derive tokens. Only needs to
  be set on Servers. Overrides the Vault token read from the VAULT_TOKEN
  environment variable.

- `-vault-create-from-role=<role>`: The role name to create tokens for tasks
  from.

- `-vault-ca-file=<path>`: Path to a PEM-encoded CA cert file used to verify the
  Vault server SSL certificate.

- `-vault-ca-path=<path>`: Path to a directory of PEM-encoded CA cert files used
  to verify the Vault server SSL certificate.Whether to enable or disabled Vault
  integration.

- `vault-cert-file=<path>`: The path to the certificate for Vault communication.

- `vault-key-file=<path>`: The path to the private key for Vault communication.

- `vault-namespace=<namespace>`: The Vault namespace used for the integration.
  Required for servers and clients. Overrides the Vault namespace read from the
  VAULT_NAMESPACE environment variable.

- `vault-tls-skip-verify`: A boolean that determines whether to skip SSL
  certificate verification.

- `vault-tls-server-name=<name>`: Used to set the SNI host when connecting to
  Vault over TLS.

[address]: /nomad/docs/configuration/consul#address
[alloc_dir]: /nomad/docs/configuration/client#alloc_dir
[auth]: /nomad/docs/configuration/consul#auth
[auto_advertise]: /nomad/docs/configuration/consul#auto_advertise
[bind_addr]: /nomad/docs/configuration#bind_addr
[bootstrap_expect]: /nomad/docs/configuration/server#bootstrap_expect
[ca_file]: /nomad/docs/configuration/consul#ca_file
[cert_file]: /nomad/docs/configuration/consul#cert_file
[checks_use_advertise]: /nomad/docs/configuration/consul#checks_use_advertise
[client_auto_join]: /nomad/docs/configuration/consul#client_auto_join
[client_http_check_name]: /nomad/docs/configuration/consul#client_http_check_name
[client_failures_before_critical]: /nomad/docs/configuration/consul#client_failures_before_critical
[client_failures_before_warning]: /nomad/docs/configuration/consul#client_failures_before_warning
[server_failures_before_critical]: /nomad/docs/configuration/consul#server_failures_before_critical
[server_failures_before_warning]: /nomad/docs/configuration/consul#server_failures_before_warning
[client_service_name]: /nomad/docs/configuration/consul#client_service_name
[data_dir]: /nomad/docs/configuration#data_dir
[datacenter]: /nomad/docs/configuration#datacenter
[enabled]: /nomad/docs/configuration/acl#enabled
[encryption overview]: /nomad/tutorials/transport-security/security-gossip-encryption
[key_file]: /nomad/docs/configuration/consul#key_file
[log_include_location]: /nomad/docs/configuration#log_include_location
[log_json]: /nomad/docs/configuration#log_json
[log_level]: /nomad/docs/configuration#log_level
[meta]: /nomad/docs/configuration/client#meta
[name]: /nomad/docs/configuration#name
[network_interface]: /nomad/docs/configuration/client#network_interface
[node_class]: /nomad/docs/configuration/client#node_class
[node_pool]: /nomad/docs/configuration/client#node_pool
[Operating Nomad agents]: /nomad/docs/operations/nomad-agent
[Nomad agent configuration]: /nomad/docs/configuration
[plugin_dir]: /nomad/docs/configuration#plugin_dir
[region]: /nomad/docs/configuration#region
[rejoin_after_leave]: /nomad/docs/configuration/server#rejoin_after_leave
[replication_token]: /nomad/docs/configuration/acl#replication_token
[retry_interval]: /nomad/docs/configuration/server#retry_interval
[retry_max]: /nomad/docs/configuration/server#retry_max
[server_auto_join]: /nomad/docs/configuration/consul#server_auto_join
[server_http_check_name]: /nomad/docs/configuration/consul#server_http_check_name
[server_rpc_check_name]: /nomad/docs/configuration/consul#server_rpc_check_name
[server_serf_check_name]: /nomad/docs/configuration/consul#server_serf_check_name
[server_service_name]: /nomad/docs/configuration/consul#server_service_name
[servers]: /nomad/docs/configuration/client#servers
[ssl]: /nomad/docs/configuration/consul#ssl
[state_dir]: /nomad/docs/configuration/client#state_dir
[token]: /nomad/docs/configuration/consul#token
[verify_ssl]: /nomad/docs/configuration/consul#verify_ssl

