---
name: "just-serve-config"
section: "5"
platform: "linux"
package: "justbuild"
version: "1.5.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/just-serve-config"
---

# just-serve-config(5)

The format of the configuration used by the serve subcommand of justbuild(1)

## NAME

just-serve-config - The format of the configuration used by the **serve** subcommand of [**justbuild**(1)](/justbuild/1.md)

## DESCRIPTION

The file is read as JSON. Any other serialization describing the same JSON object is equivalent. We assume, that in JSON objects, each key occurs at most once; it is implementation defined how repetitions of the same key are treated.

### Location objects

The general syntax and semantics of a location object are described in [**just-mrrc**(5)](/just-mrrc/5.md). Here we use a restricted form where the value for key *"root"* can only be either *"home"* or *"system"*. This is because `just serve` is not aware of the concept of workspaces.

### The just-serve configuration format

The configuration file is given by a JSON object.

- •

  The value for the key *"local build root"* is a single location object, specifying the path to use as the root for local CAS, cache, and build directories. The path will be created if it does not exist already.

- •

  The value for the key *"repositories"* is a list of location objects, specifying paths to Git repositories for **justbuild** **serve** to use as additional object lookup locations. The paths are to be used in the order given and only if requested objects are not found in the local build root.

- •

  The value for the key *"logging"* is a JSON object specifying logging options.

For subkey *"files"* the value is a list of location objects, specifying one or more local log files to use.

For subkey *"limit"* the value is an integer setting the default for the log limit.

For subkey *"restrict stderr limit"* the value is an integer setting a restriction for the log on stderr.

For subkey *"plain"* the value is a flag. If set, do not use ANSI escape sequences to highlight messages.

For subkey *"append"* the value is a flag. If set, append messages to log file instead of overwriting existing.

- •

  The value for the key *"authentication"* is a JSON object specifying client-side authentication options for **justbuild** **serve** when communicating with the remote execution endpoint.

For subkey *"ca cert"* the value is a single location object, specifying the path to a TLS CA certificate.

For subkey *"client cert"* the value is a single location object, specifying the path to a TLS client certificate.

For subkey *"client key"* the value is a single location object, specifying the path to a TLS client key.

- •

  The value for the key *"remote service"* is a JSON object specifying the server arguments for running **justbuild** **serve** as a service.

For subkey *"interface"* the value specifies the interface of the service. If unset, the loopback device is used.

For subkey *"port"* the value specifies the port to which the service is to listen. If unset, the service will choose to the first available one.

For subkey *"pid file"* the value is a single location object, specifying the path to a file to which the pid should be stored in plain text. If the file exists, it will be overwritten.

For subkey *"info file"* the value specifies a single location object, specifying the path to a file file to which the used port, interface, and pid should be stored in JSON format. If the file exists, it will be overwritten.

For subkey *"server cert"* the value is a single location object, specifying the path to a TLS server certificate.

For subkey *"server key"* the value is a single location object, specifying the path to a TLS server key.

- •

  The value for the key *"execution endpoint"* is a JSON object specifying the arguments of a remote execution endpoint to be used by **justbuild** **serve**.

For subkey *"address"* the value is a string specifying the remote execution address in a NAME:PORT format.

For subkey *"client address"* the value is a string specifying the remote execution address used by the client in a NAME:PORT format. If not provided, it defaults to *"address"*.

For subkey *"compatible"* the value is a flag which specifies whether the remote endpoint uses the original remote execution protocol.

If the key *"execution endpoint"* is given, the following three keys will be evaluated as well:

- •

  *"max-attempts"*: the value must be a number specifying the maximum number of attempts to perform when a remote procedure call (to the *"execution endpoint"* given) fails because the resource is unavailable.

- •

  *"initial-backoff-seconds"*: the value must be a number; before retrying the second time, the client will wait the given amount of seconds plus a jitter, to better distribute the workload.

- •

  *"max-backoff-seconds"*: the value must be a number; from the third attempt (included) on, the backoff time is doubled at each attempt, until it exceeds the `"max-backoff-seconds"` value. From that point, the waiting time is computed as `"max-backoff-seconds"` value plus a jitter.

- •

  The value for the key *"jobs"* specifies the number of jobs to run. If unset, the number of available cores is used.

- •

  The value for the key *"build"* is a JSON object specifying arguments used by **justbuild** **serve** to orchestrate remote builds.

For subkey *"build jobs"* the value specifies the number of jobs to run during a remote build. If unset, the same value as for outer key *"jobs"* is used.

For subkey *"action timeout"* the value in a number specifying the timeout limit in seconds for actions run during a remote build. If unset, the default value 300 is used.

For subkey *"target-cache write strategy"* the value has to be one of the values *"disable"*, *"sync"*, or *"split"*. The default is *"sync"*, giving the instruction to synchronize artifacts and write target-level cache entries. The value *"split"* does the same using blob splitting when synchronizing artifacts, provided it is supported by the remote-execution endpoint. The value *"disable"* disables adding new entries to the target-level cache, which defeats the purpose of typical set up to share target-level computations between clients.

For the subkey *"local launcher"*, if given, the value has to be a list. This list is used as local launcher for the build in the case the serve process acts simultaneously as remote-execution endpoint. If unset (or `null`), the value `["env", "--"]` will be taken as default.

## EXAMPLE

An example serve configuration file could look as follows.

-

  ```
  { "local build root": {"root": "system", "path": "var/just-serve/root"}
  , "authentication":
    { "ca cert":
      {"root": "system", "path": "etc/just-serve/certs/ca.crt"}
    , "client cert":
      {"root": "system", "path": "etc/just-serve/certs/client.crt"}
    , "client key":
      {"root": "system", "path": "etc/just-serve/certs/client.key"}
    }
  , "remote service":
    { "interface": "192.0.2.1"
    , "port": 9999
    , "pid file":
      {"root": "system", "path": "var/run/just-serve/server.pid"}
    , "server cert":
      {"root": "system", "path": "etc/just-serve/certs/server.crt"}
    , "server key":
      {"root": "system", "path": "etc/just-serve/certs/server.key"}
    }
  , "execution endpoint": {"address": "198.51.100.1:8989"}
  , "repositories":
    [ {"root": "system", "path": "var/just-serve/repos/third-party-distfiles"}
    , {"root": "system", "path": "var/just-serve/repos/project-foo"}
    , {"root": "system", "path": "var/just-serve/repos/project-bar"}
    ]
  , "logging":
    {"files": [{"root": "home", "path": ".log/just-serve/latest"}]}
  , "jobs": 8
  , "build": {"build jobs": 128}
  , "max-attempts": 10
  , "initial-backoff-seconds": 10
  , "max-backoff-seconds": 60
  }
  ```

## See also

[**justbuild**(1)](/justbuild/1.md), [**just-mrrc**(5)](/just-mrrc/5.md)