diff --git a/README.md b/README.md
index 446814b8..9dddabec 100644
--- a/README.md
+++ b/README.md
@@ -12,42 +12,50 @@ KVVM is served over RPC with [go-plugin](https://github.com/hashicorp/go-plugin)
 
 At its core, the Avalanche protocol still maintains the immutable ordered sequence of states in a fully permissionless settings. And KVVM defines the rules and data structures to store key-value pairs.
 
-## Build the `quarkvm` plugin for AvalancheGo
+## Run `quarkvm` with local network
 
-```bash
-cd ${HOME}/go/src/github.com/ava-labs/quarkvm
-./scripts/build.sh
-
-> Building quarkvm in /Users/patrickogrady/go/src/github.com/ava-labs/avalanchego/build/plugins/tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH
-```
+[`scripts/tests.e2e.sh`](scripts/tests.e2e.sh) automatically installs [avalanchego](https://github.com/ava-labs/avalanchego) to set up a local network, creates `quarkvm` genesis file, and run e2e tests.
 
-## Generate a Gensis File
+See [`tests/e2e`](tests/e2e) and [`tests/runner`](tests/runner) to see how it's set up and how its client requests are made:
 
 ```bash
-./build/quark-cli genesis
-
-> created genesis and saved to /Users/patrickogrady/code/quarkvm/genesis.json
-```
-
-## Clone ava-sim (separate folder)
+# to run full e2e tests and shut down cluster afterwards
+cd ${HOME}/go/src/github.com/ava-labs/quarkvm
+./scripts/tests.e2e.sh 1.7.3
 
-```bash
-git clone https://github.com/ava-labs/ava-sim.git
-./scripts/build.sh
+# to run full e2e tests and keep the cluster alive
+cd ${HOME}/go/src/github.com/ava-labs/quarkvm
+SHUTDOWN=false ./scripts/tests.e2e.sh 1.7.3
 ```
 
-## Start ava-sim
-
 ```bash
-./scripts/run.sh /Users/patrickogrady/go/src/github.com/ava-labs/avalanchego/build/plugins/tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH /Users/patrickogrady/code/quarkvm/genesis.json
-
->>>>>>
-Custom VM endpoints now accessible at:
-NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg: http://127.0.0.1:9650/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa
-NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ: http://127.0.0.1:9652/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa
-NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN: http://127.0.0.1:9654/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa
-NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu: http://127.0.0.1:9656/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa
-NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5: http://127.0.0.1:9658/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa
+# inspect cluster endpoints when ready
+cat /tmp/avalanchego-v1.7.3/output.yaml
+<<COMMENT
+endpoint: /ext/bc/2VCAhX6vE3UnXC6s1CBPE6jJ4c4cHWMfPgCptuWS59pQ9vbeLM
+logsDir: ...
+pid: 12811
+uris:
+- http://localhost:56239
+- http://localhost:56251
+- http://localhost:56253
+- http://localhost:56255
+- http://localhost:56257
+COMMENT
+
+# ping the local cluster
+curl -X POST --data '{
+    "jsonrpc": "2.0",
+    "method": "quarkvm.ping",
+    "params":{},
+    "id": 1
+}' -H 'content-type:application/json;' 127.0.0.1:56239/ext/bc/2VCAhX6vE3UnXC6s1CBPE6jJ4c4cHWMfPgCptuWS59pQ9vbeLM
+<<COMMENT
+{"jsonrpc":"2.0","result":{"success":true},"id":1}
+COMMENT
+
+# to terminate the cluster
+kill 12811
 ```
 
 ## Claim a Prefix (work done automatically)
@@ -56,14 +64,14 @@ NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5: http://127.0.0.1:9658/ext/bc/Bbx6eyUCS
 ./build/quark-cli \
 --private-key-file .quark-cli-pk \
 --url http://127.0.0.1:9650 \
---endpoint /ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa  \
+--endpoint /ext/bc/2VCAhX6vE3UnXC6s1CBPE6jJ4c4cHWMfPgCptuWS59pQ9vbeLM  \
 claim pat
 
 >>>>>
-creating requester with URL http://127.0.0.1:9650 and endpoint "/ext/bc/Bbx6eyUCSzoQLzBbM9gnLDdA9HeuiobqQS53iEthvQzeVqbwa"
+creating requester with URL http://127.0.0.1:9650 and endpoint "/ext/bc/2VCAhX6vE3UnXC6s1CBPE6jJ4c4cHWMfPgCptuWS59pQ9vbeLM"
 Submitting tx NpfRjXRGRCXGxfqq6vcvH3GAm3yijJyxYD7QBxQFDS6YvSnXw with BlockID (zgvHpznxkG7xAh2qgsQFVkrioB4ENdKYfum6KWe6rZGiuzdPf): &{0xc00011a0c8 [175 87 123 222 38 232 10 27 198 13 215 107 60 56 102 21 11 12 195 39 191 122 160 156 155 11 183 164 202 22 22 76 231 28 232 58 18 187 198 249 170 168 232 227 43 85 90 54 94 76 49 184 59 9 194 205 222 162 20 67 208 185 115 12] 0}
 issued transaction NpfRjXRGRCXGxfqq6vcvH3GAm3yijJyxYD7QBxQFDS6YvSnXw (success true)
 polling transaction "NpfRjXRGRCXGxfqq6vcvH3GAm3yijJyxYD7QBxQFDS6YvSnXw"
 confirmed transaction "NpfRjXRGRCXGxfqq6vcvH3GAm3yijJyxYD7QBxQFDS6YvSnXw"
 prefix pat info &{Owner:0xc00011dd70 LastUpdated:1638591044 Expiry:1638591074 Keys:1}
-```
+```
\ No newline at end of file
diff --git a/scripts/tests.e2e.sh b/scripts/tests.e2e.sh
index bc5d8464..01d52d62 100755
--- a/scripts/tests.e2e.sh
+++ b/scripts/tests.e2e.sh
@@ -3,6 +3,9 @@ set -e
 
 # e.g.,
 # ./scripts/tests.e2e.sh 1.7.3
+#
+# to keep the cluster alive
+# SHUTDOWN=false ./scripts/tests.e2e.sh 1.7.3
 if ! [[ "$0" =~ scripts/tests.e2e.sh ]]; then
   echo "must be run from repository root"
   exit 255
@@ -15,6 +18,13 @@ if [[ -z "${VERSION}" ]]; then
   exit 255
 fi
 
+SHUTDOWN=${SHUTDOWN:-true}
+if [[ ${SHUTDOWN} == true ]]; then
+  _SHUTDOWN_FLAG="--shutdown"
+else
+  _SHUTDOWN_FLAG=""
+fi
+
 # download avalanchego
 # https://github.com/ava-labs/avalanchego/releases
 GOARCH=$(go env GOARCH)
@@ -84,10 +94,10 @@ done
 echo "found it!"
 cat /tmp/avalanchego-v${VERSION}/output.yaml
 
-echo "running e2e tests against the local cluster with --shutdown"
+echo "running e2e tests against the local cluster with shutdown flag '${_SHUTDOWN_FLAG}'"
 ./tests/e2e/e2e.test \
 --ginkgo.v \
 --cluster-info-path /tmp/avalanchego-v${VERSION}/output.yaml \
---shutdown
+${_SHUTDOWN_FLAG}
 
 echo "ALL SUCCESS!"