> Turso: what your AI agent should know — from The Handover, the-handover.org/services/turso
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Turso

What we tell an AI agent working on a project that uses Turso: 2 rules, 0 learned the hard way.

Build a full rootnote set for a Turso project: https://the-handover.org/build?areas=working-agreement,database&database=turso

The vendor's own file for agents (what Turso is, where its documentation lives): https://docs.turso.tech/llms.txt. This page covers where it catches agents out.

### Turso: the CLI's login token has full organisation access, and before 1.0.26 any local user could read it

> Reported by Turso, "turso-cli persists Turso platform JWT with world-readable (0o644) file permissions (CVE-2026-48790)" — github.com/tursodatabase/turso-cli/security/advisories/GHSA-57f6-pvx8-hwj6 · distilled by Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-25

Turso's advisory: `turso auth login` saved the platform token in plain text to
`settings.json` — `~/Library/Application Support/turso/` on macOS,
`~/.config/turso/` on Linux — readable by every user on the machine. That token
is not scoped to a database. It can create and destroy databases, rotate
credentials, read data and change billing for every organisation the user belongs
to. The advisory lists who else could read it: jobs running as other users,
sandboxed CI runners with the home directory mounted, and containers with a
bind-mounted home. Fixed in 1.0.26.

- **Update the Turso CLI to 1.0.26 or later, and check the existing
  `settings.json` is readable only by you** (`600`). The advisory notes that the
  library's permission setting applies only when a file is created, so an
  existing file is not tightened by that alone.
- **Do not log the CLI in where an agent's sandbox or a CI runner mounts your home
  directory.** Give the agent a token scoped to the one database it needs.

### Turso: scope tokens to one database, and sync before trusting a replica

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **Scope auth tokens to a single database**, and keep them out of the
  repository.
- **Writes from other processes reach an embedded replica only after it syncs.**
  Sync, or read from the primary, wherever freshness matters.

Also applies to every database choice, so not repeated here: An instruction is not a control: keep production out of the agent's reach, and check recovery yourself; Never run a migration or a write against production that has not run against a copy.