Turso Databases

Synodes pairs every sandbox with a dedicated Turso database — a serverless SQLite-compatible (libSQL) database that runs at the edge. Your AI agents get an instantly available, fully provisioned database injected as environment variables — no manual setup, no connection string wrangling.

How It Works

When you create a sandbox, Synodes injects two environment variables:

TURSO_DATABASE_URL — the libSQL connection string (e.g., libsql://my-db-org.turso.io)
TURSO_AUTH_TOKEN — a scoped authentication token for that database

Your agent reads these from the environment and connects using the standard @libsql/client (TypeScript) or libsql_client (Python) library. No additional configuration needed.

Provisioning Modes

Auto-provisioning

Set env vars to the {{auto}} placeholder and Synodes creates a fresh database on sandbox creation:

# CLI
synodes create --language python \
  --env TURSO_DATABASE_URL="{{auto}}" \
  --env TURSO_AUTH_TOKEN="{{auto}}"

# Python SDK
sandbox = synodes.create(
    language="python",
    env_vars={
        "TURSO_DATABASE_URL": "{{auto}}",
        "TURSO_AUTH_TOKEN": "{{auto}}"
    }
)

Manual / Pre-provisioned

Pass your own Turso database credentials. This is useful when you have a shared database or want to preserve data across sandbox lifecycles:

synodes create --language python \
  --env TURSO_DATABASE_URL=libsql://my-org.turso.io \
  --env TURSO_AUTH_TOKEN=eyJ...

Database Lifecycle

The database lifecycle mirrors the sandbox lifecycle:

Created — when the sandbox is created (auto-provisioned mode)
Active — available for reads and writes while the sandbox runs
Retained — data persists when a sandbox stops (manual-provisioned mode)
Destroyed — auto-provisioned databases are torn down when the sandbox is deleted

Data retention: Auto-provisioned databases are ephemeral — they disappear when you delete the sandbox. For persistent data, use a manually provisioned database or snapshot the sandbox before deletion.

Key Features

Zero-Latency Local Replicas

Turso replicates your database to edge locations near your sandbox's region. Reads are served locally with sub-millisecond latency — ideal for agent memory lookups and state checks.

Branches & Restore

Create database branches for experimentation. Your agent can fork the database, try schema changes, and merge back or discard:

# Using the Turso CLI
turso db create agent-memory-dev --from agent-memory

SQLite Compatibility

Turso uses the libSQL protocol — fully compatible with SQLite, so any ORM or SQL library that works with SQLite works with Turso. Use Prisma, Drizzle, SQLAlchemy, or raw SQL.

Agent Memory Pattern

AI agents use Turso databases for:

Conversation history — store and retrieve past messages across sessions
Long-term memory — persist facts, preferences, and learned patterns
Tool results cache — cache API responses and expensive computations
Task state — track progress across multi-step workflows

See the Agent Memory with Turso section of the SDK quickstart for complete Python and TypeScript examples.

Limits & Pricing

Database storage is billed at $0.25 per GB-month (prorated). See the Pricing page for the full consumption model and cost examples.

Architecture Pricing