# Connect an agent

> Status: Available. Give a coding agent an accurate prompt, a database-scoped token and nothing else.

| | |
|---|---|
| **Works** | A copyable prompt that describes the real protocol, dialect and error rules. Database-scoped tokens. Documentation as Markdown and llms.txt. |
| **Differs** | The prompt assumes the token is already in the environment. It never contains a secret. |
| **Missing** | An installer, an SDK package, an MCP server and agent skills. They are planned, not shipped. |
| **Operational impact** | The connectivity check `SELECT 1` may activate that one idle database. Nothing else is woken. |
| **Evidence** | The prompt text is generated from the same source as the site's Copy agent prompt button. |

## The prompt

Use the **Copy agent prompt** button on the [home page](https://gauntlet-db.stavros.xyz/), 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](https://gauntlet-db.stavros.xyz/docs/roadmap.md).

## 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](https://gauntlet-db.stavros.xyz/docs/concepts/scale-to-zero.md)).

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.

---
Source: https://gauntlet-db.stavros.xyz/docs/agents