Skip to main content

Hosted Service Complete Documentation

This document contains all Envio Hosted Service documentation consolidated into a single file for LLM consumption.

Envio Hosted Service Overview​

File: hosted-service.md

Envio offers a fully managed hosting solution for your indexers, providing all the infrastructure, scaling, and monitoring needed to run production-grade indexers without operational overhead.

Our hosted service offers multiple tiers to suit different needs, from free development environments to enterprise-grade dedicated hosting. Each tier includes powerful features like static production endpoints, built-in alerts, and production-ready infrastructure.

Deployment Options​

Envio provides flexibility in how you deploy and host your indexers:

  • Fully Managed Hosted Service: Let Envio handle everything. The following sections of this page outline the Fully Managed Hosted Service in more detail. This is the recommend deployment method for most users and removes the hosting overhead for your team. See below for the all the awesome features we provide and see the Pricing & Billing page for more information on which Hosting tier suits your indexing needs.

  • Self-Hosting: Run your indexer on your own infrastructure. This requires advanced setup and infrastructure knowledged not unique to Envio. See the repository at https://github.com/enviodev/local-docker-example for a simple docker example to get you started. Please note this example does not cover all infrastructure related needs. It is recommended that at least a separate Postgres management tool is used for self hosting in production.

Hosted Service Key Features​

  • Git-based Deployments: Similar to Vercel, deploy your indexer by simply pushing to a designated deployment branch
  • Zero Infrastructure Management: We handle all the servers, databases, and scaling for you
  • Static Production Endpoints: Consistent URLs with zero-downtime deployments and instant version switching
  • Built-in Monitoring: Track logs, sync status, and deployment health in real-time
  • Comprehensive Alerting: Multi-channel notifications (Discord, Slack, Telegram, Email) for critical issues, performance warnings, and deployment updates
  • Security Features: IP/Domain whitelisting to control access to your indexer endpoints
  • GraphQL API: Access your indexed data through a performant, production-ready GraphQL endpoint
  • Multi-chain Support: Deploy indexers that track multiple networks from a single codebase

Hosted Service Deployment Model​

The Envio Hosted Service provides a seamless GitHub-integrated deployment workflow:

  1. GitHub Integration: Install the Envio Deployments GitHub App to connect your repositories
  2. Flexible Configuration: Support for monorepos with configurable root directories, config file locations, and deployment branches
  3. Automatic Deployments: Push to your deployment branch to trigger builds and deployments
  4. Version Management: Maintain multiple deployment versions with one-click switching and rollback capabilities
  5. Real-time Monitoring: Track deployment progress, logs, and sync status through the dashboard

Multiple Indexers: Deploy several indexers from a single repository using different configurations, branches, or directories.

You can view and manage your hosted indexers in the Envio Explorer at https://envio.dev/explorer.

Important Notes​

It is recommended that before deploying to the Hosted Service, the indexer is built and tested locally to ensure it runs smoothly on the Hosted Service.

Hosted Service Features​

File: hosted-service-features.md

Our hosted service includes several production-ready features to help you manage and secure your indexer deployments.

Plan Availability Notice​

Most features listed in this section are available for paid production plans only. The free development tier has limited features and is designed for testing and development purposes.

Development Tier Disclaimer​

The free development tier is intended for testing and development purposes only and should not be used as a production environment. Envio makes no guarantees regarding uptime, availability, or data persistence for deployments on the development tier. If you choose to use a development tier deployment in a production capacity, you do so entirely at your own risk. Envio assumes no liability or accountability for any downtime, data loss, or service interruptions that may occur on development tier deployments.

IP/Domain Whitelisting​

Status: Coming Soon - Full support for whitelisting is in active development

Control access to your indexer by restricting requests to specific IP addresses or domains. This security feature helps protect your data and ensures only authorized clients can query your indexer.

Benefits:

  • Enhanced security for sensitive data
  • Prevent unauthorized access
  • Control API usage from specific sources
  • Ideal for production environments with strict access requirements

Technical Implementation:

  • IP Whitelisting: Full IP address validation and blocking
  • Domain Whitelisting: Best-effort domain validation using SNI (Server Name Indication) checking
  • Domain filtering does not involve mutual TLS (mTLS) or client certificate validation

Note: Domain whitelisting relies on SNI checking and may not provide the same level of security as IP whitelisting. For maximum security, consider using IP whitelisting when possible.

Built-in Alerts​

Stay informed about your indexer's health and performance with our integrated alerting system. Configure multiple notification channels and choose which alerts you want to receive.

Version Requirement: This feature is only available for indexers deployed with version 2.24.0 or higher.

Notification Channels​

Configure one or multiple notification channels to receive alerts:

  • Discord
  • Slack
  • Telegram
  • Email

Alert Types​

Critical Alerts:

  • Production Endpoint Down - Triggered when your production endpoint stops responding to GraphQL requests

Warning Alerts:

  • Indexer Stopped Processing - Triggered when the indexer is not processing blocks for more than 10 minutes

Info Alerts:

  • Indexer Error Logs - Triggered when indexer generates error logs indicating potential issues

Notification Types​

Deployment Notifications:

  • Historical Sync Complete - Get notified when any deployment has completed its historical sync

Note: More alert types and notification types will be added in future updates. You can request specific alert types in the Envio Discord community.

Zero-Downtime Deployments​

Update your indexer without any service interruption using our seamless deployment system with static production endpoints.

How it works:

  • Deploy new versions alongside your current deployment
  • Each indexer gets a static production endpoint that remains consistent
  • Use 'Promote to Production' to instantly route the static endpoint to any deployment
  • All requests to your static production endpoint are automatically routed to the promoted deployment
  • Maintain API availability throughout upgrades with no endpoint changes required

Key Features:

  • Static Production Endpoint: Consistent URL that never changes, regardless of which deployment is active
  • Instant Switching: Promote any deployment to production with zero downtime
  • Rollback Capabilities: Quickly switch back to previous deployments if needed
  • Seamless Updates: Your applications continue working without any configuration changes

Deployment Location Choice​

Status: Coming Soon - Full support for cross region deployments is in active development. If you require a deployment to be based in the USA please contact us through our support channel on discord.

Available on: Dedicated plans only

Choose your primary deployment region to optimize performance and meet compliance requirements.

Available Regions:

  • USA
  • EU

Benefits:

  • Reduced latency for your target users
  • Data residency compliance support
  • Custom infrastructure configurations
  • Dedicated infrastructure resources

Direct Database Access​

Available on: Dedicated plans only

Access your indexed data directly through SQL queries, providing flexibility beyond the standard GraphQL endpoint.

Use Cases:

  • Complex analytical queries
  • Custom data exports
  • Advanced reporting and dashboards
  • Integration with external analytics tools

Powerful Analytics Solution​

Available on: Dedicated plans only (additional cost)

A comprehensive analytics platform that automatically pipes your indexed data from PostgreSQL into ClickHouse (approximately 2 minutes behind real-time) and provides access through a hosted Metabase instance.

Technical Architecture:

  • Data Pipeline: Automatic replication from PostgreSQL to ClickHouse
  • Near Real-time: Data available in analytics platform within ~2 minutes
  • Frontend: Hosted Metabase instance for visualization and analysis
  • Performance: ClickHouse optimized for analytical queries on large datasets

Capabilities:

  • Interactive, customizable dashboards through Metabase
  • Variety of visualization options (charts, graphs, tables, maps)
  • Fast analytical queries on large datasets via ClickHouse
  • Ad-hoc SQL queries for data exploration
  • Automated alerts based on data thresholds
  • Team collaboration and report sharing
  • Export capabilities for further analysis

Pricing & Billing​

File: hosted-service-billing.mdx

Envio offers flexible pricing options to meet the needs of projects at different stages of development.

Pricing Tiers​

Our hosted service offers flexible pricing tiers to match your project's needs, from free development environments to enterprise-grade dedicated hosting.

For the most up-to-date pricing information, detailed plan comparisons, and feature breakdowns, please visit the official Envio Pricing Page at https://envio.dev/pricing.

Available Tiers:

  • Development - Free tier perfect for testing and development
  • Production Small - Paid tier to get started with production deployments
  • Production Medium - Paid tier for scaling your indexing operations
  • Production Large - Paid tier for high-volume production workloads
  • Dedicated - Custom pricing for ultimate performance and control

Development Tier Warning​

The free development tier is intended for testing and development purposes only and should not be used as a production environment. Envio makes no guarantees regarding uptime, availability, or data persistence for deployments on the development tier. If you choose to use a development tier deployment in a production capacity, you do so entirely at your own risk. Envio assumes no liability or accountability for any downtime, data loss, or service interruptions that may occur on development tier deployments.

Feature Availability by Tier​

FeatureDevelopmentProduction SmallProduction MediumProduction LargeDedicated
Pricing & Limits
Monthly costFree$70$300$800Custom
Included indexing hours750800800800Unlimited
Additional hours cost-$0.1/hour$0.2/hour$0.5/hourCustom
Multichain networks∞51015∞
Query rate limit100/min250/min1,000/min2,000/min5,000/min
Approx storage capacity0.1M events1M events10M events100M eventsUnlimited
Number of contracts1001,00010,00050,000Unlimited
Deployment Features
Deployments per indexer35555
Static production endpoint❌✅✅✅✅
Security & Management
IP/Domain whitelisting❌✅✅✅✅
Built-in alerts❌✅✅✅✅
Infrastructure
Backups❌✅✅✅✅
Deployment location choice❌❌❌❌✅
Direct database access❌❌❌❌✅
Support
Discord community✅✅✅✅✅
Priority Discord support❌✅✅✅✅
Premium Telegram support❌❌❌❌✅
Custom SLA❌❌❌❌✅
Add-on Services
Analytics solution❌❌❌❌💰

Legend: ✅ Included | ❌ Not available | 💰 Additional cost

Self-Hosting Option​

For users who prefer to manage their own infrastructure, Envio supports self-hosting your indexer as well. For your convenience, there is a Docker file in the root of the generated folder.

Deploying Your Indexer​

File: hosted-service-deployment.md

The Envio Hosted Service provides a seamless git-based deployment workflow, similar to modern platforms like Vercel. This enables you to easily deploy, update, and manage your indexers through your normal development workflow.

Prerequisites & Important Information​

Requirements​

  • Version Support: Deployment on the Hosted Service requires at least version 2.6.0. Additionally the following versions are not supported:
    • 2.29.x
  • PNPM Support: deployment must be compatible with pnpm version 9.10.0
  • Package.json: the package.json file must be present and include the above two requirements.
  • Configuration file: a HyperIndex configuration file must be present (the name can be set in the indexer settings)
  • Github Repository: The repository must be no larger than 100MB

Before deploying your indexer, please be aware of the following limits and policies:

Deployment Limits​

  • 3 development tier indexers per organization
  • Deployments per indexer: 3 deployments per indexer
  • Deployments can be deleted in the hosted service to make space for more deployments

Development Tier Fair Usage Policy​

The free development tier includes automatic deletion policies to ensure fair resource allocation:

Automatic Deletion Rules:

  • Hard Limits:
    • Deployments that exceed 20GB of storage will be automatically deleted
    • Deployments older than 30 days will be automatically deleted
  • Soft Limits (whichever comes first):
    • 100,000 events processed
    • 5GB storage used
    • no requests for 7 days

When soft limits are breached, the two-stage deletion process begins

Two-Stage Deletion Process:

Applies to development deployments that breach the soft limits

  1. Grace Period (7 days) - Your indexer continues to function normally, you receive notification about the upcoming deletion
  2. Read-Only Access (3 days) - Indexer stops processing new data, existing data remains accessible for queries
  3. Full Deletion - Indexer and all data are permanently deleted

Note: The grace period durations (7 + 3 days) are subject to change. Always monitor your deployment status and upgrade when approaching limits.

Step-by-Step Deployment Instructions​

Initial Setup​

  1. Log in with GitHub: Visit https://envio.dev/app/login and authenticate with your GitHub account
  2. Select an Organization: Choose your personal account or any organization you have access to
  3. Install the Envio Deployments GitHub App: Grant access to the repositories you want to deploy

Configure Your Indexer​

  1. Add a New Indexer: Click "Add Indexer" in the dashboard
  2. Connect to Repository: Select the repository containing your indexer code
  3. Configure Deployment Settings:
    • Specify the config file location
    • Set the root directory (important for monorepos)
    • Choose the deployment branch

Note: You can deploy multiple indexers from a single repository by configuring them with different config file paths, root directories, and/or deployment branches.

Monorepo Warning: If you're working in a monorepo, ensure all your imports are contained within your indexer directory to avoid deployment issues.

Deploy Your Code​

  1. Create a Deployment Branch: Set up the branch you specified during configuration
  2. Deploy via Git: Push your code to the deployment branch
  3. Monitor Deployment: Track the progress of your deployment in the Envio dashboard

Manage Your Deployment​

  1. Version Management: Once deployed, you can:
    • View detailed logs
    • Switch between different deployed versions
    • Rollback to previous versions if needed

Continuous Deployment Best Practices​

For a robust deployment workflow, we recommend:

  1. Protected Branches: Set up branch protection rules for your deployment branch
  2. Pull Request Workflow: Instead of pushing directly to the deployment branch, use pull requests from feature branches
  3. CI Integration: Add tests to your CI pipeline to validate indexer functionality before merging to the deployment branch

Continuous Configuration​

After deploying your indexer, you can manage its configuration through several tabs in the Envio dashboard:

General Tab​

The General tab provides core configuration options:

  • Config File Path: Update the location of your indexer's configuration file
  • Deployment Branch: Change which Git branch triggers deployments
  • Root Directory: Modify the root directory for your indexer (useful for monorepos)
  • Delete Indexer: Permanently remove the indexer and all its deployments

Warning: Deleting an indexer is permanent and will remove all associated deployments and data. This action cannot be undone.

Environment Variables Tab​

Configure environment-specific variables for your indexer:

  • Add custom environment variables with the ENVIO_ prefix
  • Environment variables are securely stored and injected into your indexer at runtime
  • Useful for API keys, configuration values, and other deployment-specific settings

Best Practice: Use environment variables for sensitive data rather than hardcoding values in your repository. Remember to prefix all variables with ENVIO_.

Plans & Billing Tab​

Manage your indexer's pricing tier and billing:

  • Select from available pricing plans
  • Upgrade your plan to suit your needs
  • View current plan features and limits

Alerts Tab​

Configure monitoring and notification preferences:

  • Set up notification channels (Discord, Slack, Telegram, Email)
  • Choose which alert types to receive (Production Endpoint Down, Indexer Stopped Processing, etc.)
  • Configure deployment notifications (Historical Sync Complete)

Note: Alert configuration is available for indexers deployed with version 2.24.0 or higher on paid production plans.

Monitoring Your Indexer​

File: hosted-service-monitoring.md

Once your indexer is deployed, the Envio Hosted Service provides several tools to help you monitor its health, performance, and progress.

Dashboard Overview​

The main dashboard provides real-time visibility into your indexer's status:

Key Metrics Displayed:

  • Active Deployments: Track how many deployments are currently running (e.g., 1/3 active)
  • Deployment Status: See whether your indexer is actively syncing, stopped, or has encountered errors
  • Recent Commits: View your deployment history with commit information and active status
  • Usage Statistics: Monitor your indexing hours, storage usage, and query rate limits
  • Network Progress: Real-time progress bars showing sync status for each blockchain network
  • Events Processed: Track the total number of events your indexer has processed
  • Historical Sync Time: See how long it took to complete the initial sync

Deployment Status Indicators​

Each deployment shows clear status information:

  • Syncing: Indexer is actively processing blocks and events
  • Syncing Stopped: Indexer has stopped processing (may indicate an error or a breach of tier limits)
  • Historical Sync Complete: Initial sync finished, indexer is processing new blocks in real-time

Error Detection and Troubleshooting​

When issues occur, the dashboard displays failure information to help you quickly diagnose problems.

Failure Information Includes:

  • Error Type: Clear indication of the failure (e.g., "Indexing Has Stopped")
  • Error Description: Details about what went wrong (e.g., "Error during event handling")
  • Next Steps: Guidance on where to find more information (error logs)
  • Support Access: Direct link to Discord for assistance

Logging​

Full logging support is integrated and configured by Envio via the Hosted Service.

Access detailed logs to troubleshoot issues and monitor indexer behavior:

  • Real-time Logs: View live logs as your indexer processes events
  • Error Logs: Quickly identify and diagnose errors in your event handlers
  • Deployment Logs: Track the deployment process and startup sequence
  • Filter Log Levels: Find specific log entries to debug issues

Access logs through the "Logs" button on your deployment page.

Built-in Alerts​

Configure proactive monitoring through the Alerts tab to receive notifications before issues impact your users:

  • Critical Alerts: Get notified when your production endpoint goes down
  • Warning Alerts: Receive alerts when your indexer stops processing blocks
  • Info Alerts: Stay informed about indexer restarts and error logs
  • Deployment Notifications: Know when historical sync completes

Note: Set up multiple notification channels (Paid Tiers Only) to ensure you never miss critical alerts about your indexer's health.

Self-Hosting Your Envio Indexer​

File: self-hosting.md

While Envio offers a fully managed Hosted Service, you may prefer to run your indexer on your own infrastructure. This guide covers everything you need to know about self-hosting Envio indexers.

Note: This documentation page is actively being improved. Check back regularly for updates and additional information.

Appreciation Note: We deeply appreciate users who choose our hosted service, as it directly supports our team and helps us continue developing and improving Envio's technology. If your use case allows for it, please consider the hosted option.

Why Self-Host?​

Self-hosting gives you:

  • Complete Control: Manage your own infrastructure and configurations
  • Data Sovereignty: Keep all indexed data within your own systems

Disclaimer: Self Hosting can be done on with a variety of different infrastructures, tools and methods. The outline below is merely a starting point and does not offer a full production level solution. In some cases advanced knowledge of infrastructure, database management and networking may be required for a full production level solution.

Prerequisites​

Before self-hosting, ensure you have:

  • Docker installed on your host machine
  • Sufficient storage for blockchain data and the indexer database
  • Adequate CPU and memory resources (requirements vary based on chains and indexing complexity)
  • Required HyperSync and/or RPC endpoints
  • Envio API token for HyperSync access (ENVIO_API_TOKEN) — required for continued access

Getting Started​

In general, if you want to self-host, you will likely use a Docker setup. For a working example, check out the local-docker-example repository at https://github.com/enviodev/local-docker-example. It contains a minimal Dockerfile and docker-compose.yaml that configure the Envio indexer together with PostgreSQL and Hasura.

Configuration Explained​

The compose file in that repository sets up three main services:

  1. PostgreSQL Database (envio-postgres): Stores your indexed data
  2. Hasura GraphQL Engine (graphql-engine): Provides the GraphQL API for querying your data
  3. Envio Indexer (envio-indexer): The core indexing service that processes blockchain data

Environment Variables​

The configuration uses environment variables with sensible defaults. For production, you should customize:

  • Envio API token (ENVIO_API_TOKEN)
  • Database credentials (ENVIO_PG_PASSWORD, ENVIO_PG_USER, etc.)
  • Hasura admin secret (HASURA_GRAPHQL_ADMIN_SECRET)
  • Resource limits based on your workload requirements

Getting Help​

If you encounter issues with self-hosting:

Recommendation: For most production use cases, we recommend using the Envio Hosted Service to benefit from automatic scaling, monitoring, and maintenance.

Summary​

The Envio Hosted Service provides a comprehensive, production-ready platform for deploying and managing blockchain indexers with:

  • Multiple pricing tiers from free development to enterprise dedicated hosting
  • Zero-downtime deployments with static production endpoints
  • Comprehensive monitoring through dashboards, logs, and multi-channel alerts
  • Git-based workflow similar to modern deployment platforms like Vercel
  • Advanced features including IP/domain whitelisting, direct database access, and analytics solutions (on paid tiers)
  • Self-hosting options for users requiring complete infrastructure control

For most users, the hosted service is the recommended approach, offering professional infrastructure management without operational overhead. Self-hosting is available for users with specific requirements around data sovereignty or infrastructure control.

For the latest pricing and features, visit https://envio.dev/pricing.