From 22806b6efb04bc54d97a427684c2ee2318796934 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 30 Jan 2026 06:49:07 +0000
Subject: [PATCH 1/2] Initial plan


From 3157b41207315cb1808441194205c40ef44833aa Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 30 Jan 2026 06:51:14 +0000
Subject: [PATCH 2/2] Add documentation for FOC_DEVNET_BASEDIR environment
 variable

Co-authored-by: redpanda-f <181817029+redpanda-f@users.noreply.github.com>
---
 README.md          |  1 +
 README_ADVANCED.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/README.md b/README.md
index ff98b66..e8a8710 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,7 @@ Built for scripting and automation:
 - **Contract addresses**: `~/.foc-devnet/run/<run-id>/contract_addresses.json`
 - **Step context**: `~/.foc-devnet/run/<run-id>/step_context.json`
 - **Latest run symlink**: `~/.foc-devnet/state/latest/` → points to most recent run
+- **Custom base directory**: Set `FOC_DEVNET_BASEDIR` env var to override default `~/.foc-devnet` location (see [Environment Variables](README_ADVANCED.md#environment-variables))
 - Write scripts for testing, demos, CI/CD pipelines, etc.
 
 ### 🌐 Isolated Networks
diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 4c3d75b..b5f21bb 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -219,6 +219,63 @@ foc-devnet init --force
 
 ---
 
+### Environment Variables
+
+#### `FOC_DEVNET_BASEDIR`
+
+**Purpose:** Overrides the default `~/.foc-devnet` directory location.
+
+**Use Cases:**
+- **Testing multiple isolated environments:** Run separate instances of foc-devnet with different configurations
+- **Custom directory locations:** Store data on a specific disk or partition (e.g., for SSD/HDD optimization)
+- **CI/CD pipelines:** Use predictable paths in automated testing environments
+- **Shared team environments:** Keep different team members' instances isolated
+
+**Tilde Expansion:**
+The variable supports tilde (`~`) expansion, so you can use paths like `~/my-custom-foc` or `~/projects/foc-test`.
+
+**Example Usage:**
+
+```bash
+# Use a custom directory with tilde expansion
+export FOC_DEVNET_BASEDIR=~/foc-test-env
+foc-devnet init
+foc-devnet start
+
+# Use an absolute path
+export FOC_DEVNET_BASEDIR=/mnt/ssd/foc-devnet
+foc-devnet init
+
+# Run multiple isolated instances (in different terminals)
+# Terminal 1:
+export FOC_DEVNET_BASEDIR=~/foc-env-1
+foc-devnet start
+
+# Terminal 2:
+export FOC_DEVNET_BASEDIR=~/foc-env-2
+foc-devnet start
+```
+
+**Default Behavior:**
+If `FOC_DEVNET_BASEDIR` is not set, foc-devnet uses `~/.foc-devnet` as the base directory.
+
+**Directory Structure:**
+When `FOC_DEVNET_BASEDIR` is set, all data directories are created under the specified path instead of `~/.foc-devnet`:
+```
+$FOC_DEVNET_BASEDIR/
+├── config.toml
+├── bin/
+├── code/
+├── docker/volumes/
+├── keys/
+├── logs/
+├── run/
+├── state/
+└── tmp/
+```
+
+---
+
 ## Directory Structure
 
 ```