Project Redis

Project Redis is a private Redis instance for your project. Use it to share ephemeral state — game worlds, lobbies, counters, session metadata — across every concurrent voice session and session worker on the same project. It is available on Advanced and Ultimate plans. Free, Budget, and Budget+ projects do not receive Project Redis.

Enable Project Redis

Dashboard: Project overview → Runner settings → Project Redis toggle (redis_enabled / runner.redis_enabled). On Advanced and Ultimate, the toggle defaults to on when your plan grants the feature.
CLI: voicethere projects settings set redis_enabled true or false — list keys with voicethere projects settings list.
API: PATCH /projects/:projectId/runner-settings with { "key": "redis_enabled", "value": true }— see Control plane API.

Settings are saved on the project immediately but apply to live agents only after you Deploy to cloud (or promote an active build). The platform provisions or tears down the Redis instance during deploy based on this toggle.

Runtime: AGENT_REDIS_URL

When Project Redis is enabled and deployed, the platform injects AGENT_REDIS_URL into your sandboxed agent child process. Connect in onAgentStart with ioredis (or another Redis client that accepts a URL):

import Redis from "ioredis";
import { defineAgent } from "@voicethere/agent";

export default defineAgent({
  async onAgentStart({ env }) {
    const redisUrl = env.AGENT_REDIS_URL ?? process.env.AGENT_REDIS_URL;
    if (!redisUrl) {
      return;
    }
    const redis = new Redis(redisUrl);
    // shared state for all sessions on this session worker
  },
});

Each session worker gets the same project Redis endpoint so agents on different workers can read and write shared keys. For per-session isolation, prefix keys with SESSION_ID or your own namespace.

Bundle ioredis

Add ioredis as a dependency in your agent project and build with @voicethere/cli /@voicethere/agent so it is bundled into the uploaded agent.js. Plain environment variables and secrets follow the same pattern as other AGENT_* keys — see Agent environment & secrets.

redis-sync template

The public @voicethere/agent repo ships a working example template id redis-sync — world-buffer sync via Redis and onAgentStart:

github.com/voicethere/agent/tree/main/templates/redis-sync
Entry: templates/redis-sync/agent.ts
Layout helpers: templates/redis-sync/world-layout.ts

Local build from the template header:

npx @voicethere/agent build --entry templates/redis-sync/agent.ts --outfile dist/agent.js

Durability and scope

Project Redis is for ephemeral shared session state — fast coordination across concurrent agents on the same project. It is not a durability SLA and is not a substitute for your own database or object store. Plan for eviction, deploy-time reprovisioning, and occasional connectivity blips in agent code (retry, idempotent writes, or graceful degradation when AGENT_REDIS_URL is unset).

If an agent child crashes, in-process Redis handles are lost — use Agent crash policy settings to understand restart vs disconnect behavior for live sessions.

CLI examples