@bastani/atomic-storage-libsql
A libSQL / Turso storage adapter for Atomic. It stores sessions, workflow journals, and Intercom multi-node routing in one shared database, so several machines can use the same state. It is a separate package: install it only where you want remote storage.
Install
atomic install npm:@bastani/atomic-storage-libsql
Install in user scope (without -l); Atomic only searches user-scope packages for storage adapters.
Configure
Select the adapter in ~/.atomic/agent/settings.json:
{
"storage": {
"adapter": "@bastani/atomic-storage-libsql",
"options": { "url": "libsql://<db>.turso.io" },
"secrets": { "authToken": { "file": "turso-token" } }
}
}
turso db tokens create <db> > ~/.atomic/turso-token
chmod 600 ~/.atomic/turso-token
| Option | Required | Description |
|---|---|---|
url | yes | A libsql://, https://, wss://, or file: URL. |
authToken | for remote databases | The database token. Pass it through secrets ({ "file": ... } or { "env": ... }) so it stays out of settings. |
namespace | no | A self-hosted sqld namespace (sqld --enable-namespaces), sent as the x-namespace header. Needs a libsql:, https:, or http: URL. |
A file: database is opened in write-ahead-log mode with a 5000 ms busy timeout, the way Atomic's own SQLite stores are, so several processes can read and write one file at once: a statement waits up to 5 seconds for a lock another process holds instead of failing with SQLITE_BUSY, and the wait blocks the calling thread. The first open changes the file to WAL mode, which is kept in the file and adds -wal and -shm files beside it. Open a file only through this adapter at a time: another SQLite library with the same file open in WAL mode was seen to read stale data.
The token is redacted from error messages and diagnostics. Add a prefix to the storage block to keep projects or teams apart in one database. See Storage for selection precedence, per-process overrides, and the other storage options.
Use from the SDK
import { openLibsqlDatabase } from "@bastani/atomic-storage-libsql";
const database = await openLibsqlDatabase({ url: "libsql://<db>.turso.io", authToken });
openLibsqlDatabase also accepts namespace and headers (extra request headers, redacted from errors), both for libsql:, https:, or http: URLs. The returned SqliteDatabase can be passed as SDK sessionStore: { kind: "database", database } or workflow journal: { database }; it sends a workflow journal's batch of appends to the database in one request.
The package ships plain ESM JavaScript with TypeScript declarations. This import works in supported Node versions without a TypeScript loader.
License
MIT