# Bog Cloud agent guide

Prototype; keep backups. Origin: https://cloud.bog.new. Send Authorization: Bearer TOKEN; never expose tokens in chat/URLs/logs.

GitHub approval is enabled. Download /bog-app-access.py; `python3 bog-app-access.py --origin https://cloud.bog.new --connect --auth-file ./bog-auth.json`. Show approval link/code; helper polls and privately saves token. See /auth.md. MCP: read /mcp/server-card, initialize, tools/list.

## Try before sign-in (one hour)

`bog-cloud --origin https://cloud.bog.new try --name notes --output ./temporary-bog.json` creates a real Bog and saves its credential to an owned private file. No account or approval is needed. Add `--definition ./notes.json` to create with a bounded custom definition. Use `bog-cloud --config ./temporary-bog.json claim-link` when ready; show only the returned short-lived claim URL to the human. The human signs in with GitHub, chooses a workspace with room, and claims the same Bog before `expires_at`. Poll `GET /claim/CODE/status` for active, claimed, or expired; do not put the credential in chat. Old credentials stop working on claim. If the output file says pending after a network failure, retry the same command and file. Raw API: `POST /v1/claimable-bogs` with Idempotency-Key and JSON {"name":"notes","recovery_secret":"64 random hex characters"}; response includes a private credential, routes, and expiry. A retry with the same key and recovery secret rotates the old temporary credential. Do not print the raw response. MCP can use the temporary bearer after HTTP creation; neither MCP sign-in nor a browser login creates a temporary Bog.



## Three-call start

POST /v1/bogs with Idempotency-Key and {"name":"notes","wait":true}; PUT /v1/bogs/ID/docs/n1 with {"title":"Hello","body":"Remember","updated_at":1}; GET /v1/bogs/ID/views/docs?limit=10. Use returned ID; require ready. Retry identical key/body; capacity means retry same ID after capacity frees.

workspace_id defaults personal; shared must be explicit. GET /v1/workspaces: actual bog_limit (null=uncapped). Defaults 3 Bogs/workspace, 16 MiB/Bog; existing allowances differ; host/storage limits still apply.

## Composable notes

Instead create with {"name":"notes","wait":true,"definition":DEFINITION}. Use:
```json
{"expose":{"batch":{"action":"batch","target":"notes"},"get":{"action":"get","target":"notes"},"list":{"action":"list","target":"notes"},"put":{"action":"put","target":"notes"},"recent":{"action":"top","target":"recent"},"remove":{"action":"remove","target":"notes"},"semantic":{"action":"search","target":"semantic"},"text":{"action":"search","target":"text"},"wait":{"action":"wait","target":"notes"}},"input":"notes","resources":{"notes":{"terminal":{"kind":"table"}},"recent":{"terminal":{"ascending":false,"field":"/updated_at","kind":"ranked"}},"semantic":{"terminal":{"fields":["/title","/body"],"kind":"semantic"}},"text":{"terminal":{"fields":["/title","/body"],"kind":"bm25"}}},"version":1}
```
B=/v1/bogs/ID. Generated routes:
```text
POST B/resources/notes/query (list)
PUT B/docs/{key} (put)
POST B/resources/notes/query (wait)
POST B/resources/recent/query (recent)
POST B/resources/semantic/search (semantic)
POST B/resources/text/search (text)
```
POST query bodies: list {"action":"list","limit":10}, recent {"action":"top","limit":10,"include_fields":["/title"]}, wait {"action":"wait","cursor":"CURSOR","timeout":25}. Both searches: {"query":"remember","limit":5,"include_fields":["/title"]}. PUT the note above.

Table batch_get: {"action":"batch_get","keys":["n1"]}. List after/before: exclusive key bounds, no offset. include_fields results use pointer keys, e.g. "/title". Semantic max_distance 0–2; score=1-distance, no universal cutoff.

Keep cursor; wait returns seq,cursor,changed,reset. Refetch on changed/reset; no replay/automatic agent wake. Page max1000, offset max10000; wait 0–25s. 401: authenticate; 403: check scope/membership. writes_paused: await update. GET B/resources: schemas; /v1/components: enabled/limits. Updates: plan/apply/poll; only succeeded activates.

## Private app

prepare_app_access returns nonsecret handoff/command. Helper --handoff --output installs privately; --auth-file reuses only your approval. Never read another client's credentials. App tokens access one Bog only. Load installed config privately.

More: /docs.md /openapi.json /.well-known/agent-skills/index.json /.well-known/ard.json