Local development

You can start Nhost Run services alongside your Nhost project very easily using the Nhost CLI by simply using the option --run-service path/to/run-service.toml[:overlay_name], for instance:

Let’s first take a look at the commend above, the first thing you can notice is that multiple --run-service flags are supported. You can pass as many as you need and they all will be added to your project. You can also add or remove Run services to an already running instance by re-running the command specifying the final list of --run-service you want. Any missing service will be removed and any new one will be added.

The second thing you will notice is that one of the --run-service flags contains the suffix :mysvc while the other one doesn’t. If you add to the configuration path the suffix :overlay_name the configuration overlay with name overlay_name will be applied.

The last thing to notice in the screenshot is that the URLs include information on how to connect to the Run service (in the example used in this guide only one of the started services expose a port):

- run-bun-gen:        From laptop:      http://localhost:5000
                      From services:    http://run-bun-gen:5000

Based on the information above, if you want to connect directly to your service from your laptop you can use the URL http://localhost:5000 while if you want to connect to the Run service from another service (i.e. another Run service or hasura) you can use http://run-bun-gen:5000

Note

You can also use the environment variable NHOST_RUN_SERVICE passing comma-separated values. For instance, the equivalent environment variable for this example would be NHOST_RUN_SERVICE=../mysvc/nhost-run-service.toml:mysvc,../mysvc/nhost-run-service.toml

Caution

The Nhost CLI doesn’t build services so make sure you build any image that might be needed for running nhost up --run-service...

Live Reload with Volume Mounts

When developing a Run service, you often want changes to your source code to be reflected immediately without rebuilding the Docker image. You can achieve this by combining the --run-service-volume flag with a configuration overlay that overrides the start command to use a file watcher like nodemon.

The --run-service-volume flag mounts a local directory into the running container, and the overlay replaces the start command with one that watches for file changes:

nhost up \
  --run-service ../mysvc/nhost-run-service.toml:local \
  --run-service-volume "mysvc=/path/to/mysvc:/app"

The format for --run-service-volume is service-name=/local/path:/container/path. You can pass this flag multiple times to mount multiple directories or for different services.

For example, given the following service configuration:

nhost-run-service.toml

name = 'mysvc'
command = ["node", "index.js"]

[image]
image = 'mysvc:dev'

[[ports]]
port = 8000
type = 'http'
publish = true

[resources]
replicas = 1

[resources.compute]
cpu = 62
memory = 128

overlay (local)

[
  {
    "value": ["npx", "nodemon", "/app/index.js"],
    "op": "add",
    "path": "/command"
  }
]

The overlay replaces the start command with npx nodemon /app/index.js, which watches for file changes and automatically restarts the process. Combined with the volume mount, any changes you make to your local source code will be picked up immediately:

$ curl http://localhost:8000
{"message":"Hello from mysvc!","timestamp":"2026-03-25T15:51:54.586Z"}

# Edit index.js locally...

$ docker logs myproject-run-mysvc-1
[nodemon] restarting due to changes...
[nodemon] starting `node /app/index.js`
Server listening on port 8000

$ curl http://localhost:8000
{"message":"Hello from mysvc (dev)!","timestamp":"2026-03-25T15:52:48.782Z"}

Note

You can also use the environment variable NHOST_RUN_SERVICE_VOLUME passing comma-separated values. For instance: NHOST_RUN_SERVICE_VOLUME=mysvc=/path/to/mysvc:/app

Quick Development

While developing your service, you may want to run it locally outside of the Nhost CLI to quickly iterate on it. To simplify this the Nhost CLI includes a command to generate an .env file based on your environment variables configuration and secrets. For instance, imagine a service with the following configuration:

run-service.toml

[[environment]]
name = 'HASURA_GRAPHQL_URL'
value = 'http://hasura-service:8080/v1/graphql'

[[environment]]
name = 'SOME_CONFIGURATION_PARAMETER'
value = 'some-value'

[[environment]]
name = 'SECRET_KEY'
value = '{{ secrets.SECRET_KEY }}'

overlay

[
  {
    "value": {
      "name": "ENVIRONMENT",
      "value": "dev"
    },
    "op": "add",
    "path": "/environment/-"
  },
  {
    "value": "https://local.graphql.local.nhost.run/v1/graphql",
    "op": "replace",
    "path": "/environment/0/value"
  }
]

.secrets

SECRET_KEY = '#asdasd;l;kq23\\n40-0as9d"$\\'

We can then generate an env file for our service with the folllowing command:

$ nhost run env --config ../mysvc/nhost-run-service.toml --overlay-name local-dev > .env
$ cat .env
HASURA_GRAPHQL_URL="https://local.graphql.local.nhost.run/v1/graphql"
SOME_CONFIGURATION_PARAMETER="some-value"
SECRET_KEY="#asdasd;l;kq23\\n40-0as9d\"\$\\"
ENVIRONMENT="dev"

Caution

Keep in mind you may need to use different configuration when attempting to connect to other services in the stack. For instance, in the example above we are using http://hasura-service:8080/v1/graphql to connect to hasura in production and in the CLI but when running the service in the host machine using the env file we are using an overlay to change the value to https://local.graphql.local.nhost.run/v1/graphql. Refer to the network configuration for more details.