Connect an agent · Gauntlet docs

#The prompt

Use the Copy agent prompt button on the home page, or copy it from the top of this page. It tells the agent:

what Gauntlet is (SQLite-family SQL, PostgreSQL wire as a transport only);
how to connect over PostgreSQL wire or HTTP;
which errors it must handle, and that 40003 is never retried blindly;
what it must not do: use an admin token, create or drop databases, or touch other databases.

The prompt points at this documentation's Markdown, so the agent reads the current contract instead of guessing from PostgreSQL habits.

#Environment variables

The prompt uses three names. They are a convention for your project, not a setting read by a Gauntlet SDK:

Variable	Holds
`GAUNTLET_DATABASE_URL`	A PostgreSQL connection string without the password, for example `postgres://app@n1.example.net:7151/app?sslmode=verify-full`
`GAUNTLET_HTTP_URL`	The HTTP base URL of a node, for example `https://n1.example.net:7101`
`GAUNTLET_DATABASE_TOKEN`	The database token

If your project already has its own names, keep them and tell the agent.

#Which credential to hand over

Credential	Give it to an agent?
Database token	Yes. It opens exactly one database. Anyone with it can do everything in that database
Client token	No. Every database's token is derived from it
Admin token	No. It opens `/admin`, `/status` and `/metrics` for the deployment
Bucket credentials	No. The bucket is the database

There are no read-only or short-lived tokens yet. A read-only token and platform-issued short-lived tokens are on the roadmap.

#One database per agent

The unit of isolation is the database. Clients of different databases are mutually untrusted, and a token is bound to one immutable database ID. Giving each agent its own database keeps one agent's mistakes out of another's state, and an agent that is idle costs only its stored bytes (scale to zero).

Creating databases needs the admin token today, so an agent should not do it. Run gauntlet admin create-database from your own backend. Scoped creation inside a project is planned.

#Coming

MCP server and skills. Not shipped. Do not configure an MCP URL for Gauntlet until one is published here.
SDK helpers that hide 40001 retries and 40003 lookups.
Idempotency keys, so an agent's retried tool call commits at most once.

The full prompt text

This is exactly what the Copy agent prompt buttons copy.

Prompt

Connect this project to my existing Gauntlet database.

Context:
- Documentation index for agents: https://gauntlet-db.stavros.xyz/llms.txt
- Quickstart: https://gauntlet-db.stavros.xyz/docs/quickstart.md
- SQL compatibility and error codes: https://gauntlet-db.stavros.xyz/docs/sql/compatibility.md
- Database: the one already configured for this project
- Protocol: PostgreSQL wire or the native HTTP JSON API, whichever this project already uses
- Connection values are in environment variables: GAUNTLET_DATABASE_URL (PostgreSQL wire),
  GAUNTLET_HTTP_URL (HTTP base URL) and GAUNTLET_DATABASE_TOKEN (the database token).
  These names are a convention, not a shipped SDK setting. Keep this project's own names if it has them.

Before editing, read the Gauntlet documentation above and inspect how this project
already talks to its database. Gauntlet is pre-beta software; where the documentation
and my deployment disagree, tell me instead of guessing.

What Gauntlet is:
- A distributed SQL database. SQL is the SQLite family, run by the Turso engine.
- The PostgreSQL wire protocol is a transport only. There is no PostgreSQL SQL dialect,
  no pg_catalog or information_schema, no extensions, and no ORM is certified yet.
- libSQL client compatibility is not available yet. Do not assume it.

Connecting:
- PostgreSQL wire: dbname is the database name, the user name is ignored, and the
  password is the database token. Authentication is SCRAM-SHA-256. Keep TLS
  verification on (sslmode=verify-full with the deployment's CA certificate).
- HTTP: POST <GAUNTLET_HTTP_URL>/db/<name>/sql with a JSON body
  {"sql": "...", "params": [...]} and the header "Authorization: Bearer <token>".
  POST /db/<name>/tx runs a list of statements atomically.

SQL rules that differ from PostgreSQL:
- Every table needs an explicit primary key, and INSERT supplies the key value.
- CREATE TABLE is a standalone statement outside a transaction. There is no ALTER TABLE,
  DROP TABLE or CREATE INDEX; an index comes only from a UNIQUE constraint at creation.
- Parameters are $1, ?1 or ?. Names are single-part (no schema.table).
- Column types follow SQLite affinity. In prepared statements ordinary columns are
  described as text; CAST(x AS INTEGER) when the driver needs a number.

Errors you must handle (SQLSTATE):
- 40001: conflict. Roll back and retry the whole transaction. Locking is no-wait, so
  this is normal under contention.
- 40003: commit outcome unknown. Do NOT retry. Look the transaction up with
  GET /db/<name>/txn/<txid> and replay only if the status is `aborted`.
- 57P03: cannot serve right now. Roll back, then retry the whole transaction with backoff.
- 53300: too many connections. Back off; keep the pool below the node's limit.

Credentials and scope:
- Use only the database token for this one database. Keep it server-side and out of
  source, logs, browser bundles and this conversation.
- Never use or ask for a deployment admin token, a client token or bucket credentials.
- Do not create, drop, back up, restore or branch databases, and do not rotate credentials.

Task:
1. Add the smallest connection integration that fits this project.
2. Run one explicit `SELECT 1` connectivity check. It may activate this database if it
   is idle; do not probe or wake any other database.
3. Do not change the schema or write application data unless I ask for it.

Report the files changed, the protocol and client used, the result of the check, and
anything this project needs that Gauntlet does not support.