Skip to content

Local Setup Guide

This guide walks you through setting up Exosphere locally for development and testing. You'll learn how to run both the state manager and dashboard components, either using Docker Compose for quick setup or running them individually for more control.

Overview

Exosphere consists of two main components that work together:

  1. State Manager - Backend service that handles workflow execution and state management
  2. Dashboard - Web interface for monitoring and managing workflows

You can set these up using:

  • Docker Compose (recommended for quick start) - runs both services together
  • Individual Setup - run each service separately for development

Prerequisites

Before you begin, ensure you have:

Setup

The fastest way to get Exosphere running locally is using Docker Compose. This approach handles all the configuration and networking automatically.

Follow the guide: Get Exosphere running locally with Docker

If you prefer more control over each component or want to develop locally, you can set up the state manager and dashboard separately.

To get Exosphere state manager running, follow State Manager Setup

For complete monitoring dashboard setup details, see our Dashboard Guide.

Testing Your Setup

Once both services are running, test the complete setup:

  1. Verify state manager: 

    curl http://localhost:8000/health

  2. Verify dashboard: 

    curl http://localhost:3000

  3. Check API documentation:

  4. Open http://localhost:8000/docs in your browser
  5. Test the /health endpoint

Next Steps

With your local Exosphere instance running, you're ready to:

  1. Register your first node - Create custom processing logic
  2. Create and run workflows - Build your first workflow
  3. Monitor execution - Use the dashboard to track progress
  • Fanout - Create parallel execution paths dynamically
  • Unite - Synchronize parallel execution paths
  • Retry Policy - Build resilient workflows
  • Store - Persist data across workflow execution

Troubleshooting

Common Issues

Port conflicts: If ports 8000 or 3000 are already in use, modify the port mappings in your Docker commands or configuration files.

MongoDB connection: Ensure your MongoDB instance is accessible and the connection string is correct.

Authentication errors: Verify that EXOSPHERE_API_KEY matches STATE_MANAGER_SECRET.

Dashboard can't connect: Check that the state manager is running and accessible at the configured URI.

Getting Help

Production Considerations

For production deployment options, see our hosted platform or contact our team for enterprise solutions.