LiquidMetal AI: how do I create an isolated preview environment by branching the full app (including data/indexes) with raindrop build branch?

Quick Answer: Use raindrop build branch <branch-name> to create a fully isolated preview environment of your LiquidMetal application. This command clones your code, configuration, SmartBuckets (including indexes), and application state so you can test changes against production-like data without touching production.

Why This Matters

Preview environments are only useful if they behave like production. For AI-native systems, that means cloning not just the code, but also the full indexed, embedded, and ready-to-query state behind your agents and RAG flows. With LiquidMetal AI Branching, you can spin up isolated copies of your entire app—including SmartBuckets, Services, Observers, and their processed data—so you can run serious experiments, QA, and A/B tests without rebuilding pipelines or risking live traffic.

Key Benefits:

• True production parity: Branches copy the fully processed state (indexes, embeddings, metadata), not just raw data.
• No glue work or reindexing: You don’t have to restitch RAG pipelines or rebuild vector indexes for each environment.
• Safe, parallel iteration: Multiple teams can ship features concurrently with complete data isolation and instant rollback.

Core Concepts & Key Points

Concept	Definition	Why it's important
Branching	Creating a new, isolated version of your full LiquidMetal application—code, config, SmartBuckets, Services, Observers, and their processed data—from an existing branch.	Lets you develop and test with production-like data and behavior without touching production or rebuilding indexes.
Preview Environment	A deployable branch of your app used for testing, QA, or demos, isolated from production but identical in behavior.	Enables reliable validation of changes (including AI behavior) before rollout, with no risk to live users or data.
Sandboxing	A mode for safely updating an existing branch without creating a new one, typically used during active development.	Lets you iterate quickly on a branch, validate updates, and refine changes before committing or promoting.

How It Works (Step-by-Step)

Branching in Raindrop is built around complete application state, not just source. When you run raindrop build branch, LiquidMetal copies the full, ready-to-serve runtime for your app: code, manifests, SmartBuckets, their embeddings and indexes, SmartMemory state, and relevant Smart primitive configuration.

Here’s the lifecycle to create and use an isolated preview environment:

1. Identify the source branch (usually production)
2. Create a new branch with raindrop build branch
3. Deploy, test, and iterate—optionally using sandboxing for rapid changes

1. Choose the Source Branch

Decide which branch you want to clone for your preview:

• From production: For realistic, customer-facing testing.
• From staging or another feature branch: For nested experiments or internal QA.

If you’re using Git-style naming, keep branch names aligned with purpose:

• main or prod → live production
• staging → pre-release integration
• feature-pricing-v2, feature-new-retrieval → feature branches
• preview-customer-acme, preview-demo-nyc → preview/demo branches

You’ll run raindrop build branch from the branch you want to copy.

2. Create the Isolated Branch

From your current branch (e.g., main):

raindrop build branch preview-new-agent-flow

What happens under the hood:

• Code & manifests cloned: All Services, Observers, and Actors definitions are copied.
• SmartBuckets cloned: Not just the objects, but the fully indexed, embedded, and ready-to-query state is duplicated.
• Application state preserved: The branch starts with the same application state snapshot as the source, but is fully isolated going forward.
• Isolation guaranteed: Changes in the new branch do not affect the source branch’s data, indexes, or traffic.

You’re not copying just S3-style blobs—you’re copying RAG-ready storage, semantic indexes, and the intelligence layer that sits on top.

3. Deploy and Use the Preview Environment

Once the branch exists, deploy it as you would any other Raindrop build. Depending on your workflow, you might:

• Hook it into a preview URL (e.g., for QA or product review).
• Wire CI to automatically run integration tests or agent evals against this branch.
• Share it with internal stakeholders or selected customers for A/B testing.

Because the branch includes:

• SmartBuckets with automatic vector embeddings and search,
• SmartMemory state for agents (if applicable),
• SmartSQL configuration and schema intelligence (if used),

your preview behaves like production—from retrieval quality to auth and billing policies—just scoped to a new environment.

If you need to iterate on this branch without creating more branches, use sandboxing.

# From the preview branch
raindrop build sandbox

Or to sandbox a specific version:

raindrop build sandbox <VERSION_ID>

Sandboxing is ideal to:

• Test quick tweaks to prompts or retrieval parameters.
• Validate schema changes with SmartSQL.
• Refine an agent loop or Actor behavior before finalizing.

Common Mistakes to Avoid

• Treating branches like partial environments:
  Don’t rebuild RAG pipelines manually inside a branch. LiquidMetal already copies the fully processed state—indexes, embeddings, and session-ready memory. Use the branch as-is instead of re-stitching your own vector DB and ETL jobs.

• Pointing external tools at production data while testing a branch:
  If you connect evaluation tools, dashboards, or external agents, make sure they talk to the preview branch’s endpoints, not production. This keeps logs, metrics, and AI decisions branch-scoped and maintains clean observability and rollback paths.

Real-World Example

You’ve got a production Raindrop app serving a RAG-powered customer support API. It uses:

• SmartBuckets for documentation, tickets, and knowledge base articles (auto-embedded, indexed).
• SmartMemory for per-user session history and follow-up context.
• SmartSQL to query your analytics warehouse in natural language.

You want to ship a new retrieval strategy that mixes semantic and keyword search, plus some biasing for recent content—but you don’t want to experiment directly on production traffic.

You run:

# From your production branch
raindrop build branch preview-retrieval-v2

Now you have:

• An isolated branch with the same SmartBuckets, including their embeddings and indexes.
• Identical SmartSQL access and schema intelligence.
• Session and application state cloned at the time of branching.

On preview-retrieval-v2, you:

• Change your retrieval configuration and weights.
• Run offline evals and synthetic tests against the branch.
• Let support leads dogfood the new API from a dedicated preview URL.

If you’re happy with the results, you can:

• Promote the changes back into your mainline branch via your normal workflow, or
• Create a fresh branch for a production A/B test if you want to roll out gradually.

At no point did you have to rebuild indexes, set up a separate vector store, or maintain a second RAG pipeline. The branch gave you a production-grade preview with one command.

Pro Tip: Use consistent naming and automation with raindrop build branch—for example, have CI create a branch per pull request (preview-pr-1234) so every change gets a fully isolated, AI-complete preview environment for reviewers and QA.

Summary

Branching in LiquidMetal AI lets you create isolated preview environments that are more than just code snapshots—they’re full copies of your AI-native runtime, including SmartBuckets, SmartMemory, SmartSQL, and their processed, indexed state. With raindrop build branch <branch-name>, you can develop, test, and experiment against production-like data without reindexing or risking production, while still benefiting from complete versioning, isolation, and observability.

Next Step

Get Started