Skip to content
Rival Docs

Storage

Rival tools are stateless by design. Understanding where data lives - and what doesn’t survive past a single run - will save you from surprises when building.

Three options, in order of permanence

There are three places state can live when you’re building on Rival:

  1. Ephemeral within a run - in-memory variables and local files. Wiped when the run ends.
  2. Persistent via Digital Assets - files uploaded ahead of time, readable by every run.
  3. External services - databases, blob storage, queues, anything reachable over the network.

Pick based on how long the data needs to live.

1. Ephemeral within a run

While your handler is running, you have a normal-looking local environment - variables, in-memory data structures, and an ephemeral local filesystem. Use them freely for scratch work and intermediate computation.

What doesn’t carry over:

  • Module-level state - globals, class-level caches, module-scoped variables - all reset on the next run.
  • Local files - anything written to disk is gone when the run ends.
  • In-memory data - cleared with the run.

Don’t try to use these for cross-run state. Even if two consecutive runs land in the same physical environment, the platform doesn’t guarantee they’ll see each other’s data.

2. Persistent files: Digital Assets

If your tool needs to read a file that should persist between runs - a dataset, a model weight, a topic taxonomy, a configuration JSON - the answer is Digital Assets.

Digital Assets is Rival’s standalone file library. You upload a file once, get a stable path, and read that path from your handler on every run.

  • Files and folders up to 500 MB each
  • Most common file types are supported (videos aren’t allowed)
  • Public (anyone can read with the path) or Private (only your organization)
  • Stored at /digital-assets, organized into File Upload, Folder Upload, and S3 Bucket listing

See Digital Assets for the full walkthrough.

3. External services for stateful needs

Digital Assets is great for files. It is not a database.

If your tool needs to store and query data that changes over time - user records, counters, session state, generated content - you need to connect to an external service over the network. Rival does not provide a built-in database.

Common choices:

  • Postgres (Supabase, Neon, PlanetScale, RDS)
  • Redis (Upstash, ElastiCache) for caching and counters
  • MongoDB (Atlas) for document storage
  • S3 or other object storage for large blobs
  • Any HTTP-accessible API you’d already be using

Store your connection credentials as environment variables in Settings → Secrets, assign them to the tool, and read them in your handler at runtime. This keeps secrets out of your code and lets you rotate them without redeploying.

Quick reference

NeedSolution
Temporary scratch space during a single runUse in-memory variables or local files (ephemeral)
Read a file consistently across runsUpload to Digital Assets
Store structured data that changes over timeConnect to an external database
Share state across concurrent runsUse an external store - no shared memory exists in the run environment
Large blobs (images, audio, archives)Digital Assets or external object storage