Skip to content

Configuration

This document describes all grite configuration files and options.

Configuration Files

Grite uses two configuration files:

File Scope Purpose
.git/grite/config.toml Repository Repository-wide settings
.git/grite/actors/<id>/config.toml Actor Per-actor settings

Repository Configuration

Location: .git/grite/config.toml

# Default actor for this repository
default_actor = "64d15a2c383e2161772f9cea23e87222"

# Lock policy: off, warn, require
lock_policy = "warn"

[snapshot]
# Create snapshot after this many events
max_events = 10000

# Create snapshot if older than this many days
max_age_days = 7

Options

default_actor

The default actor ID to use when no actor is specified.

  • Type: string (32-character hex)
  • Default: none (auto-created on first use)
  • Set by: grite actor use <id>

Example: 

default_actor = "64d15a2c383e2161772f9cea23e87222"

lock_policy

How to handle lock violations.

  • Type: string
  • Values: off, warn, require
  • Default: warn
Value Behavior
off No lock warnings or enforcement
warn Warn when working on locked resources
require Require lock before modifying resources

Example: 

lock_policy = "require"

[snapshot]

Snapshot creation settings.

max_events

Create a snapshot when event count exceeds this threshold.

  • Type: integer
  • Default: 10000
max_age_days

Create a snapshot when the last snapshot is older than this many days.

  • Type: integer
  • Default: 7

Example: 

[snapshot]
max_events = 5000
max_age_days = 3

Actor Configuration

Location: .git/grite/actors/<actor_id>/config.toml

# Actor ID (required)
actor_id = "64d15a2c383e2161772f9cea23e87222"

# Human-friendly label (optional)
label = "work-laptop"

# Creation timestamp (optional)
created_ts = 1700000000000

# Public key for signature verification (optional)
public_key = "aabbccdd..."

# Key scheme (optional, default: ed25519)
key_scheme = "ed25519"

Options

actor_id

The unique identifier for this actor.

  • Type: string (32-character hex)
  • Required: yes
  • Generated by: grite init or grite actor init

label

Human-friendly name for the actor.

  • Type: string
  • Required: no
  • Set by: grite actor init --label <name>

Example: 

label = "alice-macbook"

created_ts

Timestamp when the actor was created.

  • Type: integer (milliseconds since Unix epoch)
  • Required: no
  • Generated by: grite actor init

public_key

Ed25519 public key for signature verification.

  • Type: string (hex-encoded)
  • Required: no
  • Generated by: grite actor init --generate-key

When present, events from this actor are signed automatically.

key_scheme

Cryptographic scheme for signatures.

  • Type: string
  • Values: ed25519
  • Default: ed25519

Currently only Ed25519 is supported.

Signing Keys

If an actor has a signing key, it's stored at:

.git/grite/actors/<actor_id>/keys/signing.key

This file contains the Ed25519 private key. The corresponding public key is stored in the actor config.

Warning

Never share or commit the signing.key file. It should remain local to each device.

Example Configurations

Minimal Repository Config

default_actor = "64d15a2c383e2161772f9cea23e87222"

Strict Locking

default_actor = "64d15a2c383e2161772f9cea23e87222"
lock_policy = "require"

Frequent Snapshots

default_actor = "64d15a2c383e2161772f9cea23e87222"

[snapshot]
max_events = 1000
max_age_days = 1

Actor with Signing

actor_id = "64d15a2c383e2161772f9cea23e87222"
label = "security-auditor"
created_ts = 1700000000000
public_key = "3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c"
key_scheme = "ed25519"

Configuration Precedence

For actor selection:

  1. --data-dir flag or GRIT_HOME environment variable
  2. --actor flag
  3. default_actor in repository config
  4. Auto-create new actor

Viewing Current Configuration

# Show current actor
grite actor current --json

# Show actor details
grite actor show --json

# Show all actors
grite actor list --json

Next Steps