Skip to main content

Configuration

Graft’s configuration is minimal. The entire project state lives in a single JSON file.

State File

Location: ~/.graft/<project>/config.json
{
  "schema_version": 2,
  "target_container": "my-postgres",
  "active_branch": "main",
  "project_root": "/Users/alice/.graft/my-postgres",
  "mode": "bind",
  "config": {
    "image": "postgres:16",
    "env": [
      "POSTGRES_PASSWORD=secret",
      "POSTGRES_DB=myapp"
    ],
    "exposed_ports": ["5432/tcp"],
    "port_bindings": {
      "5432/tcp": ["127.0.0.1:5432"]
    },
    "network_mode": "bridge",
    "destination": "/var/lib/postgresql/data",
    "volume_name": "myapp_postgres_data"
  },
  "branches": {
    "main": {
      "name": "main",
      "path": "branches/main",
      "size": "289.2M",
      "created_at": "2026-06-04T11:59:00Z",
      "updated_at": "2026-06-04T12:00:00Z"
    },
    "experiment": {
      "name": "experiment",
      "path": "branches/experiment",
      "size": "289.2M",
      "created_at": "2026-06-04T12:01:00Z"
    }
  }
}

Environment Variables

VariableDefaultDescription
GRAFT_HOME~/.graftRoot directory for all Graft project data
GRAFT_RSYNCrsyncPath to rsync binary (used in snapshot mode bridge)

Project Discovery

Graft resolves which project to use through a discovery mechanism:
  1. Current directory check — Looks for .graft/config.json in the current working directory
  2. GRAFT_HOME scan — Scans $GRAFT_HOME/<project>/config.json for all project directories
  3. If exactly one project exists under GRAFT_HOME, it’s used automatically
  4. If multiple projects exist, an error is shown (future: --project flag)

Schema Versioning

Both the state file and the SQLite DAG carry schema versions:
StoreFieldCurrent VersionOn Mismatch
config.jsonschema_version2Error: delete project dir and re-init
graft.dbschema_version table1Error: delete graft.db and re-init
Version mismatches are always a breaking change. The project data must be re-initialized because the storage layout or semantics have changed incompatibly.