Skip to content

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

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: 

    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: 

    # 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

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: 

    git clone https://github.com/exospherehost/exospherehost.git
cd exospherehost/state-manager

  2. Install dependencies: 

    uv sync

  3. Set up environment variables: 

    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: 

    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

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:
  2. State manager URL
  3. API key for authentication

  4. Namespace configuration

  5. Contact us for setup assistance:

  6. Email: nivedit@exosphere.host

  7. Configure your application: 

    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()

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: 

    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: 

    docker-compose -f docker-compose.prod.yml up -d

Kubernetes Deployment

  1. Create namespace: 

    kubectl create namespace exosphere

  2. Create ConfigMap for configuration: 

    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"

  3. Create Secret for sensitive data: 

    apiVersion: v1
kind: Secret
metadata:
  name: state-manager-secrets
  namespace: exosphere
type: Opaque
data:
  STATE_MANAGER_SECRET: <base64-encoded-state-manager-secret>
  SECRETS_ENCRYPTION_KEY: <base64-encoded-secrets-encryption-key>

  4. Deploy the state manager: 

    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:

curl http://localhost:8000/health

Response: 200 

{"message": "OK"}

Getting Help

Next Steps