Configuration

lattice.json at the repo root is the only file Lattice reads for configuration. This page lists every field it accepts, with its type, whether it is required, its default, and what an invalid value does. For what the fields mean in practice, see Workspaces, Task graph, Caching, and Engines and provisioning.

Top-level fields

Every top-level key is optional, so {} is a valid lattice.json.

Where the file lives

Every command that reads config walks up from the current directory to the nearest lattice.json and treats that directory as the repo root. Commands therefore work from any subdirectory. With no lattice.json in the current directory or any parent, the command fails before reading anything else:

Error: no lattice.json found in this directory or any parent. Run `lattice init` to create one

$schema

{ "$schema": ".lattice/schema.json" }

A plain string reference, conventionally .lattice/schema.json. That path holds a copy of Lattice’s bundled JSON Schema, written next to your config so that editors with JSON Schema support validate and autocomplete lattice.json as you type. Lattice never reads the value.

lattice run, lattice setup, lattice prune, and lattice stats write .lattice/schema.json only when the file is absent, so a copy you have pinned or hand-edited stays as it is. lattice init writes it unconditionally as part of scaffolding, along with five .gitignore lines: .lattice/cache/, .lattice/toolchains/, .lattice/bin/, .lattice/setup/, and .lattice-setup-marker. .lattice/schema.json is not among them.

Unknown keys

The bundled schema sets additionalProperties: false at every level, and the parser agrees: a key Lattice does not recognize fails the load before any task is scheduled.

Error: unknown field `output` in tasks.build (lattice.json line 5, column 14)
Did you mean `outputs`?
Fields accepted here: dependsOn, inputs, outputs, ignore, env, persistent, cache, timeout

The message names the key, the object it sits in, its position in the file, the closest accepted field, and every field accepted there. A workspace entry is indexed, as in workspaces[1], so the message points at one entry out of several.

There is no way to keep an extra key in the file. A lattice.json carrying a key from an earlier release, or a note under a key of your own, has to drop it.

latticeVersion

{ "latticeVersion": "1.1.1" }

The version of Lattice this repo runs. A non-string value fails to parse. The string itself is not validated at load time. See Upgrading for how the version check uses this field together with settings.versionCheck.

workspaces

{
  "workspaces": [
    { "name": "web", "path": "apps/web" },
    { "name": "api", "path": "apps/api", "dependsOn": ["web"] }
  ]
}

Each entry is one directory with its own manifest. There is no glob form: a bare string array such as "workspaces": ["apps/*"] fails to parse with invalid type: string "apps/*", expected struct WorkspaceConfig. A glob key on an entry fails as an unknown field.

The workspace object

Rejected values:

Path checks read the string as text rather than through the host’s path rules, so a lattice.json that is rejected on one platform is rejected on all of them. Lattice rejects whitespace around a path component for the same reason. Windows strips that whitespace and unix keeps it, so one string would name two directories.

A scripts key supplies the command for the root task of the same name and nothing else, so a key outside tasks never runs. Lattice raises an error rather than accepting such a key, because the workspace would otherwise run its detected command with nothing said about the override. Every key under scripts pairs with a task of the same name:

{
  "workspaces": [
    { "name": "core", "path": "libs/core", "scripts": { "build": "make all" } }
  ],
  "tasks": { "build": {} }
}

A minimal workspace that declares its own commands:

{
  "workspaces": [
    {
      "name": "utils",
      "path": "libs/utils",
      "auto": false,
      "scripts": { "build": "python3 setup.py build" }
    }
  ]
}

engines

{ "engines": { "node": ">=20.0.0", "rust": ">=1.75.0" } }

An engine map is a name-keyed object whose values are either a bare version constraint string or an engine object. Root engines apply to every workspace, and a workspace’s own entry replaces the root entry of the same name. Which fields a value carries selects host mode, validate-only, or provisioning. See Engines and provisioning for the three modes.

A value that is neither a string nor an object fails to parse:

Error: failed to parse lattice.json

Caused by:
    invalid type: integer `123`, expected a version constraint string or an engine object at line 1 column 22

String form

{ "engines": { "node": ">=20.0.0" } }

The bare string form works only for the 40 well-known engine names, which are the names Lattice has a built-in version command for. Every built-in driver is here, plus the language toolchains those drivers sit on top of:

Each name’s version command is on Toolchains.

A string-form engine outside that list fails validation, before any task runs:

Error: engine 'alpes' in root uses the string (version-only) form, but 'alpes' is not a well-known engine Lattice can version-check on its own. Use the object form with an explicit `versionCmd`, e.g. "alpes": { "version": ">=1.0.0", "versionCmd": "alpes --version" }

Object form

{
  "engines": {
    "alpes": {
      "version": ">=2.6.7",
      "versionCmd": "alp --version",
      "installCmd": "curl https://example.com/alp.sh | sh",
      "bin": "bin"
    }
  }
}

The object form accepts any engine name. A name outside the well-known list that carries a version but no versionCmd parses, then fails when Lattice needs the version:

engine 'alpes' has a version constraint but no way to check it (not a well-known engine and no `versionCmd`)

Lattice joins bin to the toolchain’s install directory and puts the result at the front of the PATH of every task that resolves the engine. The check therefore runs when the config loads: bin has to be relative, non-empty, free of whitespace around any component, and inside the install directory. "bin", ".", "usr/local/bin", and "bin/../libexec" all pass. "/usr/bin" and "../../.." are rejected. Either one would put a directory Lattice never provisioned in front of every command, while the run still reported a provisioned toolchain:

engine 'node' in root has a `bin` of '/usr/bin', which is not relative to the toolchain install. Write `bin` as a path inside the toolchain directory, like "bin"

globalDependencies

{
  "globalDependencies": ["tsconfig.base.json", "proto/**", ".env"]
}

Globs relative to the repo root, hashed into the cache key of every task. A task’s inputs are relative to its own workspace, so a file above the workspace cannot be named there in a way that means the same thing everywhere. Editing anything matched here makes every task in the repo miss. Lattice hashes these patterns once at the start of a run, so a malformed pattern fails the whole run rather than one task. See Cache internals.

lattice init writes this key when a workspace’s turbo.json declares globalDependencies. Prune what it brought over on the rule above: a pattern that does not really cross workspaces costs every task a miss.

globalEnv

{
  "globalEnv": ["NODE_ENV", "CI"]
}

Environment variable names whose resolved values feed the cache key of every task. A name with no value is hashed as declared-and-unset, which is a different key from not listing the name at all. Unlike a task’s env, these names are not set on task processes: they are already in the environment Lattice inherited. A task’s own env list applies on top of this one. See Environment variables.

lattice init writes this key too, when a workspace’s turbo.json declares globalEnv.

tasks

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*", "package.json"],
      "outputs": ["dist/**"]
    }
  }
}

Keys are task names you choose. Declaration order is preserved and does not affect execution order, which comes from the dependency graph. Passing a name that is not a key here fails immediately:

Error: task 'build' is not defined in the `tasks` map in lattice.json. Defined tasks: test

With no tasks declared at all, the same error ends with lattice.json defines no tasks.

The task object

timeout accepts ms, s, sec, secs, m, min, mins, h, hr, and hrs, case-insensitive, or a bare whole number of seconds. A string value below one second rounds up to one second. An unrecognized unit fails to parse:

Error: failed to parse lattice.json

Caused by:
    unknown duration unit 'fortnights' in '5 fortnights' at line 1 column 43

The maximum is 365 days, 31536000 seconds, in both forms. Lattice rejects an oversized value rather than clamping it. Past 365 days the deadline overflows instead of arriving, so an oversized timeout would mean no timeout at all:

duration '99999h' is longer than the maximum of 365 days. Use a shorter duration, or leave `timeout` out to let the task run without a limit

The number form is an integer, the way the bundled JSON schema has always declared it. Lattice rejects 1.5 rather than rounding it up to 2. The string form takes decimals, so "1.5m" and "90s" both parse. 90.0 counts as a whole number of seconds:

duration 1.5 is not a whole number of seconds. Write a whole number of seconds, or a duration string such as "90s", "1500ms", or "10m"

A glob in inputs, outputs, ignore, or globalDependencies is compiled when the task’s cache key is computed rather than when the config loads, so a malformed pattern fails that one task:

a:build: failed to compute cache key: error parsing glob 'src/[[': unclosed character class; missing ']'

A dependsOn entry naming a task the map does not define fails validation, and so does a task that names itself:

Error: task 'build' depends on 'tset', but 'tset' is not defined in `tasks`
Defined tasks: build, test

Error: task 'build' lists itself in `dependsOn`

An empty task object is valid. It declares no dependencies, no inputs, and no outputs, and it still caches: its key covers the whole workspace, so it re-runs whenever anything in that directory changes.

{
  "tasks": {
    "dev": { "persistent": true, "cache": false },
    "clean": {}
  }
}

settings

{
  "settings": {
    "maxCacheSize": "10GB",
    "cacheDir": ".lattice/cache",
    "loquacious": false,
    "versionCheck": true
  }
}

maxCacheSize is a string: an integer or decimal followed by B, KB, MB, GB, or TB, base 1024 and case-insensitive. K, M, G, and T are accepted as short forms, and a string of digits with no unit is read as bytes.

{ "settings": { "maxCacheSize": "512MB" } }

A JSON number fails to parse, even though the same digits work as a string:

Error: failed to parse lattice.json

Caused by:
    invalid type: integer `536870912`, expected a string at line 1 column 41

An unrecognized unit fails the same way:

Error: failed to parse lattice.json

Caused by:
    unknown cache size unit 'QB' in '512QB' at line 1 column 36

With settings.maxCacheSize unset, lattice prune needs --max-size:

Error: no cache size limit set. Pass --max-size, or set settings.maxCacheSize in lattice.json

Lattice validates cacheDir when the config loads, and owns the directory cacheDir names: lattice prune deletes the *.tar.gz, *.meta.json, and *.tmp files it finds there. The value therefore has to be relative, has to stay inside the repo, and cannot resolve to the repo root. ".lattice/cache" and ".cache/lattice" both pass. "." does not, because it would point prune at the top of the repo:

Error: `settings.cacheDir` is '.', which is the repo root itself. Point it at a directory of its own, like ".lattice/cache" — `lattice prune` deletes cache archives and partial writes in whatever directory it names

"/tmp/lattice" and "../cache" are rejected as well, each with its own message. See Errors for all five.

When each check runs

Everything at the parsing and validation stages is raised before Lattice looks at a single workspace directory, so nothing has run when you see it.

Complete example

A repo with a Node app, a Rust service, and a Python library:

{
  "$schema": ".lattice/schema.json",
  "latticeVersion": "1.1.1",
  "workspaces": [
    { "name": "web", "path": "apps/web", "engines": { "node": ">=20.0.0" } },
    {
      "name": "api",
      "path": "services/api",
      "dependsOn": ["shared"]
    },
    {
      "name": "shared",
      "path": "libs/shared",
      "auto": false,
      "scripts": {
        "build": "python3 -m build",
        "test": "python3 -m pytest",
        "lint": "python3 -m ruff check ."
      }
    }
  ],
  "engines": {
    "rust": ">=1.75.0",
    "protoc": {
      "version": ">=25.0.0",
      "versionCmd": "protoc --version",
      "installCmd": "curl -fsSL https://example.com/protoc.sh | sh -s -- \"$LATTICE_TOOLCHAIN_DIR\"",
      "bin": "bin"
    }
  },
  "globalDependencies": ["tsconfig.base.json", "proto/**"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*", "Cargo.toml", "package.json"],
      "ignore": ["**/*.test.*"],
      "outputs": ["dist/**", "target/release/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*", "tests/**/*"],
      "env": ["DATABASE_URL"],
      "timeout": "10m"
    },
    "lint": {
      "inputs": ["src/**/*"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    },
    "clean": {}
  },
  "settings": {
    "maxCacheSize": "10GB",
    "versionCheck": true
  }
}