Skip to content

Updated readme #640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NiveditJain merged 5 commits into from
Jan 2, 2026
Merged

Updated readme #640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a274361
docs: update README to reflect new features and capabilities of Exosp…
NiveditJain Jan 1, 2026
e82ad79
docs: update README to include marketplace feature and release cycle
NiveditJain Jan 1, 2026
0d94661
Update README to improve introduction, feature highlights, and quick …
NiveditJain Jan 1, 2026
4fadd9b
Refactor README and documentation for clarity and structure
nk-ag Jan 2, 2026
a7b581d
fix: correct spelling in project title for consistency
nk-ag Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
332 changes: 70 additions & 262 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,310 +14,118 @@

---

# Exosphere: Distributed AI Workflow Infrastructure
# Exosphere: Reliability Runtime for AI Agents

**Exosphere** is an open-source, Kubernetes-native infrastructure platform designed to run distributed AI workflows and autonomous agents at scale. Built with Python and based on a flexible node-based architecture, Exosphere enables developers to create, deploy, and manage robust AI workflows that can handle large-scale data processing and long-running operations.
**Exosphere** is a lightweight runtime to make AI agents resilient to failure and infinite scaling across distributed compute. With a few changes to your existing agent code, take your agent from demo to deployment.

![Example Workflow Run](/assets/workflow-run.png)

## 🚀 What Exosphere Can Do
## Why Exosphere?

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Example Workflow Run image was removed. Visual aids like screenshots of a workflow or the dashboard can be very effective in conveying what the project does at a glance and can make the README more engaging. Consider adding an updated image or a GIF in this area to showcase the UI or a workflow in action.

Exosphere provides a powerful foundation for building and orchestrating AI applications with these key capabilities:

### **Reliable AI Workflows at Scale**
- **Infinite Parallel Agents**: Run multiple AI agents simultaneously across distributed infrastructure
- **Dynamic State Management**: Create and manage state at runtime with persistent storage
- **Fault Tolerance**: Built-in failure handling and recovery mechanisms for production reliability
- **Core Concepts**: Fanout, Unite, Signals, Retry Policy, Store, Triggers
| Feature | Description |
|---------|-------------|
| [**Lightweight Runtime**](https://docs.exosphere.host/exosphere/architecture) | Execute workflows reliably with minimal overhead across distributed infrastructure using a state-based execution model. |
| [**Inbuilt Failure Handling**](https://docs.exosphere.host/exosphere/retry-policy) | Built-in retry policies with exponential backoff and jitter strategies for resilient, production-grade execution. |
| [**Infinite Parallel Agents**](https://docs.exosphere.host/exosphere/fanout) | Scale to unlimited parallel agents with automatic load distribution and dynamic fanout at runtime. |
| [**Dynamic Execution Graphs**](https://docs.exosphere.host/exosphere/concepts) | Durable execution designed for agentic flows with node-based control of execution. |
| [**Native State Persistence**](https://docs.exosphere.host/exosphere/store) | Persist workflow state across restarts and failures with graph-level key-value storage. |
| [**Observability**](https://docs.exosphere.host/exosphere/dashboard) | Visual monitoring, debugging, and management of workflows with real-time execution tracking. |

### **Smooth Developer Experience**
- **Plug-and-Play Nodes**: Create reusable, atomic workflow components that can be mixed and matched
- **Python-First**: Native Python support with Pydantic models for type-safe inputs/outputs
- **Interactive Dashboard**: Visual workflow management, monitoring, and debugging tools
Whether you're building data pipelines, AI agents, or complex workflow orchestrations, Exosphere provides the infrastructure backbone to make your AI applications production-ready and scalable.

### **Production Ready Infrastructure**
- **Kubernetes Native**: Deploy seamlessly on Kubernetes clusters for enterprise-grade scalability
- **State Persistence**: Maintain workflow state across restarts and failures
- **API Integration**: Connect to external services and APIs through configurable nodes

### **Built for AI Agents**
- **Autonomous Execution**: Build agents that can make decisions and execute complex workflows
- **Data Processing**: Handle large datasets with distributed processing capabilities
- **Long-Running Operations**: Support for workflows that run for hours, days, or indefinitely
---

Whether you're building data pipelines, AI agents, or complex workflow orchestrations, Exosphere provides the infrastructure backbone to make your AI applications production-ready and scalable.
## Run Your First Agent

## 🎯 Use Cases & Applications
| Step | Description |
|------|-------------|
| [**Getting Started**](https://docs.exosphere.host/getting-started) | Get the Exosphere State Manager and Dashboard running locally for development. |
| [**Run Your First Node**](https://docs.exosphere.host/exosphere/register-node) | Create your first node and register it with the Exosphere runtime. |
| [**Trigger Agent**](https://docs.exosphere.host/exosphere/trigger-graph) | Learn how to trigger your agent workflows and manage execution flows. |
| [**Deploy and Monitor**](https://docs.exosphere.host/exosphere/dashboard) | Deploy your agents and monitor their execution with the visual dashboard. |

Exosphere is perfect for a wide range of AI and automation scenarios:
![How does this work?](assets/how.png)

- **Data Processing & ETL Pipelines**
- **AI Agent Orchestration**
- **Content Generation & Analysis**
- **API Integration & Automation**
---

## Architecture Overview
## Architecture Overview

Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Remove trailing space.

Line 54 has a trailing space. Clean this up to comply with markdown linting rules.

🔎 Proposed fix 
-Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows: 
+Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:
Exosphere is built on a flexible, node-based architecture that makes it easy to create complex workflows:
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

54-54: Trailing spaces
Expected: 0 or 2; Actual: 1

(MD009, no-trailing-spaces)

🤖 Prompt for AI Agents 
In README.md around line 54, remove the single trailing space at the end of the
line "Exosphere is built on a flexible, node-based architecture that makes it
easy to create complex workflows:" so the line ends cleanly with the colon;
update the file to trim that trailing whitespace (or run a trim-whitespace/lint
fix) and save the file to satisfy markdown linting rules.


![Exosphere Architecture](assets/exosphere-concepts.png)

### **Core Components**
### Core Components

- **Nodes**: Atomic, reusable units of work that can be AI agents, API calls, data processors, or any custom logic
- **Runtime**: The execution environment that manages and orchestrates your nodes
- **State Manager**: Handles persistent state across workflow executions
- **Dashboard**: Visual interface for monitoring and managing workflows
- **Graphs**: Define the flow and dependencies between nodes
| Component | Description |
|-----------|-------------|
| **Nodes** | Atomic, reusable units of work that can be AI agents, API calls, data processors, or any custom logic |
| **Runtime** | The execution environment that manages and orchestrates your nodes |
| **State Manager** | Handles persistent state across workflow executions |
| **Dashboard** | Visual interface for monitoring and managing workflows |
| **Graphs** | Define the flow and dependencies between nodes |

### **Key Concepts**
### Key Concepts

![Building blocks of Exosphere](assets/exosphere-components.png)

- **Fanout**: Distribute work across multiple parallel instances of a node
- **Unite**: Combine results from multiple parallel executions
- **Signals**: Inter-node communication and event handling
- **Retry Policy**: Configurable failure handling and recovery
- **Store**: Persistent storage for workflow state and data
- **Triggers**: Automatic scheduling with cron expressions

## ⏰ Automatic Scheduling Example

Schedule your workflows to run automatically using cron expressions:

!!! info "Beta Feature"
Available in `beta-latest` Docker tag and SDK version `0.0.3b1`

```python
from exospherehost import StateManager, GraphNodeModel, CronTrigger

# Define triggers for automatic execution
triggers = [
CronTrigger(expression="0 9 * * 1-5"), # Every weekday at 9 AM
CronTrigger(expression="0 */6 * * *") # Every 6 hours
]

# Create graph with automatic scheduling
result = await state_manager.upsert_graph(
graph_name="data-pipeline",
graph_nodes=graph_nodes,
secrets={"api_key": "your-key"},
triggers=triggers # Enable automatic execution (Beta)
)
```

### **Deployment Options**

- **Local Development**: Run with Docker Compose for quick setup
- **Kubernetes**: Production-ready deployment on K8s clusters
- **Cloud**: Deploy on any cloud provider with Kubernetes support

## 🚀 Getting Started

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Step 1: Installation

```bash
uv add exospherehost
```

### Step 2: Create Your First Node

Each node is an atomic, reusable unit in Exosphere. Once registered, you can plug it into any workflow. Nodes can be AI agents, API calls, data processors, or any custom logic you want to execute.

```python
from exospherehost import BaseNode
from pydantic import BaseModel

class CityAnalyzerNode(BaseNode):
"""A node that analyzes and describes a city using AI"""

class Inputs(BaseModel):
city: str
analysis_type: str = "general" # general, tourism, business, etc.

class Outputs(BaseModel):
description: str
key_features: str
score: str

class Secrets(BaseModel):
openai_api_key: str # Optional: for AI-powered analysis

async def execute(self) -> Outputs:
# Your custom logic here - could be:
# - AI agent calls
# - API requests
# - Data processing
# - Database queries
# - Any Python code!

description = f"Analysis of {self.inputs.city}"
features = ["culture", "economy", "lifestyle"]
score = 8.5

return self.Outputs(
description=description,
key_features=json.dumps(features),
score=str(score)
)
```



### Step 3: Create and Start the Runtime

Create the runtime and register your nodes:
```python
from exospherehost import Runtime

# Initialize the runtime with your nodes
runtime = Runtime(
name="city-analysis-runtime",
namespace="my-project",
nodes=[CityAnalyzerNode]
)

# Start the runtime (this will block the main thread)
runtime.start()
```

**Run your application:**
```bash
uv run main.py
```

Your runtime is now running and ready to process workflows! 🎉

### Step 4: Define Your First Graph

Graphs can be defined using JSON objects or with the new model-based Python SDK (beta) for better type safety and validation. See [Graph definitions](https://docs.exosphere.host/exosphere/create-graph/) for more examples.



```python
from exospherehost import StateManager, GraphNodeModel, RetryPolicyModel, RetryStrategyEnum

async def create_graph():
state_manager = StateManager(namespace="hello-world")

graph_nodes = [
GraphNodeModel(
node_name="MyFirstNode",
namespace="hello-world",
identifier="describe_city",
inputs={"city": "initial"},
next_nodes=[]
)
]

# Optional: Define retry policy (beta)
retry_policy = RetryPolicyModel(
max_retries=3,
strategy=RetryStrategyEnum.EXPONENTIAL,
backoff_factor=2000
)

# Create graph with model-based approach (beta)
result = await state_manager.upsert_graph(
graph_name="my-first-graph",
graph_nodes=graph_nodes,
secrets={},
retry_policy=retry_policy # beta
)
```

## Quick Start with Docker Compose

Get Exosphere running locally in under 2 minutes:

```bash
# Option 1: With cloud MongoDB (recommended)
echo "MONGO_URI=your-mongodb-connection-string" > .env
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
docker compose up -d

# Option 2: With local MongoDB (development)
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
docker compose -f docker-compose-with-mongodb.yml up -d
```

**Environment Configuration:**
- Docker Compose automatically loads `.env` files from the working directory
- Create your `.env` file in the same directory as your docker-compose file

Access your services:

- **Dashboard**: `http://localhost:3000`
- **API**: `http://localhost:8000`

> **📝 Note**: This configuration is for **development and testing only**. For production deployments, environment variable customization, and advanced configuration options, please read the complete **[Docker Compose Setup Guide](https://docs.exosphere.host/docker-compose-setup)**.

## 📚 Documentation & Resources
| Concept | Description |
|---------|-------------|
| **Fanout** | Distribute work across multiple parallel instances of a node |
| **Unite** | Combine results from multiple parallel executions |
| **Signals** | Inter-node communication and event handling |
| **Retry Policy** | Configurable failure handling and recovery |
| **Store** | Persistent storage for workflow state and data |
| **Triggers** | Automatic scheduling with cron expressions |

### **Essential Guides**
- **[Getting Started Guide](https://docs.exosphere.host/getting-started)**: Complete walkthrough for new users
- **[Docker Compose Setup](https://docs.exosphere.host/docker-compose-setup)**: Run Exosphere locally in minutes
- **[Architecture Guide](https://docs.exosphere.host/exosphere/architecture)**: Understand core concepts like fanout and unite
- **[Youtube Walkthroughs](https://www.youtube.com/@exospherehost)**: Step by step demos on Exosphere and how to build reliable flows with sample code.
- **[Featured Exosphere Projects](https://github.com/exospherehost/exosphereprojects)**: Templates on common projects on Exosphere, pull and run!
---

### **Advanced Topics**
- **[State Manager Setup](https://docs.exosphere.host/exosphere/state-manager-setup)**: Production deployment guide
- **[Dashboard Guide](https://docs.exosphere.host/exosphere/dashboard)**: Visual workflow management
- **[Graph Definitions](https://docs.exosphere.host/exosphere/create-graph/)**: Building complex workflows
## Resources

### **Community & Support**
- **[Official Documentation](https://docs.exosphere.host)**: Complete reference and tutorials
- **[Discord Community](https://discord.com/invite/zT92CAgvkj)**: Get help and connect with other developers
- **[GitHub Issues](https://github.com/exospherehost/exospherehost/issues)**: Report bugs and request features
- **[PyPI Package](https://pypi.org/project/exospherehost/)**: Latest stable releases
| Resource | Notes |
|----------|-------------|
| [**Getting Started Guide**](https://docs.exosphere.host/getting-started) | Complete walkthrough for new users |
| [**Docker Compose Setup**](https://docs.exosphere.host/docker-compose-setup) | Run Exosphere locally in minutes |
| [**Architecture Guide**](https://docs.exosphere.host/exosphere/architecture) | Understand core concepts like fanout and unite |
| [**YouTube Walkthroughs**](https://www.youtube.com/@exospherehost) | Step-by-step demos on Exosphere with sample code |
| [**Featured Projects**](https://github.com/exospherehost/exosphereprojects) | Templates on common projects, pull and run |


### Community and Support

| Resource | Description |
|----------|-------------|
| [**Official Documentation**](https://docs.exosphere.host) | Complete reference and tutorials |
| [**Discord Community**](https://discord.com/invite/zT92CAgvkj) | Get help and connect with other developers |
| [**GitHub Issues**](https://github.com/exospherehost/exospherehost/issues) | Report bugs and request features |
| [**PyPI Package**](https://pypi.org/project/exospherehost/) | Latest stable releases |

## 🌟 Open Source Commitment
---

We believe that open source is the foundation of innovation and progress. Exosphere is our contribution to this movement, and we're committed to supporting the community in multiple ways:
## Open Source Commitment

### **Our Promise to the Community**
We believe that humanity would not have been able to achieve the level of innovation and progress we have today without the support of open source and community. We want to be a part of this movement.

1. **🔄 Open Source First**: The majority of our codebase is open source and available to everyone
2. **💰 Giving Back**: A portion of our profits goes directly to supporting open source projects and communities
3. **🎓 Mentorship**: We actively collaborate with student programs to mentor the next generation of developers
4. **🤝 Community Driven**: We welcome contributions, feedback, and collaboration from developers worldwide
Please feel free to reach out to us at [nivedit@exosphere.host](mailto:nivedit@exosphere.host). Let's push the boundaries of possibilities for humanity together.

### **Get Involved**
---

- **Contributors**: Help us build the future of AI infrastructure
- **Users**: Your feedback shapes our roadmap and priorities
- **Students**: Join our mentorship programs and grow your skills
- **Organizations**: Partner with us to advance open source AI tools
## Release Cycle and Roadmap

**Ready to make a difference?** Reach out to us at [nivedit@exosphere.host](mailto:nivedit@exosphere.host) and let's push the boundaries of what's possible together! 🚀

## 🎯 Ready to Get Started?
Exosphere follows a predictable, calendar-based release process:

Exosphere is designed to make AI workflow development accessible, scalable, and production-ready. Whether you're building your first AI agent or scaling to thousands of parallel workflows, Exosphere provides the infrastructure you need.

### **Next Steps:**
1. **⭐ Star this repository** to show your support
2. **🚀 Try the quick start** with our Docker Compose setup
3. **💬 Join our Discord** community for help and discussions
4. **📖 Read the docs** for comprehensive guides and examples
5. **🤝 Contribute** to help us build the future of AI infrastructure
| Aspect | Description |
|--------|-------------|
| **Monthly Releases** | A new stable version ships at the end of every month |
| **Issue and PR Labelling** | Work intended for a release is tagged `YYYY:Mon` (e.g., `2026:Jan`). Filter by this label in GitHub to see exactly what is planned |
| **Living Roadmap** | The collection of items carrying the current month's label is our public roadmap. Follow along in GitHub Projects to track progress in real time |

---

## Contributing

We welcome community contributions. For guidelines, refer to our [CONTRIBUTING.md](https://github.com/exospherehost/exospherehost/blob/main/CONTRIBUTING.md).

![exosphere.host Contributors](https://contrib.rocks/image?repo=exospherehost/exospherehost)


Thanks to our awesome contributors!

![exosphere.host Contributors](https://contrib.rocks/image?repo=exospherehost/exospherehost)
Binary file added assets/how.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/docs/exosphere/concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Exosphere Concepts
# Concepts

Exosphere is built around several core concepts that make it unique in the workflow orchestration space. This page provides an overview of these key features and how they work together.
Exosphere is built around several core concepts that make it uniquely positioned for reliable orchestration of agents. This page provides an overview of these key features and how they work together.

## Core Concepts Overview

Expand Down
Loading