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

# Configuration

> All fields accepted by Groundhog 0.2 in groundhog.toml.

Groundhog reads one TOML file for each deployment.
The default path is `./groundhog.toml`.

Pass another path with the global `--config <PATH>` option.
Relative paths in the file resolve against the file's directory.

`serve`, `seal`, and `verify` validate configuration before they open deployment data, locks, or sockets.
Unknown sections and keys are errors.

## Generated configuration

`groundhog init` writes this file:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[data]
dir = "./data"

[security]
mode = "open"              # open | governed | locked — this build serves only "open"

[integrity]
anchor = "none"   # this binary supports only unsigned local chain heads

[server]
socket = "data/ground.sock"   # the binary's only transport
token = ""                    # empty = no auth (local development)

[replay]
default_limit = 1000
max_limit     = 100000
```

## `[data]`

### `dir`

The directory that contains Groundhog data.
Default: `./data`.

The durable log is `<dir>/log/`.
Groundhog 0.2 does not use a warehouse path.

## `[security]`

### `mode`

The configured security contract.
Default: `open`.

Accepted names are `open`, `governed`, and `locked`.
Groundhog 0.2 serves only `open`.
It refuses other values with exit code 4 before it opens deployment state.

## `[integrity]`

### `anchor`

The configured chain-head anchoring contract.
Default: `none`.

Accepted names are `none`, `signed`, `mirrored`, and `witnessed`.
`serve`, `seal`, and `verify --chain` support only `none`.
They refuse each non-`none` mode with exit code 4.
Plain `verify` checks storage without enforcing this field.

## `[server]`

### `socket`

The Unix domain socket used by `serve`.
Default: `data/ground.sock`.

The service does not listen on TCP.
Clients need filesystem access to this socket.

### `token`

The bearer token required for every HTTP request.
Default: an empty string.

An empty token disables HTTP authentication.
A non-empty token requires this header:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer <token>
```

The file stores the token as plaintext TOML.
Restrict file permissions and do not commit secrets to source control.

## `[replay]`

### `default_limit`

The matching-event limit used when finite replay omits `limit`.
Default: `1000`.

### `max_limit`

The largest accepted finite replay `limit`.
Default: `100000`.

Both values must be positive.
`default_limit` cannot exceed `max_limit`.

Follow mode uses these values as page limits within one open response.
The limit does not end the follow response.

## Upgrade from 0.1

Groundhog 0.2 rejects the removed `[query]` section.
Remove the complete section before starting a 0.2 command.

The exact error is:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
The [query] section is no longer supported. Remove it from groundhog.toml.
```

Do not replace this section with another warehouse setting.
Groundhog 0.2 stores and serves only the durable event log.

## Path example

Given `/srv/acme/groundhog.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[data]
dir = "./state"

[server]
socket = "run/ground.sock"
```

the resolved paths are:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
/srv/acme/state
/srv/acme/run/ground.sock
```

These paths do not depend on the process working directory.

## Reload behavior

Groundhog loads configuration when a command starts.
`serve` does not reload the file while it runs.

Restart the service to apply token, socket, or replay-limit changes.
Changing `data.dir` selects another deployment and does not move data.

## See also

[groundhog(1)](/groundhog/references/cli),
[`init`](/groundhog/commands#init),
[`serve`](/groundhog/commands#serve),
[deployment operations](/groundhog/operations/deployment)