# Quickstart

URL: https://briq.cloud/docs/getting-started

> Connect your agent client to briq and run your first briq.

briq is one MCP server: `https://api.briq.cloud/mcp`. Your agent adds it to its own config; no account or key
needed first.

## Connect your agent

1. Paste this prompt into your agent:

```text
Add the briq MCP server to your config:
- name: "briq"
- url: https://api.briq.cloud/mcp (Streamable HTTP, OAuth)
- for all my projects

Then tell me what to do next to connect and activate it. If needed, read the setup instructions for agents: https://briq.cloud/docs/setup/agents.md
```

2. Follow your agent's next steps: usually a restart, then a link to sign in.

3. Try it:

- GitHub repo: "Run hextris/hextris github repo on briq (https://briq.cloud/docs/guides/run-a-github-repo.md) and give me a link to it."
- Reporting: "Start Metabase on briq (https://briq.cloud/cookbook/metabase.md), load 'Our World in Data' energy dataset into it, generate a report on world energy generation, and share it with me." (Metabase is an open-source BI tool, like Tableau.)
- Postgres: "Start a Postgres for this project on briq (https://briq.cloud/cookbook/postgres.md) and connect the app to it."
- Web app: "Run this app on briq (https://briq.cloud/cookbook/node.md) and give me a preview link."
- Memory: "Start a SiYuan notebook on briq (https://briq.cloud/cookbook/siyuan.md), keep your notes on this project in it, and give me a link to browse them." (SiYuan is an open-source notes app, like Obsidian.)
- Planning: "Start a Plane board on briq (https://briq.cloud/cookbook/plane.md), turn our TODO list into issues, and give me a link to the board." (Plane is an open-source project board, like Linear.)

The prompt gives your agent the server's name and URL; it knows how to add it to its own
config. To do it yourself, see [Clients](https://briq.cloud/docs/setup/clients).

## Sign in

Your agent tells you when. Usually it needs a restart, then your browser opens on the sign-in
step, or the first time it uses briq. Sign in (or create an account; Google and GitHub work) and
approve the client for a team, with its budget. The client keeps the sign-in; the model never
sees it.

An agent that runs elsewhere (on a server, or behind a chat app) cannot open your browser. It
sends you a link and a code instead: open the link on any device, check the code matches the one
it showed you, and approve.

The client then appears on the dashboard's **Agents** page, where you change its limits or revoke
it. See [Agents, keys and policy](https://briq.cloud/docs/concepts/keys-and-policy).

<Callout title="No sign-in at all? Use an API key">
  For CI, containers and scripts, create a key on the **Agents** page and send it as a Bearer
  token: see [Clients](https://briq.cloud/docs/setup/clients#api-key). It works for the [REST API](https://briq.cloud/docs/api/overview) too.
</Callout>

## Your first briq

The client lists the `briq_*` tools and a `briq_getting_started` prompt. The tool descriptions
already tell the model how to use them; you do not need to write instructions.

Ask for something that needs a real service:

> Spin up a Postgres, apply the migrations in `db/migrations`, and tell me if they are clean.

```text
briq_run({ recipe: "postgres", params: { version: "16" } })
→ bq_7kq2m9x1p4ab db (postgres:16) running · …internal · cost so far … · sleeps at 18:42 UTC unless used
  outputs:
    DATABASE_URL=postgres://postgres:…@…internal:5432/app

briq_files_put({ briq: "bq_7kq2m9x1p4ab", path: "/m/001_init.sql", contentBase64: "…" })
briq_exec({ briq: "bq_7kq2m9x1p4ab", cmd: ["psql", "-U", "postgres", "-d", "app", "-v", "ON_ERROR_STOP=1", "-f", "/m/001_init.sql"] })
→ exit 0
  CREATE TABLE
  CREATE INDEX

briq_destroy({ briq: "bq_7kq2m9x1p4ab" })
→ bq_7kq2m9x1p4ab db (postgres:16) destroyed · …internal · cost so far …
```

* `briq_run` returns once the recipe's healthcheck passes, so the database is ready.
* Credentials are generated per run and returned once; they are masked in status, logs and audit.
* `DATABASE_URL` is a private address, reachable from briqs in your team, not from your machine.
  Run commands with `briq_exec`, or run your code in a briq of the same
  [stack](https://briq.cloud/docs/concepts/stack).
* If the agent forgets `briq_destroy`, the briq goes to sleep after an hour unused and costs
  nothing until something uses it again.

## Watch it

The [dashboard](https://briq.cloud/app) shows running briqs, spend and the audit log (one row per call, with agent,
action, target and cost). Stop, change when it sleeps, or destroy anything from there.

## Without an agent

Every MCP tool is a [REST](https://briq.cloud/docs/api/overview) call:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "recipe": "postgres", "wait": true }'

curl -X POST https://api.briq.cloud/v1/briqs/bq_7kq2m9x1p4ab/exec \
  -H "Authorization: Bearer $BRIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "cmd": ["psql", "-U", "postgres", "-c", "select 1"] }'

curl -X DELETE https://api.briq.cloud/v1/briqs/bq_7kq2m9x1p4ab \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```