Sim IDX manages your deployment environments and data ingestion through an automated build and ingestion lifecycle. Every Sim IDX app operates across isolated environments based on your Git branching strategy, with each deployment following a predictable lifecycle that governs when your code is compiled, when data is indexed, and what changes trigger historical backfill.

​
Deployment Lifecycle

Every deployment progresses through three statuses: Building → Ingesting → Ready. This lifecycle governs when your code is compiled, when data is indexed, and what changes re-trigger historical backfill.

​
Building

After you push a commit, Sim IDX builds your app (equivalent to running sim build). If there is a problem, the build fails with clear logs to help you resolve it. Fix the issue locally, commit, and push again to start a new build.

​
Ingesting

When the build succeeds, the deployment begins ingesting. Two things happen in parallel:
  • Real‑time indexing from the chain tip begins immediately.
  • Historical backfill starts for the data defined by your Listener Contract. The status percentage reflects the backfill progress until it reaches 100%.
Your APIs and database are usable as soon as the deployment enters Ingesting. Response completeness improves as the backfill advances.
Backfill is re-triggered only when you change your Listener Contract (including generated bindings that alter what the listener indexes). API-only or other non-listener code changes will create a new deployment but will not re-run historical backfill. The new deployment continues from the latest indexed state. To force a new backfill, modify your listener, commit, and push.

​
Ready

Backfill has completed (100%). Your app continues to index new onchain activity in real time.

​
Incremental Deployments

Sim IDX optimizes your development workflow through incremental deployments, which avoid unnecessary reprocessing when you make changes that don’t affect data ingestion. First Deployment per Branch: When you make the first commit to any branch (including main), Sim IDX triggers a complete build and ingestion process. Your code is compiled, a new database is provisioned, historical backfill begins from scratch, and new API endpoints are created. Subsequent Deployments: For additional commits to the same branch, the deployment behavior depends on what you’ve changed. Non-Listener Changes result in incremental deployments. This includes changes to your sim.toml configuration, updates to API route logic, and modifications to non-listener application code. These changes result in incremental deployments where your code is rebuilt and redeployed, the same database instance is reused, API base URLs remain unchanged, no historical backfill occurs, and real-time indexing continues uninterrupted. Listener Changes trigger a complete redeployment. Any modification to your listener contract requires a full build and ingestion cycle because they alter what data is indexed and how it’s processed. This includes adding or modifying ABIs, changes to generated code that affect indexing logic, adding new listener files, creating new triggers in your main listener file, and any code changes within existing listener functions.

​
Deployment Environments

Sim IDX operates with two types of environments based on your Git branching strategy:

​
Production Environment

When you push commits to the main branch, Sim IDX creates production deployments. Each production deployment receives:
  • A dedicated PostgreSQL database
  • A unique base URL for your APIs
  • Full build and ingestion lifecycle processing
If you’re using database URLs or API endpoints during development, make sure you update them after every production push.

The Current Deployment section of your App Page represents your latest production deployment.

​
Preview Environments

When you push commits to any branch other than main, Sim IDX automatically creates isolated preview environments. Each preview deployment gets:
  • Its own isolated database
  • A unique API URL separate from production
  • Independent build and ingestion lifecycle

The Other Deployments section of your App Page is where you can find preview deployments.

​
PR Flow

For a more structured development process, you can use PRs on GitHub to trigger preview deployments. This allows for code review and collaborative testing before merging changes into the main branch. To start, create a new branch in your local repo and push it to GitHub. Then, open a pull request from your new branch to the main branch.

Open a new pull request on GitHub

Once the pull request is created, Sim IDX automatically builds a new preview deployment. You can find this build in the “Other Deployments” section of your App Page in the Sim dashboard. The deployment is linked to the pull request, allowing you and your team to easily access the PR on GitHub to review changes and test the isolated deployment.

The PR link in the deployment details.

After the pull request is approved and merged, a new production deployment will be created from the main branch.