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

# Configuration

> State file format and project discovery.

# Configuration

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

## State File

Location: `~/.graft/<project>/config.json`

```json theme={null}
{
  "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

| Variable      | Default    | Description                                         |
| ------------- | ---------- | --------------------------------------------------- |
| `GRAFT_HOME`  | `~/.graft` | Root directory for all Graft project data           |
| `GRAFT_RSYNC` | `rsync`    | Path 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:

| Store         | Field                  | Current Version | On Mismatch                           |
| ------------- | ---------------------- | --------------- | ------------------------------------- |
| `config.json` | `schema_version`       | 2               | Error: delete project dir and re-init |
| `graft.db`    | `schema_version` table | 1               | Error: 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.