Enhance documentation for Runtime blocking behavior and interactive usage

docs/docs/exosphere/create-runtime.md

@@ -4,6 +4,29 @@ The `Runtime` class is the core component that manages the execution environment
 
 ## Runtime Setup
 
+Before creating a runtime, you need to set up the state manager and configure your environment variables.
+
+### Prerequisites
+
+1. **Start the State Manager**: Run the state manager using Docker Compose:
+   ```bash
+   docker-compose up -d
+   ```
+   For detailed setup instructions, see [State Manager Setup](./state-manager-setup.md).
+
+2. **Set Environment Variables**: Configure your authentication:
+   ```bash
+   export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri"
+   export EXOSPHERE_API_KEY="your-api-key"
+   ```
+
+   Or create a `.env` file:
+   ```bash
+   EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri
+   EXOSPHERE_API_KEY=your-api-key
+   ```
+
+### Creating a Runtime
 === "Basic"
 
     ```python hl_lines="17-22"
@@ -68,6 +91,21 @@ The `Runtime` class is the core component that manages the execution environment
 
     ```
 
+!!! warning "Blocking Operation"
+    `Runtime.start()` is a blocking operation that runs indefinitely. In interactive environments like Jupyter notebooks, consider running it in a background thread:
+
+    ```python
+    import threading
+
+    def run_runtime():
+        runtime.start()
+
+    thread = threading.Thread(target=run_runtime, daemon=True)
+    thread.start()
+    ```
+
+    See the [Getting Started guide](../getting-started.md#important-blocking-behavior) for more alternatives.
+
 ## Runtime Parameters
 
 ### Required Parameters

docs/docs/getting-started.md

@@ -86,6 +86,74 @@ Runtime(
 ).start()
 ```
 
+## Important: Blocking Behavior
+
+**Note**: `Runtime.start()` is a blocking operation that will run indefinitely until stopped. This can be problematic in interactive environments like Jupyter notebooks or Python REPLs.
+
+### For Interactive Environments
+
+If you're working in a Jupyter notebook or Python REPL, consider these alternatives:
+
+=== "Background Thread"
+
+    ```python
+    import threading
+
+    # Create the runtime
+    runtime = Runtime(
+        namespace="MyProject",
+        name="DataProcessor",
+        nodes=[SampleNode]
+    )
+
+    # Run in a background thread
+    def run_runtime():
+        runtime.start()
+
+    thread = threading.Thread(target=run_runtime, daemon=True)
+    thread.start()
+
+    # Your interactive session continues here
+    print("Runtime is running in the background!")
+    ```
+
+=== "Asyncio Task"
+
+    ```python
+import asyncio
+
+# Create the runtime
+runtime = Runtime(
+    namespace="MyProject",
+    name="DataProcessor",
+    nodes=[SampleNode]
+)
+
+# In an async context (like a Jupyter notebook),
+# runtime.start() returns a task that runs in the background.
+runtime_task = runtime.start()
+
+# Your interactive session can continue.
+print("Runtime is running in the background!")
+
+# You can now do other async work while the runtime runs.
+# For example:
+# await asyncio.sleep(10)
+# print("Finished waiting.")
+    ```
+
+=== "Production Script"
+
+    ```python
+    # For production scripts, the blocking behavior is usually desired
+    if __name__ == "__main__":
+        Runtime(
+            namespace="MyProject",
+            name="DataProcessor",
+            nodes=[SampleNode]
+        ).start()  # Blocks and runs forever
+    ```
+
 ## Next Steps
 
 Now that you have the basics, explore:
@@ -107,14 +175,10 @@ Now that you have the basics, explore:
 
 ## Architecture
 
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   Your Nodes    │    │     Runtime      │    │ State Manager   │
-│                 │◄──►│                  │◄──►│                 │
-│ - Inputs        │    │ - Registration   │    │ - Orchestration │
-│ - Outputs       │    │ - Execution      │    │ - State Mgmt    │
-│ - Secrets       │    │ - Error Handling │    │ - Dashboard     │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
+```mermaid
+graph LR
+    A["Your Nodes<br/>- Inputs<br/>- Outputs<br/>- Secrets"] <--> B["Runtime<br/>- Registration<br/>- Execution<br/>- Error Handling"]
+    B <--> C["State Manager<br/>- Orchestration<br/>- State Mgmt<br/>- Dashboard"]
 ```
 
 ## Data Model (v1)

docs/docs/index.md

@@ -59,9 +59,12 @@ Runtime(
     namespace="MyProject",
     name="HelloWorld",
     nodes=[HelloWorldNode]
-).start()
+).start()  # Note: This blocks the main thread
 ```
 
+!!! info "Interactive Environments"
+    If you're using Jupyter notebooks or Python REPLs, `Runtime.start()` will block your session. See the [Getting Started guide](./getting-started.md#important-blocking-behavior) for non-blocking alternatives.
+
 ### Run it
 
 Run the server with: