> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> Using services with your environment

It is very common for software projects to depend on other programs for core
parts of their functionality.
A web service may depend on a load balancer and a database.
A developer working on the front end of a website may need a development server
running that hot-reloads the site as they tweak the CSS.
You may also want a program that automatically runs your test suite when file
changes are detected.

What these use cases all have in common is that they use long-running programs
as part of the development lifecycle,
and the developer likely wants those programs running as soon as they sit down
to start working on the project.

We call these long-running programs "services",
and you can integrate them directly with your environment.

## Defining services

Services are defined in the `[services]` section of the manifest.
Services have a very simple schema consisting of a `command` to run to start
the service,
any `vars` you want set specifically for the service,
and whether the service spawns a background process.
See [`manifest-toml(1)`](/man/manifest.toml) for
more details on the exact format of the `[services]` section of the manifest.

An example service definition is shown below:

```toml theme={null}
[services.database]
command = "exec postgres -D \"$PGDATA\" -p \"$PGPORT\""
vars.PGUSER = "myuser"
vars.PGPASSWORD = "super-secret"
vars.PGDATABASE = "mydb"
vars.PGPORT = "9001"
```

This definition creates a service called `database` that starts a PostgreSQL
database and configures some of its properties through environment variables.

Some services cannot be shut down by the default mechanism (sending the spawned process a `SIGTERM`).
Most often this is because the spawned process itself spawns another process (typically a daemon) and then terminates. In this case you need to provide your own command for shutting down the service. You do this by setting `is-daemon = true` for the service and providing a `shutdown.command`. Below is an example that uses `pg_ctl` (the daemon-spawning launcher) instead of `exec postgres`, which launches postgres in the foreground. It demonstrates the `is-daemon = true` + `shutdown.command` pattern for programs that background themselves. Together these fields allow the service manager to shut down services that background themselves.

```toml theme={null}
[services.database]
command = "pg_ctl start -D \"$PGDATA\" -l \"$PGDATA/server.log\" -o \"-p $PGPORT\""
is-daemon = true
shutdown.command = "pg_ctl stop -D \"$PGDATA\" -m fast"
vars.PGUSER = "myuser"
vars.PGPASSWORD = "super-secret"
vars.PGDATABASE = "mydb"
vars.PGPORT = "9001"
```

You can define a `shutdown.command` for any service, including services that do not run as daemons. Note that this pattern can have unpredictable effects in practice: it replaces the Flox service manager’s controlled `SIGTERM` → grace → `SIGKILL` shutdown path, which tracks the service’s PID, with the command that you define. And if your shutdown command fails to locate and kill the process for any reason, there's no fallback; the service never receives any signal and keeps running.

## Starting services

Services can be started automatically when you activate your environment via
the `flox activate --start-services` command
(or via the shorter `flox activate -s`).
This will start services as part of activating your environment.
When activating your environment from multiple shells you only need to start
the services once.
Since your services are just processes running on your machine,
they will be visible to any other activations.

Activating your environment without the `--start-services` flag will not start
the services.
If you activate your environment without services and then later decide that
you want to start them, that is done via the `flox services start` command.
When called without any arguments this command will start all services listed
in the manifest.
You can also specify individual service names,
in which case only those services will be started.
If you accidentally provide a service name that doesn't exist,
you'll get an error and no services will be started.
If a service is already running,
you'll see a warning but the command will otherwise succeed.

## Stopping services

Services are **automatically stopped** when the last running activation of the
environment terminates.
This means that if you `flox activate -s` in a single shell,
the services will be shut down automatically when you exit that shell.
Similarly, if you `flox activate -s` in one shell, then `flox activate` in two
more shells,
the services won't be shut down until all three of those activations have
terminated.

You can stop services yourself via the `flox services stop` command.
You can also specify individual service names,
in which case only those services will be stopped.
If you accidentally provide a service name that doesn't exist,
you'll get an error and no services will be stopped.
If a service is already stopped,
you'll see a warning but the command will otherwise succeed.

## Restarting services

Services can be restarted via the `flox services restart` command.
You can also specify individual service names,
in which case only those services will be restarted.
If you accidentally provide a service name that doesn't exist,
you'll get an error and no services will be restarted.

## Handling environment edits

While working in your environment that has running services,
you may discover that you need to edit a service definition or some other part
of the environment.
In this scenario you would call `flox edit` like usual,
but now the manifest is out of sync with both the current activation of your
environment *and* the running services.
After making the edit you'll see a warning about needing to reactivate your
environment in order to apply the changes to your shell,
but if you just want to apply the changes to your services
(say you only modified a service definition)
you can do so without needing to reactivate your environment.

There are two ways to accomplish this:

1. `flox services restart`
2. `flox services stop` followed by `flox services start`

In both cases the services will be started in an ephemeral activation so that
the services can be started in the same environment as they otherwise would be
in a new activation.
The `flox services stop` in the second case is only necessary if any services
are currently running.

## Checking on services

You can see the status of your services with the `flox services status`
command.
This will display the name of the service, the PID, and its status.
An example is shown below:

```console theme={null}
NAME       STATUS            PID
database   Running         12345
server     Running         23456
```

You can see the logs of your services with the `flox services logs` command.
This command operates in two modes:

* all services with `--follow`
* single service with either `--follow` or `--tail`

When no services are specified the `--follow` flag must be provided,
in which case logs for all running services will be displayed in real time.
If a single service name is provided then the logs for that service will be
displayed.

Logs for the service manager itself are stored as `services.*.log` files in the
`.flox/logs` directory of your environment.