{node.name}
diff --git a/docs/docs/api-server/index.md b/docs/docs/api-server/index.md
deleted file mode 100644
index 7cbe0120..00000000
--- a/docs/docs/api-server/index.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# API Server
-API Server is essentially the public interface of the Exosphere platform for the users to interact with. API Server is created in fastapi and has following core apps, each independent of each other.
-
-## Project
-Project is a logical grouping and separation of the resources within exosphere ecosystem, thus each project has its unique namespace and billing details attached to it.
-
-Note: Currently all users within a project have same access to all resources within the project. Billing information is set once and cannot be changed, these could be changed only by the exosphere team on email request as of now.
-
-### Project Model
-```json
-{
- "_id":{
- "type": ObjectId,
- "required": true,
- "description": "Unique identifier for the project, auto generated by database"
- },
- "name":{
- "type": String,
- "required": true,
- "description": "Human readable name of the project"
- },
- "status":{
- "type": String,
- "required": true,
- "description": "Status of the project, active, inactive, blocked, deleted (enum)"
- },
- "billing_account":{
- "type": {
- "company_name": {
- "type": String,
- "required": true,
- "description": "Name of the company"
- },
- "company_address": {
- "type": String,
- "required": true,
- "description": "Address of the company"
- },
- "tax_number_type": {
- "type": String,
- "required": true,
- "description": "Type of the tax number, vat, gst, etc. (enum)"
- },
- "tax_number": {
- "type": String,
- "required": true,
- "description": "Tax number of the company"
- },
- "country": {
- "type": String,
- "required": true,
- "description": "Country of the company"
- }
- },
- "required": true,
- "description": "Billing account of the project, reference to the billing account document"
- },
- "users": [
- {
- {
- "role": {
- "type": String,
- "required": true,
- "description": "Role of the user in the project, admin, user, etc. (enum)"
- },
- "user": {
- "type": ObjectId,
- "required": true,
- "description": "Reference to the user document"
- }
- }
- }
- ],
- "super_admin": {
- "type": ObjectId,
- "required": true,
- "description": "Reference to the user document, super admin of the project"
- },
- "created_at":{
- "type": DateTime,
- "required": true,
- "description": "Date and time when the project was created"
- },
- "updated_at":{
- "type": DateTime,
- "required": true,
- "description": "Date and time when the project was last updated"
- }
-}
-```
-
-## User
-Model representing exosphere user.
-
-### User Model
-```json
-{
- "_id":{
- "type": ObjectId,
- "required": true,
- "description": "Unique identifier for the user, auto generated by database"
- },
- "name":{
- "type": String,
- "required": true,
- "description": "Human readable name of the user"
- },
- "type": {
- "type": String,
- "required": true,
- "description": "Type of the user, human, api, etc. (enum)"
- },
- "identifier": {
- "type": String,
- "required": true,
- "description": "Identifier of the user, email, phone, etc. (string)"
- },
- "verification_status": {
- "type": String,
- "required": true,
- "description": "Verification status of the user, verified, not_verified, blocked, deleted, not_required (enum)"
- },
- "credential": {
- "type": String,
- "required": true,
- "description": "Credential of the user, password, key, etc. (string)"
- },
- "status": {
- "type": String,
- "required": true,
- "description": "Status of the user, active, inactive, deleted, blocked (enum)"
- },
- "created_at":{
- "type": DateTime,
- "required": true,
- "description": "Date and time when the user was created"
- },
- "updated_at":{
- "type": DateTime,
- "required": true,
- "description": "Date and time when the user was last updated"
- }
-}
-```
-
-## Auth
-The main role of this project is to issue tokens and verify the users and APIs to access the resources within the projects.
diff --git a/docs/docs/api-server/swagger.md b/docs/docs/api-server/swagger.md
deleted file mode 100644
index 99b1c365..00000000
--- a/docs/docs/api-server/swagger.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# Swagger
-All api definitions and swagger documentation is available at [https://api.exosphere.host/docs](https://api.exosphere.host/docs)
\ No newline at end of file
diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md
deleted file mode 100644
index abf08c14..00000000
--- a/docs/docs/architecture.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Architecture
-This page explains the architecture of working and implementation of `satellites`, `orbit` and working of apis and api server.
-
-
-
-## API Server
-The main job of the API server is to handle the requests from the user and make sure of the following:
-
-- Authentication
-- Authorization
-- Rate Limiting
-- Error Handling
-
-Further pass the request to the controller to handle the workflow gracefully.
-
-## Controller
-This is like the brain of the system and is responsible for the following:
-
-- Scheduling the workflows
-- Managing the state of the workflows
-- Handling the errors
-- Handling the logs
-- Requested necessary infrastructure resources to manage the satellites
-
-
-## Orbit
-Container holding one or more satellites is referred as `orbit`. There are certain rules with each `orbit` has to follow:
-
-- Should be a self-contained unit
-- Should define the minimum hardware requirements
-- Should implement standard exosphere interfaces and protocols
-
-## Infra Manager
-The role of the infra manager is to manage the underlying infrastructure and hardware resources as per the instructions from the controller.
\ No newline at end of file
diff --git a/docs/docs/assets/DashboardSS-1.png b/docs/docs/assets/DashboardSS-1.png
new file mode 100644
index 00000000..646586af
Binary files /dev/null and b/docs/docs/assets/DashboardSS-1.png differ
diff --git a/docs/docs/assets/DashboardSS-2.png b/docs/docs/assets/DashboardSS-2.png
new file mode 100644
index 00000000..7e1c8a43
Binary files /dev/null and b/docs/docs/assets/DashboardSS-2.png differ
diff --git a/docs/docs/assets/DashboardSS-3.jpg b/docs/docs/assets/DashboardSS-3.jpg
new file mode 100644
index 00000000..f788b1c5
Binary files /dev/null and b/docs/docs/assets/DashboardSS-3.jpg differ
diff --git a/docs/docs/cluster.md b/docs/docs/cluster.md
deleted file mode 100644
index 6eb8b99f..00000000
--- a/docs/docs/cluster.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Cluster
-A cluster is a group of satellites that are run together. They are defined in a YAML file and executed as a single job. You can define a cluster in a YAML file and deploy it on ExosphereHost infrastructure within minutes.
-
-Adding more examples to this section to make clusters clearer. Further, we are working on Pythonic control flow to make clusters more flexible and powerful.
\ No newline at end of file
diff --git a/docs/docs/exosphere/architecture.md b/docs/docs/exosphere/architecture.md
new file mode 100644
index 00000000..9ec34a38
--- /dev/null
+++ b/docs/docs/exosphere/architecture.md
@@ -0,0 +1,149 @@
+# Exosphere Architecture
+
+This document provides a comprehensive overview of Exosphere's top-level architecture, focusing on state execution, fanout mechanisms, and the unites keyword for stage unification.
+
+## Overview
+
+Exosphere is built around a **state-based execution model** where workflows are composed of discrete states that can be executed independently. The architecture consists of several key components:
+
+- **State Manager**: Central orchestrator that manages state lifecycle and transitions
+- **Runtimes**: Distributed execution engines that process individual states
+- **Graph Templates**: Declarative workflow definitions
+- **States**: Individual execution units with inputs, outputs, and metadata
+
+## State Execution Model
+
+### State Lifecycle
+
+Each state in Exosphere follows a well-defined lifecycle:
+
+```
+CREATED → QUEUED → EXECUTED/ERRORED → SUCCESS
+```
+
+1. **CREATED**: State is initialized with inputs and dependencies
+2. **QUEUED**: State is ready for execution and waiting for a runtime
+3. **EXECUTED**: State finished (with outputs) — terminal for that state
+4. **ERRORED**: State failed during executionState and all its dependencies are complete
+5. **SUCCESS**: Workflow/branch-level success once all dependent states complete
+
+
+## Fanout Mechanism
+
+### Single vs Multiple Outputs
+
+Exosphere supports two execution patterns:
+
+1. **Single Output**: A state produces one output and continues to the next stage
+2. **Multiple Outputs (Fanout)**: A state produces multiple outputs, creating parallel execution paths
+
+
+### Fanout Example
+
+Consider a data processing workflow:
+
+```python hl_lines="9-11"
+class DataSplitterNode(BaseNode):
+ async def execute(self) -> list[Outputs]:
+ data = json.loads(self.inputs.data)
+ chunk_size = 100
+
+ outputs = []
+ for i in range(0, len(data), chunk_size):
+ chunk = data[i:i + chunk_size]
+ outputs.append(self.Outputs(
+ chunk=json.dumps(chunk)
+ ))
+
+ return outputs # This creates fanout on each output
+```
+
+When this node executes:
+1. **Original state** gets the first chunk as output
+2. **Additional states** are created for each remaining chunk
+3. **All states** are marked as EXECUTED
+4. **Next stages** are created for each state independently
+
+**This enables parallel processing of data chunks across multiple runtime instances.**
+
+## Unites Keyword
+
+### Purpose
+
+The `unites` keyword is a powerful mechanism for **synchronizing parallel execution paths**. It allows a node to wait for multiple parallel states to complete before executing.
+
+### Unites Logic
+
+When a node has a `unites` configuration:
+
+1. **Execution is deferred** until all states with the specified identifier are complete
+2. **State fingerprinting** ensures only one unites state is created per unique combination
+3. **Dependency validation** ensures the unites node depends on the specified identifier
+
+### Unites Example
+
+```json hl_lines="22-24"
+{
+ "nodes": [
+ {
+ "node_name": "DataSplitterNode",
+ "identifier": "data_splitter",
+ "next_nodes": ["processor_1"]
+ },
+ {
+ "node_name": "DataProcessorNode",
+ "identifier": "processor_1",
+ "inputs":{
+ "x":"${{data_splitter.outputs.data_chunk}}"
+ }
+ "next_nodes": ["result_merger"]
+ },
+ {
+ "node_name": "ResultMergerNode",
+ "identifier": "result_merger",
+ "inputs":{
+ "x_processed":"${{processor_1.outputs.processed_data}}"
+ }
+ "unites": {
+ "identifier": "data_splitter"
+ },
+ "next_nodes": []
+ }
+ ]
+}
+```
+
+In this example:
+1. `data_splitter` creates fanout with 3 outputs
+2. `processor_1` executes in parallel for all three data chunks
+3. `result_merger` waits for all processors to complete (unites with `data_splitter`)
+4. Only one `result_merger` state is created due to fingerprinting
+
+## Architecture Benefits
+
+### Scalability
+
+- **Horizontal scaling**: Add more runtime instances to handle increased load
+- **Parallel processing**: Fanout enables concurrent execution
+- **Load distribution**: State manager distributes work across available runtimes
+
+### Fault Tolerance
+
+- **State persistence**: All states are stored in the database
+- **Retry mechanisms**: Failed states can be retried automatically
+- **Recovery**: Workflows can resume from where they left off
+
+### Flexibility
+
+- **Dynamic fanout**: Nodes can produce variable numbers of outputs
+- **Synchronization**: Unites keyword provides precise control over parallel execution
+- **Dependency management**: Automatic resolution of complex dependencies
+
+### Observability
+
+- **State tracking**: Complete visibility into execution progress
+- **Error handling**: Detailed error information and retry logic
+- **Performance monitoring**: Track execution times and resource usage
+
+
+Exosphere's architecture provides a robust foundation for building distributed, scalable workflows. The combination of state-based execution, fanout mechanisms, and the unites keyword enables complex parallel processing patterns while maintaining simplicity and reliability.
\ No newline at end of file
diff --git a/docs/docs/exosphere/create-graph.md b/docs/docs/exosphere/create-graph.md
new file mode 100644
index 00000000..11d20395
--- /dev/null
+++ b/docs/docs/exosphere/create-graph.md
@@ -0,0 +1,296 @@
+# Create Graph
+
+Graphs in Exosphere define executions by connecting nodes together. A graph template specifies the nodes, their connections, and how data flows between them. This guide shows you how to create and manage graph templates.
+
+## Graph Structure
+
+A graph template consists of:
+
+- **Nodes**: The processing units in your workflow with their inputs and next nodes
+- **Secrets**: Configuration data shared across nodes
+- **Input Mapping**: How data flows between nodes using `${{ ... }}` syntax
+
+## Basic Graph Example
+
+One can define a graph on Exosphere through a simple json config, which specifies the nodes and their relationships on the graph.
+
+```json
+{
+ "secrets": {
+ "openai_api_key": "your-openai-key",
+ "database_url": "your-database-url"
+ },
+ "nodes": [
+ {
+ "node_name": "DataLoaderNode",
+ "namespace": "MyProject",
+ "identifier": "data_loader",
+ "inputs": {
+ "source": "initial",
+ "format": "json"
+ },
+ "next_nodes": ["data_processor"]
+ },
+ {
+ "node_name": "DataProcessorNode",
+ "namespace": "MyProject",
+ "identifier": "data_processor",
+ "inputs": {
+ "raw_data": "${{ data_loader.outputs.processed_data }}",
+ "config": "initial"
+ },
+ "next_nodes": ["data_validator"]
+ },
+ {
+ "node_name": "DataValidatorNode",
+ "namespace": "MyProject",
+ "identifier": "data_validator",
+ "inputs": {
+ "data": "${{ data_processor.outputs.processed_data }}",
+ "validation_rules": "initial"
+ },
+ "next_nodes": []
+ }
+ ]
+}
+```
+
+## Components
+
+### Secrets
+
+Define secrets as an object with key-value pairs:
+
+```json
+{
+ "secrets": {
+ "openai_api_key": "your-openai-key",
+ "aws_access_key_id": "your-aws-key",
+ "aws_secret_access_key": "your-aws-secret",
+ "aws_region": "us-east-1",
+ "database_url": "your-database-url"
+ }
+}
+```
+
+**Fields:**
+
+- **Keys**: Secret names that will be available to all nodes
+- **Values**: The actual secret values (in production, these should be encrypted)
+
+### Nodes
+
+Define the nodes in your workflow with their inputs and next nodes:
+
+```json
+{
+ "nodes": [
+ {
+ "node_name": "NodeClassName",
+ "namespace": "MyProject",
+ "identifier": "unique_node_id",
+ "inputs": {
+ "input_field": "initial_value",
+ "mapped_field": "${{ source_node.outputs.output_field }}"
+ },
+ "next_nodes": ["next_node_identifier"]
+ }
+ ]
+}
+```
+
+**Fields:**
+
+- **`node_name`**: The class name of the node (must be registered)
+- **`namespace`**: The namespace where the node is registered
+- **`identifier`**: Unique identifier for the node in this graph
+- **`inputs`**: Input values for the node
+- **`next_nodes`**: Array of node identifiers that this node connects to
+
+### Input Mapping
+
+Use the `${{ ... }}` syntax to map outputs from previous nodes:
+
+```json
+{
+ "inputs": {
+ "static_value": "initial",
+ "mapped_value": "${{ source_node.outputs.output_field }}",
+ "nested_mapping": "${{ source_node.outputs.nested.field }}"
+ }
+}
+```
+
+**Mapping Syntax:**
+
+- **`${{ node_identifier.outputs.field_name }}`**: Maps output from a specific node
+- **`initial`**: Static value provided when the graph is triggered
+- **Direct values**: String values. In v1, numbers/booleans must be string-encoded (e.g., "42", "true").
+## Creating Graph Templates
+
+The recommended way to create graph templates is using the Exosphere Python SDK, which provides a clean interface to the State Manager API.
+
+```python hl_lines="5-9 23-27"
+from exospherehost import StateManager
+
+async def create_graph_template():
+ # Initialize the State Manager
+ state_manager = StateManager(
+ namespace="MyProject",
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY
+ )
+
+ # Define the graph nodes
+ graph_nodes = [
+ ... #nodes from the namespace MyProject
+ ]
+
+ # Define secrets
+ secrets = {
+ ... # Store real values in a secret manager or environment variables, not in code.
+ }
+
+ try:
+ # Create or update the graph template
+ result = await state_manager.upsert_graph(
+ graph_name="my-workflow",
+ graph_nodes=graph_nodes,
+ secrets=secrets
+ )
+ print("Graph template created successfully!")
+ print(f"Validation status: {result['validation_status']}")
+ return result
+ except Exception as e:
+ print(f"Error creating graph template: {e}")
+ raise
+
+# Run the function
+import asyncio
+asyncio.run(create_graph_template())
+```
+## Input Mapping Patterns
+
+=== "Field Mapping"
+
+ ```json
+ {
+ "inputs": {
+ "data": "${{ source_node.outputs.data }}"
+ }
+ }
+ ```
+
+=== "Static Values"
+
+ ```json
+ {
+ "inputs": {
+ "config_value": "static_value",
+ "number_value": "42",
+ "boolean_value": "true"
+ }
+ }
+ ```
+
+## Graph Validation
+
+The state manager validates your graph template:
+
+### Node Validation
+
+- All nodes must be registered in the specified namespace
+- Node identifiers must be unique within the graph
+- Node names must match registered node classes
+
+### Input Validation
+
+- Mapped fields must exist in source node schemas
+- Input field names must match node input schemas
+- No circular dependencies allowed in `next_nodes`
+
+### Secret Validation
+
+- All referenced secrets must be defined in the secrets object
+- Secret names must be valid identifiers
+
+## Graph Management
+
+=== "Get Graph Template"
+
+ ```python hl_lines="11"
+ from exospherehost import StateManager
+
+ async def get_graph_template():
+ state_manager = StateManager(
+ namespace="MyProject",
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY
+ )
+
+ try:
+ graph_info = await state_manager.get_graph("my-workflow")
+ print(f"Graph validation status: {graph_info['validation_status']}")
+ print(f"Number of nodes: {len(graph_info['nodes'])}")
+ print(f"Validation errors: {graph_info['validation_errors']}")
+ return graph_info
+ except Exception as e:
+ print(f"Error getting graph template: {e}")
+ raise
+
+ # Get graph information
+ graph_info = asyncio.run(get_graph_template())
+ ```
+
+=== "Update Graph Template"
+
+ ```python hl_lines="17 21-25"
+ async def update_graph_template():
+ state_manager = StateManager(
+ namespace="MyProject",
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY
+ )
+
+ # Updated graph nodes
+ updated_nodes = [
+ ...
+ ]
+
+ # Updated secrets
+ updated_secrets = {
+ "openai_api_key": "your-openai-key",
+ "database_url": "your-database-url",
+ "logging_endpoint": "your-logging-endpoint" # Added new secret
+ }
+
+ try:
+ result = await state_manager.upsert_graph(
+ graph_name="my-workflow",
+ graph_nodes=updated_nodes,
+ secrets=updated_secrets
+ )
+ print("Graph template updated successfully!")
+ print(f"Validation status: {result['validation_status']}")
+ return result
+ except Exception as e:
+ print(f"Error updating graph template: {e}")
+ raise
+
+ # Update the graph
+ asyncio.run(update_graph_template())
+ ```
+
+## Graph Visualization
+
+The Exosphere dashboard provides visual representation of your graphs. Checkout the [Dashboard Guide](./dashboard.md)
+
+- **Node View**: See all nodes and their connections via `next_nodes`
+- **Execution Flow**: Track how data flows through the graph using input mapping
+- **State Monitoring**: Monitor execution states in real-time
+- **Error Tracking**: Identify and debug failed executions
+
+## Next Steps
+
+- **[Trigger Graph](./trigger-graph.md)** - Learn how to execute your workflows
+- **[Dashboard](./dashboard.md)** - Use the Exosphere dashboard for monitoring
diff --git a/docs/docs/exosphere/create-runtime.md b/docs/docs/exosphere/create-runtime.md
new file mode 100644
index 00000000..30cd0807
--- /dev/null
+++ b/docs/docs/exosphere/create-runtime.md
@@ -0,0 +1,276 @@
+# Create Runtime
+
+The `Runtime` class is the core component that manages the execution environment for your Exosphere nodes. It handles node registration, state polling, execution, and communication with the state manager.
+
+## Runtime Setup
+
+=== "Basic"
+
+ ```python hl_lines="17-22"
+ from exospherehost import Runtime, BaseNode
+ from pydantic import BaseModel
+
+ class MyNode(BaseNode):
+ class Inputs(BaseModel):
+ data: str
+
+ class Outputs(BaseModel):
+ result: str
+
+ class Secrets(BaseModel):
+ pass
+
+ async def execute(self) -> Outputs:
+ return self.Outputs(result=f"Processed: {self.inputs.data}")
+
+ # Create and start the runtime
+ Runtime(
+ namespace="MyProject",
+ name="MyRuntime",
+ nodes=[MyNode]
+ ).start()
+
+ ```
+
+=== "Advanced"
+
+ ```python hl_lines="17-30"
+ from exospherehost import Runtime, BaseNode
+ from pydantic import BaseModel
+
+ class MyNode(BaseNode):
+ class Inputs(BaseModel):
+ data: str
+
+ class Outputs(BaseModel):
+ result: str
+
+ class Secrets(BaseModel):
+ pass
+
+ async def execute(self) -> Outputs:
+ return self.Outputs(result=f"Processed: {self.inputs.data}")
+
+ # Create runtime with custom configuration
+ runtime = Runtime(
+ namespace="MyProject",
+ name="MyRuntime",
+ nodes=[MyNode],
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY,
+ batch_size=32,
+ workers=8,
+ poll_interval=2
+ )
+
+ # Start the runtime
+ runtime.start()
+
+ ```
+
+## Runtime Parameters
+
+### Required Parameters
+
+- **`namespace`** (str): The namespace for your project. Used to organize and isolate your nodes and workflows.
+- **`name`** (str): The name of this runtime instance. Must be unique within your namespace.
+- **`nodes`** (List[type[BaseNode]]): List of node classes to register and execute.
+
+### Optional Parameters
+
+- **`state_manager_uri`** (str | None): URI of the state manager service. If not provided, uses `EXOSPHERE_STATE_MANAGER_URI` environment variable.
+- **`key`** (str | None): API key for authentication. If not provided, uses `EXOSPHERE_API_KEY` environment variable.
+- **`batch_size`** (int): Number of states to fetch per poll. Defaults to 16.
+- **`workers`** (int): Number of concurrent worker threads. Defaults to 4.
+- **`state_manager_version`** (str): State manager API version. Defaults to "v0".
+- **`poll_interval`** (int): Seconds between polling for new states. Defaults to 1.
+
+## Environment Configuration
+
+Create a `.env` file in your project root:
+
+```bash
+EXOSPHERE_STATE_MANAGER_URI=https://your-state-manager.exosphere.host
+EXOSPHERE_API_KEY=your-api-key
+```
+
+Then load it in your code:
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from exospherehost import Runtime, BaseNode
+
+# Your runtime code here...
+```
+
+## Runtime Lifecycle
+
+### 1. Initialization
+
+The runtime validates configuration and node classes:
+
+```python
+runtime = Runtime(
+ namespace="MyProject",
+ name="MyRuntime",
+ nodes=[MyNode]
+)
+```
+
+### 2. Execution
+
+The runtime starts polling for states and executing nodes:
+
+```python
+runtime.start()
+```
+
+## Multiple Nodes
+
+You can register multiple nodes in a single runtime:
+
+```python hl_lines="10-16"
+from exospherehost import Runtime, BaseNode
+from pydantic import BaseModel
+
+class DataProcessorNode(BaseNode):
+ ...
+
+class DataValidatorNode(BaseNode):
+ ...
+
+# Register both nodes
+Runtime(
+ namespace="MyProject",
+ name="DataPipeline",
+ nodes=[DataProcessorNode, DataValidatorNode]
+).start()
+
+```
+
+## Runtime Configuration Best Practices
+
+### Batch Size and Workers
+
+Choose appropriate values based on your workload:
+
+```python hl_lines="4 13"
+# For CPU-intensive tasks
+Runtime(
+ namespace="MyProject",
+ name="CPU",
+ nodes=[MyNode],
+ batch_size=8, # Smaller batches
+ workers=2 # Fewer workers
+).start()
+
+# For GPU-intensive tasks
+Runtime(
+ namespace="MyProject",
+ name="GPU",
+ nodes=[MyNode],
+ batch_size=32, # Larger batches
+ workers=16 # More workers
+).start()
+```
+
+### Poll Interval
+
+Adjust based on your latency requirements:
+
+```python hl_lines="6 14"
+# For real-time processing
+Runtime(
+ namespace="MyProject",
+ name="RealTime",
+ nodes=[MyNode],
+ poll_interval=1 # Poll every second
+).start()
+
+# For batch processing
+Runtime(
+ namespace="MyProject",
+ name="Batch",
+ nodes=[MyNode],
+ poll_interval=10 # Poll every 10 seconds
+).start()
+```
+
+## Logging
+
+The runtime provides built-in logging:
+
+```python
+import logging
+
+# Configure logging level
+logging.basicConfig(level=logging.INFO)
+
+# The runtime will log:
+# - Node registration
+# - State polling
+# - Execution results
+# - Errors and retries
+```
+
+## Production Deployment
+
+### Docker Deployment
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+CMD ["python", "main.py"]
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: exosphere-runtime
+spec:
+ replicas: 3
+ selector:
+ matchLabels:
+ app: exosphere-runtime
+ template:
+ metadata:
+ labels:
+ app: exosphere-runtime
+ spec:
+ containers:
+ - name: runtime
+ image: your-registry/exosphere-runtime:latest
+ env:
+ - name: EXOSPHERE_STATE_MANAGER_URI
+ value: "https://your-state-manager.exosphere.host"
+ - name: EXOSPHERE_API_KEY
+ valueFrom:
+ secretKeyRef:
+ name: exosphere-secrets
+ key: api-key
+```
+
+## Monitoring
+
+Monitor your runtime using the Exosphere dashboard:
+
+- **Node Status**: View registered nodes and their health
+- **Execution Metrics**: Monitor throughput and error rates
+- **State Management**: Track state transitions and completion
+- **Error Logs**: Debug failed executions
+
+## Next Steps
+
+- **[Register Node](./register-node.md)** - Learn how to create custom nodes
+- **[Create Graph](./create-graph.md)** - Build workflows by connecting nodes
+- **[Trigger Graph](./trigger-graph.md)** - Execute and monitor workflows
diff --git a/docs/docs/exosphere/dashboard.md b/docs/docs/exosphere/dashboard.md
new file mode 100644
index 00000000..83cae101
--- /dev/null
+++ b/docs/docs/exosphere/dashboard.md
@@ -0,0 +1,161 @@
+# Exosphere Dashboard
+
+The Exosphere dashboard provides a comprehensive web interface for monitoring, debugging, and managing your workflows. This guide shows you how to set up and use the dashboard effectively.
+
+## Dashboard Overview
+
+The Exosphere dashboard is a modern web application that connects to your state manager backend and provides:
+
+- **Real-time monitoring** of workflow execution
+- **Visual graph representation** of your workflows
+- **State management** and debugging tools
+- **Performance metrics** and analytics
+- **Error tracking** and resolution
+- **Graph template management** and validation
+
+## Setup Guide
+
+### Prerequisites
+
+Before setting up the dashboard, ensure you have:
+- A running Exosphere state manager (see [State Manager Setup](./state-manager-setup.md))
+- Your API key and namespace from the state manager
+- Docker (for containerized deployment)
+
+=== "Docker (Recommended)"
+
+ The easiest way to run the dashboard is using the pre-built Docker container. This approach ensures consistent environments and minimal setup.
+
+ #### Prerequisites
+
+ - Docker installed
+
+ #### Setup Steps
+
+ 1. **Pull the latest dashboard image and run**:
+ ```bash
+ # Pull the latest dashboard image
+ docker pull ghcr.io/exospherehost/exosphere-dashboard:latest
+
+ # Run the dashboard container
+ docker run -d \
+ --name exosphere-dashboard \
+ -p 3000:3000 \
+ -e NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL="http://localhost:8000" \
+ ghcr.io/exospherehost/exosphere-dashboard:latest
+ ```
+
+ 2. **Verify the service is running**:
+ ```bash
+ # Check container status
+ docker ps
+
+ # Check logs
+ docker logs exosphere-dashboard
+
+ # Test the dashboard
+ curl http://localhost:3000
+ ```
+
+ The dashboard will be available at `http://localhost:3000`
+
+ #### Required Environment Variables
+
+ | Variable | Description | Required | Default |
+ |----------|-------------|----------|---------|
+ | `NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL` | State manager API endpoint | Yes | - |
+
+=== "Local Development"
+
+ For development or customization, you can run the dashboard locally using the source code.
+
+ #### Prerequisites
+
+ - Node.js 18 or higher
+ - npm or yarn package manager
+ - Git
+
+ #### Setup Steps
+
+ 1. **Clone the repository**:
+ ```bash
+ git clone https://github.com/exospherehost/exospherehost.git
+ cd exospherehost/dashboard
+ ```
+
+ 2. **Install dependencies**:
+ ```bash
+ npm install
+ ```
+
+ 3. **Set up environment variables**:
+ ```bash
+ cp .env.example .env
+ # Edit .env with your configuration
+ ```
+
+ 4. **Start the development server**:
+ ```bash
+ npm run dev
+ ```
+
+ The dashboard will be available at `http://localhost:3000`
+
+ #### Environment Variables
+
+ Create a `.env` file in the dashboard directory with these variables:
+
+ ```bash
+ # State manager API endpoint
+ NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL=http://localhost:8000
+ ```
+
+## Dashboard Interface
+
+The Exosphere dashboard features a clean, modern interface with three main sections accessible via the navigation tabs at the top.
+
+
+
+View registered nodes, and graph templates on a namespace
+
+
+
+
+View graph runs and debug each node that was created.
+
+## Using the Dashboard
+
+1. **Configure Connection**:
+
+ - Set your namespace in the header
+ - Enter your API key
+ - Ensure your state manager is running
+
+2. **Explore Overview**:
+
+ - Review registered nodes and their capabilities
+ - Check graph template status and validation
+ - Monitor namespace statistics
+
+3. **Manage Templates**:
+
+ - View existing graph templates
+ - Create new templates using the builder
+ - Validate template configurations
+
+4. **Monitor Execution**:
+
+ - Select specific run IDs to track
+ - View real-time execution progress
+ - Debug failed states and errors
+
+### Support
+
+For additional help:
+- Check the [State Manager Setup](./state-manager-setup.md) guide
+- Review [Architecture](./architecture.md) for workflow understanding
+
+## Next Steps
+
+- **[Architecture](./architecture.md)** - Learn about fanout, units, inputs, outputs, and secrets
+- **[State Manager Setup](./state-manager-setup.md)** - Complete backend setup guide
diff --git a/docs/docs/exosphere/getting-started.md b/docs/docs/exosphere/getting-started.md
new file mode 100644
index 00000000..28f43f7b
--- /dev/null
+++ b/docs/docs/exosphere/getting-started.md
@@ -0,0 +1,147 @@
+# Getting Started
+
+## Installation
+
+```bash
+uv add exospherehost
+```
+
+## Environment Setup
+
+Set up your environment variables for authentication:
+=== ".env File"
+
+ ```bash
+ EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri
+ EXOSPHERE_API_KEY=your-api-key
+ ```
+=== "Environment Variables"
+
+ ```bash
+ export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri"
+ export EXOSPHERE_API_KEY="your-api-key"
+ ```
+
+Refer: [Getting State Manager URI](./state-manager-setup.md)
+
+## Overview
+
+Exosphere is built around three core concepts:
+
+### 1. Nodes
+
+Nodes are the building blocks of your workflows. Each node:
+
+- Defines input/output schemas using Pydantic models
+- Implements an `execute` method for processing logic
+- Can be connected to other nodes to form **workflows**
+- Automatically handles state persistence
+
+### 2. Runtime
+
+The `Runtime` class manages the execution environment and coordinates with the ExosphereHost state manager. It handles:
+
+- Node lifecycle management
+- State coordination
+- Error handling and recovery
+- Resource allocation
+
+### 3. State Manager
+
+The state manager orchestrates workflow execution, manages state transitions, and provides the dashboard for monitoring and debugging.
+
+## Quick Start Example
+
+Create a simple node that processes data:
+
+```python
+from exospherehost import Runtime, BaseNode
+from pydantic import BaseModel
+
+class SampleNode(BaseNode):
+ class Inputs(BaseModel):
+ name: str
+ data: str
+
+ class Outputs(BaseModel):
+ message: str
+ processed_data: str
+
+ class Secrets(BaseModel):
+ pass
+
+ async def execute(self) -> Outputs:
+ print(f"Processing data for: {self.inputs.name}")
+ processed_data = f"completed:{self.inputs.data}"
+ return self.Outputs(
+ message="success",
+ processed_data=processed_data
+ )
+
+# Initialize the runtime
+Runtime(
+ namespace="MyProject",
+ name="DataProcessor",
+ nodes=[SampleNode]
+).start()
+```
+
+## Next Steps
+
+Now that you have the basics, explore:
+
+- **[Register Node](./register-node.md)** - Understand how to create and register custom nodes
+- **[Create Runtime](./create-runtime.md)** - Learn how to set up and configure your runtime
+- **[Create Graph](./create-graph.md)** - Build workflows by connecting nodes together
+- **[Trigger Graph](./trigger-graph.md)** - Execute your workflows and monitor their progress
+
+## Key Features
+
+- **Distributed Execution**: Run nodes across multiple compute resources
+- **State Management**: Automatic state persistence and recovery
+- **Type Safety**: Full Pydantic integration for input/output validation
+- **String-only data model (v1)**: All `Inputs`, `Outputs`, and `Secrets` fields are strings
+- **Async Support**: Native async/await support for high-performance operations
+- **Error Handling**: Built-in retry mechanisms and error recovery
+- **Scalability**: Designed for high-volume batch processing and workflows
+
+## Architecture
+
+```
+┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
+│ Your Nodes │ │ Runtime │ │ State Manager │
+│ │◄──►│ │◄──►│ │
+│ - Inputs │ │ - Registration │ │ - Orchestration │
+│ - Outputs │ │ - Execution │ │ - State Mgmt │
+│ - Secrets │ │ - Error Handling │ │ - Dashboard │
+└─────────────────┘ └──────────────────┘ └─────────────────┘
+```
+
+## Data Model (v1)
+
+**Important**: In v1, all fields in `Inputs`, `Outputs`, and `Secrets` must be strings. If you need to pass complex data (e.g., JSON), serialize the data to a string first, then parse that string within your node.
+
+```python
+class MyNode(BaseNode):
+ class Inputs(BaseModel):
+ # ✅ Correct - string fields
+ user_id: str
+ config: str # JSON string
+
+ class Outputs(BaseModel):
+ # ✅ Correct - string fields
+ result: str
+ metadata: str # JSON string
+
+ class Secrets(BaseModel):
+ # ✅ Correct - string fields
+ api_key: str
+ database_url: str
+```
+
+## Support
+
+For support and questions:
+- **Email**: [nivedit@exosphere.host](mailto:nivedit@exosphere.host)
+- **Documentation**: [https://docs.exosphere.host](https://docs.exosphere.host)
+- **GitHub Issues**: [https://github.com/exospherehost/exospherehost/issues](https://github.com/exospherehost/exospherehost/issues)
diff --git a/docs/docs/exosphere/index.md b/docs/docs/exosphere/index.md
new file mode 100644
index 00000000..294cb435
--- /dev/null
+++ b/docs/docs/exosphere/index.md
@@ -0,0 +1,130 @@
+# Exosphere
+
+Exosphere is an open-source infrastructure layer to run distributed AI workflows and agents with Python based on a node-based architecture.
+
+---
+
+**Documentation**: [https://docs.exosphere.host](https://docs.exosphere.host)
+
+**Source Code**: [https://github.com/exospherehost/exospherehost](https://github.com/exospherehost/exospherehost)
+
+---
+
+## Requirements
+
+Python 3.12+
+
+## Installation
+
+```bash
+uv add exospherehost
+```
+
+## Example
+
+### Create it
+
+Create a file `main.py` with:
+
+```python
+from exospherehost import Runtime, BaseNode
+from pydantic import BaseModel
+
+class HelloWorldNode(BaseNode):
+ class Inputs(BaseModel):
+ name: str
+
+ class Outputs(BaseModel):
+ message: str
+
+ class Secrets(BaseModel):
+ pass
+
+ async def execute(self) -> Outputs:
+ return self.Outputs(
+ message=f"Hello, {self.inputs.name}!"
+ )
+
+# Initialize the runtime
+Runtime(
+ namespace="MyProject",
+ name="HelloWorld",
+ nodes=[HelloWorldNode]
+).start()
+```
+
+### Run it
+
+Run the server with:
+
+```bash
+uv run main.py
+```
+
+### Check it
+
+Your runtime is now running and ready to process workflows!
+
+### Interactive Dashboard
+
+Now go to your Exosphere dashboard to:
+
+* View your registered nodes
+* Create and manage graph templates
+* Trigger workflows
+* Monitor execution states
+* Debug and troubleshoot
+
+Ref: [Dashboard Guide](./dashboard.md)
+
+## Example flow
+
+Now modify the file `main.py` to add more complex processing:
+
+```python
+from exospherehost import Runtime, BaseNode
+from pydantic import BaseModel
+import json
+
+class DataProcessorNode(BaseNode):
+ class Inputs(BaseModel):
+ data: str
+ operation: str
+
+ class Outputs(BaseModel):
+ result: str
+ status: str
+
+ class Secrets(BaseModel):
+ api_key: str
+
+ async def execute(self) -> Outputs:
+ # Parse the input data
+ try:
+ data = json.loads(self.inputs.data)
+ except:
+ return self.Outputs(
+ result="",
+ status="error: invalid json"
+ )
+
+ # Process based on operation
+ if self.inputs.operation == "transform":
+ result = {"transformed": data, "processed": True}
+ else:
+ result = {"original": data, "processed": False}
+
+ return self.Outputs(
+ result=json.dumps(result),
+ status="success"
+ )
+
+# Initialize the runtime
+Runtime(
+ namespace="MyProject",
+ name="DataProcessor",
+ nodes=[DataProcessorNode]
+).start()
+```
+
+The runtime will automatically reload and register the updated node.
diff --git a/docs/docs/exosphere/register-node.md b/docs/docs/exosphere/register-node.md
new file mode 100644
index 00000000..00a178ee
--- /dev/null
+++ b/docs/docs/exosphere/register-node.md
@@ -0,0 +1,151 @@
+# Register Node
+
+Nodes are the building blocks of Exosphere workflows. Each node defines a specific piece of processing logic with typed inputs, outputs, and secrets. This guide shows you how to create and register custom nodes.
+
+## Node Structure
+
+Every node inherits from `BaseNode` and defines three key components:
+
+```python
+from exospherehost import BaseNode
+from pydantic import BaseModel
+
+class MyNode(BaseNode):
+ class Inputs(BaseModel):
+ # Define your input fields here
+ pass
+
+ class Outputs(BaseModel):
+ # Define your output fields here
+ pass
+
+ class Secrets(BaseModel):
+ # Define your secret fields here
+ pass
+
+ async def execute(self) -> Outputs:
+ # Implement your processing logic here
+ pass
+```
+
+### Inputs
+
+Define the data your node expects to receive:
+
+```python
+class Inputs(BaseModel):
+ user_id: str
+ data: str
+ config: str # JSON string for complex configuration
+ batch_size: str = "100" # Default value
+```
+
+### Outputs
+
+Define the data your node produces:
+
+```python
+class Outputs(BaseModel):
+ processed_data: str
+ metadata: str # JSON string for complex metadata
+ status: str
+ count: str
+```
+
+### Secrets
+
+Define sensitive configuration data your node needs:
+
+```python
+class Secrets(BaseModel):
+ api_key: str
+ database_url: str
+ encryption_key: str
+```
+
+## Node Validation
+
+The runtime automatically validates your nodes:
+
+```python hl_lines="19"
+from exospherehost import BaseNode
+from pydantic import BaseModel
+
+# ✅ Valid node
+class ValidNode(BaseNode):
+ class Inputs(BaseModel):
+ data: str # All fields must be strings
+
+ class Outputs(BaseModel):
+ result: str # All fields must be strings
+
+ class Secrets(BaseModel):
+ api_key: str # All fields must be strings
+
+ async def execute(self) -> Outputs:
+ return self.Outputs(result="success")
+
+# ❌ Invalid node - non-string fields
+class InvalidNode(BaseNode):
+ class Inputs(BaseModel):
+ data: str
+ count: int # Error: must be str
+
+ class Outputs(BaseModel):
+ result: str
+
+ class Secrets(BaseModel):
+ pass
+
+ async def execute(self) -> Outputs:
+ return self.Outputs(result="success")
+```
+
+## Node Registration
+
+Nodes are automatically registered when you start your runtime:
+
+```python hl_lines="14"
+from exospherehost import Runtime, BaseNode
+
+# Create your nodes
+class Node1(BaseNode):
+ # ... node implementation
+
+class Node2(BaseNode):
+ # ... node implementation
+
+# Register nodes with runtime
+Runtime(
+ namespace="MyProject",
+ name="MyRuntime",
+ nodes=[Node1, Node2] # Both nodes will be registered
+).start()
+```
+
+## Node Naming and Organization
+
+### Namespace Organization
+
+Organise nodes to a namespace to reuse them across flows in that namespace
+
+```python hl_lines="3 10"
+# Development namespace
+Runtime(
+ namespace="dev",
+ name="MyRuntime",
+ nodes=[MyNode]
+).start()
+
+# Production namespace
+Runtime(
+ namespace="prod",
+ name="MyRuntime",
+ nodes=[MyNode]
+).start()
+```
+
+## Next Steps
+
+- **[Create Graph](./create-graph.md)** - Learn how to connect nodes into workflows
+- **[Trigger Graph](./trigger-graph.md)** - Execute and monitor your workflows
diff --git a/docs/docs/exosphere/state-manager-setup.md b/docs/docs/exosphere/state-manager-setup.md
new file mode 100644
index 00000000..9ea5c593
--- /dev/null
+++ b/docs/docs/exosphere/state-manager-setup.md
@@ -0,0 +1,244 @@
+# State Manager Setup Guide
+
+This guide provides step-by-step instructions for setting up the Exosphere state manager in both local and production environments.
+
+## Overview
+
+The Exosphere state manager is the core backend service that handles workflow execution, state management, and coordination between nodes. It provides a REST API for managing graph templates, registered nodes, and workflow execution states.
+
+## Local Setup
+
+=== "Docker (Recommended)"
+
+ The easiest way to run the state manager locally is using Docker. This approach ensures consistent environments and minimal setup.
+
+ ### Prerequisites
+
+ - Docker installed
+
+ ### Setup Steps
+
+ 1. **Pull the public image and run**:
+ ```bash
+ docker run -d \
+ --name exosphere-state-manager \
+ -p 8000:8000 \
+ -e MONGO_URI="your-mongodb-connection-string" \
+ -e MONGO_DATABASE_NAME="your-database-name" \
+ -e STATE_MANAGER_SECRET="your-secret-key" \
+ -e SECRETS_ENCRYPTION_KEY="your-base64-encoded-encryption-key" \
+ ghcr.io/exospherehost/state-manager:latest
+ ```
+
+ 2. **Verify the service is running**:
+ ```bash
+ # Check container status
+ docker ps
+
+ # Check logs
+ docker logs exosphere-state-manager
+
+ # Test the API
+ curl http://localhost:8000/health
+ ```
+
+ The state manager will be available at `http://localhost:8000`
+
+ ### Required Environment Variables
+
+ | Variable | Description | Required |
+ |----------|-------------|----------|
+ | `MONGO_URI` | MongoDB connection string | Yes |
+ | `MONGO_DATABASE_NAME` | Database name | Yes |
+ | `STATE_MANAGER_SECRET` | Secret API key for authentication | Yes |
+ | `SECRETS_ENCRYPTION_KEY` | Base64-encoded key for data encryption | Yes |
+
+=== "Local Development"
+
+ For development or when you need more control over the environment, you can run the state manager locally using the source code.
+
+ ### Prerequisites
+
+ - Python 3.12 or higher
+ - uv package manager
+ - Git
+
+ ### Setup Steps
+
+ 1. **Clone the repository**:
+ ```bash
+ git clone https://github.com/exospherehost/exospherehost.git
+ cd exospherehost/state-manager
+ ```
+
+ 2. **Install dependencies**:
+ ```bash
+ uv sync
+ ```
+
+ 3. **Set up environment variables**:
+ ```bash
+ export MONGO_URI="your-mongodb-connection-string"
+ export MONGO_DATABASE_NAME="your-database-name"
+ export STATE_MANAGER_SECRET="your-secret-key"
+ export SECRETS_ENCRYPTION_KEY="your-base64-encoded-encryption-key"
+ ```
+
+ 4. **Run the state manager**:
+ ```bash
+ uv run run.py --mode=development
+ ```
+
+ The state manager will be available at `http://localhost:8000`
+
+The state manager uri and key would be configured accordingly while setting up nodes and graphs as per the config given locally.
+
+## Production Setup
+
+=== "Exosphere Hosted Platform"
+
+ For production workloads, we recommend using the hosted Exosphere platform. This provides managed infrastructure with high availability, automatic scaling, and enterprise-grade security.
+
+ ### Getting Started
+
+ 1. **Get your credentials from the Exosphere dashboard**:
+ - State manager URL
+ - API key for authentication
+ - Namespace configuration
+
+ 2. **Contact us for setup assistance**:
+ - Email: [nivedit@exosphere.host](mailto:nivedit@exosphere.host)
+
+ 3. **Configure your application**:
+ ```python
+ from exospherehost import Runtime
+
+ Runtime(
+ namespace="your-namespace",
+ name="YourWorkflow",
+ nodes=[YourNodes],
+ state_manager_uri="https://api.exosphere.host",
+ key="your-production-api-key"
+ ).start()
+ ```
+
+=== "Self-Hosted Deployment"
+
+ For organizations that need complete control over their infrastructure, you can deploy the state manager on your own infrastructure.
+
+ ### Prerequisites
+
+ - Kubernetes cluster (recommended) or Docker Swarm
+ - MongoDB cluster (Atlas, DocumentDB, or self-hosted)
+ - Load balancer and ingress controller
+ - SSL certificates for HTTPS
+
+ ### Docker Deployment
+
+ 1. **Create a Docker Compose file for production**:
+ ```yaml
+ version: '3.8'
+
+ services:
+ state-manager:
+ image: ghcr.io/exospherehost/exosphere-state-manager:latest
+ ports:
+ - "8000:8000"
+ environment:
+ - MONGO_URI=${MONGO_URI}
+ - MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME}
+ - STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET}
+ - SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY}
+ deploy:
+ replicas: 3
+ update_config:
+ parallelism: 1
+ delay: 10s
+ restart_policy:
+ condition: on-failure
+ ```
+
+ 2. **Deploy to your infrastructure**:
+ ```bash
+ docker-compose -f docker-compose.prod.yml up -d
+ ```
+
+ ### Kubernetes Deployment
+
+ 3. **Create namespace**:
+ ```bash
+ kubectl create namespace exosphere
+ ```
+
+ 4. **Create ConfigMap for configuration**:
+ ```yaml
+ apiVersion: v1
+ kind: ConfigMap
+ metadata:
+ name: state-manager-config
+ namespace: exosphere
+ data:
+ MONGO_URI: "your-mongodb-connection-string"
+ MONGO_DATABASE_NAME: "your-database-name"
+ LOG_LEVEL: "INFO"
+ ```
+
+ 5. **Create Secret for sensitive data**:
+ ```yaml
+ apiVersion: v1
+ kind: Secret
+ metadata:
+ name: state-manager-secrets
+ namespace: exosphere
+ type: Opaque
+ data:
+ STATE_MANAGER_SECRET:
+ SECRETS_ENCRYPTION_KEY:
+ ```
+
+ 6. **Deploy the state manager**:
+ ```bash
+ kubectl apply -f k8s/state-manager-deployment.yaml
+ kubectl apply -f k8s/state-manager-service.yaml
+ kubectl apply -f k8s/state-manager-ingress.yaml
+ ```
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `MONGO_URI` | MongoDB connection string | Yes | - |
+| `MONGO_DATABASE_NAME` | Database name | Yes | `exosphere` |
+| `STATE_MANAGER_SECRET` | Secret API key for authentication | Yes | - |
+| `SECRETS_ENCRYPTION_KEY` | Base64-encoded key for data encryption | Yes | - |
+| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | No | `INFO` |
+
+## Monitoring and Health Checks
+
+### Health Check Endpoint
+
+The state manager provides a health check endpoint:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Response: 200
+```json
+{"message": "OK"}
+```
+
+### Getting Help
+
+- **Documentation**: [docs.exosphere.host](https://docs.exosphere.host)
+- **GitHub Issues**: [github.com/exospherehost/exospherehost/issues](https://github.com/exospherehost/exospherehost/issues)
+- **Discord Community**: [discord.gg/exosphere](https://discord.gg/exosphere)
+- **Email Support**: [support@exosphere.host](mailto:support@exosphere.host)
+
+## Next Steps
+
+- **[Dashboard Setup](./dashboard.md)** - Set up the web dashboard for monitoring
+- **[Node Development](./register-node.md)** - Learn how to create and register nodes
+- **[Graph Creation](./create-graph.md)** - Build workflows using graph templates
diff --git a/docs/docs/exosphere/trigger-graph.md b/docs/docs/exosphere/trigger-graph.md
new file mode 100644
index 00000000..cc217ec0
--- /dev/null
+++ b/docs/docs/exosphere/trigger-graph.md
@@ -0,0 +1,54 @@
+# Trigger Graph
+
+Once you have created a graph template, you can trigger its execution by sending trigger states to the state manager. This guide shows you how to trigger graphs and monitor their execution.
+
+The recommended way to trigger graphs is using the Exosphere Python SDK, which provides a clean interface to the State Manager API.
+
+=== "Exosphere Python SDK"
+
+ ```python
+ from exospherehost import StateManager, TriggerState
+
+ async def trigger_graph():
+ # Initialize state manager
+ state_manager = StateManager(
+ namespace="MyProject",
+ state_manager_uri=EXOSPHERE_STATE_MANAGER_URI,
+ key=EXOSPHERE_API_KEY
+ )
+
+ # Create trigger state
+ trigger_state = TriggerState(
+ identifier="data_loader", # Must match a node identifier in your graph
+ inputs={
+ "source": "/path/to/data.csv",
+ "format": "csv",
+ "batch_size": "1000"
+ }
+ )
+
+ try:
+ # Trigger the graph
+ result = await state_manager.trigger("my-graph", state=trigger_state)
+ print(f"Graph triggered successfully!")
+ print(f"Run ID: {result['run_id']}")
+ return result
+ except Exception as e:
+ print(f"Error triggering graph: {e}")
+ raise
+
+ # Run the function
+ import asyncio
+ asyncio.run(trigger_graph())
+ ```
+
+## Monitoring on Exosphere Dashboard
+
+The Exosphere dashboard provides a powerful web-based interface for monitoring your graphs in real-time.
+
+For more details on using the Exosphere dashboard see the **[Dashboard Guide](./dashboard.md)**.
+
+## Next Steps
+
+- **[Dashboard](./dashboard.md)** - Use the Exosphere dashboard for monitoring
+- **[ARchitecture](./architecture.md)** - Learn about fanout, unites
diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css
index 532fac81..5c87eecb 100644
--- a/docs/docs/stylesheets/extra.css
+++ b/docs/docs/stylesheets/extra.css
@@ -18,11 +18,11 @@
--md-typeset-a-color: #daf5ff;
--md-code-fg-color: #daf5ff;
- --md-code-bg-color: #101219;
+ --md-code-bg-color: #263048;
--md-code-hl-color: #66d1b5;
- --md-code-hl-color--light: #8bdfff;
+ --md-code-hl-color--light: #0c246994;
--md-code-hl-number-color: hsla(0, 67%, 50%, 1);
@@ -71,7 +71,7 @@
--md-code-bg-color: #daf5ff;
--md-code-hl-color: #031035;
- --md-code-hl-color--light: #8bdfff;
+ --md-code-hl-color--light: #8bffaa4f;
--md-code-hl-number-color: hsla(0, 67%, 50%, 1);
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 1ee8a7bc..80b76bbf 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -96,20 +96,16 @@ plugins:
Introduction:
- index.md
- getting-started.md
- Satellites:
- - satellites/index.md
- - satellites/exospherehost/call-webhook.md
- - satellites/exospherehost/deepseek-r1-distrill-llama-70b.md
- - satellites/exospherehost/forward-logs.md
- - satellites/exospherehost/get-files.md
- - satellites/exospherehost/move-file.md
- - satellites/exospherehost/parse-with-docling.md
- - satellites/exospherehost/send-alert.md
- - satellites/exospherehost/send-email.md
- Cluster:
- - cluster.md
- Architecture:
- - architecture.md
+ Exosphere:
+ - exosphere/index.md
+ - exosphere/getting-started.md
+ - exosphere/state-manager-setup.md
+ - exosphere/register-node.md
+ - exosphere/create-runtime.md
+ - exosphere/create-graph.md
+ - exosphere/trigger-graph.md
+ - exosphere/dashboard.md
+ - exosphere/architecture.md
markdown_extensions:
- pymdownx.highlight:
@@ -119,25 +115,21 @@ markdown_extensions:
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
+ - admonition
+ - pymdownx.details
+ - pymdownx.tabbed:
+ alternate_style: true
extra_css:
- stylesheets/extra.css
nav:
- - Introduction: index.md
- - Getting Started: getting-started.md
- - Satellites:
- - Overview: satellites/index.md
- - exospherehost/deepseek-r1-distrill-llama-70b: satellites/exospherehost/deepseek-r1-distrill-llama-70b.md
- - exospherehost/get-files: satellites/exospherehost/get-files.md
- - exospherehost/parse-with-docling: satellites/exospherehost/parse-with-docling.md
- - exospherehost/call-webhook: satellites/exospherehost/call-webhook.md
- - exospherehost/forward-logs: satellites/exospherehost/forward-logs.md
- - exospherehost/move-file: satellites/exospherehost/move-file.md
- - exospherehost/send-alert: satellites/exospherehost/send-alert.md
- - exospherehost/send-email: satellites/exospherehost/send-email.md
- - Cluster: cluster.md
- - Architecture: architecture.md
- - API Server:
- - Overview: api-server/index.md
- - Swagger: api-server/swagger.md
\ No newline at end of file
+ - Introduction: exosphere/index.md
+ - Getting Started: exosphere/getting-started.md
+ - State Manager Setup: exosphere/state-manager-setup.md
+ - Register Node: exosphere/register-node.md
+ - Create Runtime: exosphere/create-runtime.md
+ - Create Graph: exosphere/create-graph.md
+ - Trigger Graph: exosphere/trigger-graph.md
+ - Dashboard: exosphere/dashboard.md
+ - Architecture: exosphere/architecture.md
\ No newline at end of file
-