drobek / docs

drobek for agents

docs/AGENT.md at v0.11.3 · View on GitHub · Markdown

On this page
  1. Connect
  2. Scopes and roles
  3. Tools
  4. The briefing
  5. Skills
  6. Where the contract is served

This is the agent-facing contract of a drobek server: how an agent connects, which tools it gets, what the briefing tells it, how skills work, and where the always-current copy of all of it is served. The authoritative, rendered version of the tool reference is the server's own /llms-full.txt; this page explains it.

Connect

The MCP endpoint is <PUBLIC_APP_URL>/mcp (Streamable HTTP) — locally http://localhost:3041/mcp, on the hosted drobek https://drobek.app/mcp. It is protected by OAuth 2.1: an MCP client that supports remote servers does discovery, client registration, PKCE and consent by itself. You approve the consent screen in the browser, with one checkbox per scope (read, write, publish), and the client gets a token bound to you.

Claude Code

claude mcp add --transport http drobek https://drobek.example.com/mcp

Then /mcp in Claude Code → drobek → sign in. For the hosted drobek, the plugin bundles the server, the build skill and a command:

claude plugin marketplace add freema/drobek-plugin
claude plugin install drobek@drobek
# then: /drobek:build-app <idea>, or /drobek:port-artifact to move a Claude artifact

Claude (web and desktop) — add a custom connector with the URL https://<your drobek>/mcp and sign in when asked. The server must be reachable over public HTTPS for that.

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "drobek": {
      "url": "https://drobek.example.com/mcp"
    }
  }
}

Sign in when Cursor asks. The plugin repository also has a one-click install link for the hosted drobek and the Cursor variant of the build skill.

Codex — for the hosted drobek:

codex plugin marketplace add freema/drobek-plugin
codex plugin add drobek@drobek
codex mcp login drobek

codex mcp login drobek opens the sign-in in the browser; restart Codex afterwards. For a self-hosted server, add an MCP server named drobek with your /mcp URL to Codex's MCP configuration and run the same login.

Without a browser (scripts, CI, a headless agent): a personal API key drk_… works as the Bearer token on the same endpoint, with the same scopes. Create it in the dashboard at /me/api-keys (shown once, revocation is immediate), or on a self-hosted server:

docker compose --env-file .env.production -f docker-compose.production.yaml exec drobek \
  node node_modules/@drobek/oauth/dist/cli/api-key-create.js \
  --email you@example.com --name laptop --scopes read,write,publish
claude mcp add --transport http drobek https://drobek.example.com/mcp \
  --header "Authorization: Bearer drk_…"

/me/connections lists the OAuth clients you approved and revokes them. API keys, OAuth connections, the sign-in e-mail (/me, confirmed by a code sent to the new address) and deleting the account itself (/me/delete, confirmed by a fresh e-mailed code) are dashboard-only: no MCP tool creates a key, revokes a connection, changes the sign-in e-mail or deletes an account.

The OAuth details

  1. An unauthenticated POST to /mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="…".
  2. GET /.well-known/oauth-protected-resource/mcp (RFC 9728) names the resource and the authorization server; GET /.well-known/oauth-authorization-server has the endpoints.
  3. The client identifies itself with a Client ID Metadata Document (an https client_id URL drobek fetches through its SSRF guard) or by Dynamic Client Registration (POST /oauth/register, 10 per IP per hour).
  4. /oauth/authorize with PKCE S256 and resource = exactly the MCP endpoint (RFC 8707) → consent → a code with iss (RFC 9207).
  5. /oauth/token → an access token for that audience only and a rotating refresh token. Sending a rotated refresh token again within 60 s (a retry after a lost response) gets a fresh pair; later, it is reuse and burns that lineage.
  6. drobek keeps no MCP session: every request is authenticated from its own credential and served on its own. A 2026-07-28 client sends each request with its protocol version in _meta and needs no initialize; a 2025-era client's initialize answers with the instructions and no Mcp-Session-Id, and a session id it still sends is ignored. A revoked key or connection gets 401 on its next request; a restart is invisible to the client.

Scopes and roles

A grant belongs to the user, not to a workspace. The scope decides which tools the client sees at all (tools/list shows exactly the granted ones); the user's role in the app's workspace decides each call: viewers read, editors and workspace-admins change. A workspace or app you cannot reach answers not_found, the same as one that does not exist.

Scope Tools
read list_apps, get_app, read_file, list_versions, skill_info, query_data, get_logs, get_analytics, list_assets, list_form_submissions, list_end_users, list_uploads, list_activity, list_domains, list_upstreams, list_members, list_feedback, get_feedback_screenshot, get_screenshot
write create_app, duplicate_app, write_files, restore_version, keep_version, delete_versions, configure_module, sync_now, create_asset_upload, delete_asset, add_domain, verify_domain, remove_domain, register_upstream, set_upstream_streaming, remove_upstream, set_frame_ancestors, release_lease, delete_app, create_records, update_record, delete_record, delete_collection, purge_orphan_records, delete_form_submission, set_end_user_role, set_end_user_blocked, sign_out_end_users, delete_upload, remove_module_secret, create_workspace, invite_member, set_member_role, remove_member, delete_workspace, resolve_feedback, delete_feedback, request_screenshot, set_workspace_module (super-admins only)
publish publish, unpublish, set_visibility, set_gallery_listing, set_primary_domain, set_workspace_publishing, takedown_app, restore_app, set_gallery_hidden (the last four for super-admins only)

Tools

Tool Scope, role Annotations What it does
list_apps read, any role read-only Who you are, your workspaces with your role, can_publish (+ publish_contact when the workspace may not publish) and the operator's publishing state (default / allowed / blocked), and the apps in them (preview/published URL, latest version, compile status, lock), plus next: before creating or changing an app, skill_info('start') (when the server has it) and the briefing. Start here — the MCP server's instructions say so too.
create_app write, editor+ not destructive A new app with a compiling version 1 from the react-ts (default) or html template, its preview_url, the briefing and the skills list.
duplicate_app write, editor+ in the target not destructive A copy of a gallery app whose owner allows duplicates (from: its slug or its address on this server — app host, verified custom domain or /duplicate/<slug>; another server's address is invalid_params), in the given workspace or the personal one: the source's published files as version 1 of a new, unpublished app that remembers its source (duplicated_from in get_app), and the source's module settings proposed through the copy's confirmation flow (modules.applied / pending with confirm_url / skipped; e-mail addresses, proxy upstreams and sync sources dropped). Never secrets, data, end users, uploads, assets or domains. not_duplicable, gallery_disabled, rate_limited (DUPLICATES_PER_USER_HOUR), limit_exceeded.
get_app read, any role read-only One app: the briefing, its files, the last 20 versions (each with published, preview and kept), the lock, the module configs (secrets as hasSecret only), visibility and frame_ancestors, the gallery state (with allow_duplicate and read-only likes and 30-day opens), duplicated_from for a copy, its custom domains in short (domains: host, status, primary), can_publish, publishing, and the latest version's render signal (render: page_loads — pages of that version that loaded in a browser, a count only — and errors — the browser errors they reported; beacon: false when its drobek.json turned the beacon off), preview_errors — the browser errors of the preview's version in short (version, distinct count, occurrences, latest_at; read them with get_logs kind browser) — and traffic — page views, estimated visitors and bot views of the last 7 days (absent when the server counts no visits).
read_file read, any role read-only Source files of the latest (or a given) version: path, or up to 20 paths in one call, and a line range of each with offset / limit (every text file says its total_lines). The first file always comes back; each further one only while the text stays within COMPILE_MAX_FILE_BYTES — the rest is listed under omitted, paths the version lacks under missing (none found → not_found). With search: the lines that contain a literal text (no regex; ignore_case; path / paths narrow it to files or folders) as { path, line, column, text }, at most limit (default 50, at most 100) with the total. Everything inside an untrusted envelope.
write_files write, editor+ destructive 1–20 changes → one new version → one compile; returns { version, base_version, compile: { ok, errors, warnings }, preview_url, changed, readiness }. An entry writes a whole file ({ path, content }), deletes one ({ path, delete: true }) or edits one in place ({ path, edits: [{ old_string, new_string, replace_all? }] }: exact-string replacements applied in order to the file of base_version, each old_string matching once unless replace_all); the kinds mix in one call. An edit that does not apply refuses the whole call with edit_mismatch (path, edit_index, reason). A secret in a file refuses the write. readiness is the publish readiness report (below). previous_version_browser_errors (only when above 0) counts the distinct browser errors the version it replaced raised in the preview — a cue to call get_logs kind browser.
restore_version write, editor+ destructive A new version with the files of an old one (rolls the working copy back); when that version was published, the draft assets go back to the ones it served then (assets_restored).
list_versions read, any role read-only The version history, newest first, a page at a time: limit 1 to APP_VERSIONS_PAGE (default 20; more is invalid_params), before = the previous page's next_before (null on the oldest page). Each version has published, preview (the newest that compiled) and kept; pinned lists those versions on every page. Returns { app_id, pinned, versions, next_before }.
keep_version write, editor+ not destructive, idempotent Keeps a version (kept: true) so neither the history retention nor a clean-up deletes it, or stops keeping it; audited app.version.keep / app.version.unkeep. At most APP_VERSIONS_KEPT_MAX per app (limit_exceeded past it); the same state answers changed: false; prunable after an unkeep says the next retention run deletes it. Works on a failed build and a taken-down app. Returns { app_id, version, kept, changed, prunable?, note }.
delete_versions write, editor+ destructive, idempotent Deletes old versions for good — every version up to up_to, or with failed_only only the failed builds — and frees their storage at once; audited app.versions.delete per batch. The published version, the preview's, kept versions, rollback sets, the newest version and the last hour's stay, listed under skipped by reason. Needs user_confirmed: true with the plan's plan_id — without it user_confirmation_required carries the plan (delete, count, skipped, plan_id) and nothing changes; the confirmed call deletes exactly that plan, and when the versions that would go changed in between it answers plan_changed and deletes nothing. Nothing to delete answers count: 0 without asking. A taken-down app answers app_locked_by_admin. Returns { app_id, deleted, count, skipped, note }.
publish publish, editor+ destructive, idempotent, open world Puts a compiled version on <slug>.<APPS_DOMAIN> and the verified domains, with the app's current assets frozen for it (an older version: the assets it served when it was last published) — the answer's assets is "draft" when the draft set the preview shows went live (production serves it now) and "as_last_published" for a rollback to an earlier set. Only when the user asks. A workspace the operator blocked gets publish_blocked; on a server with PUBLISH_APPROVAL=approval an unapproved workspace gets publish_not_approved (an approval request is already e-mailed) — both with the operator's contact. The answer carries the published version's readiness report; its warnings never stop a publish.
set_gallery_listing publish, editor+ not destructive, idempotent, open world Lists a published app in the server's public gallery with a ≤ 160-character description, changes the description, or unlists it. Listing needs user_confirmed: true — the user's explicit yes (else user_confirmation_required); unlisting needs none. allow_duplicate (listing only, covered by the same confirmation) lets signed-in people copy the app from the gallery; omitted keeps the choice. gallery_disabled when the server runs no gallery, gallery_hidden when the operator hid the app.
unpublish publish, editor+ destructive, idempotent, open world Takes the app off <slug>.<APPS_DOMAIN> and its verified domains ("not published"; the preview and version hosts keep serving, a listed app leaves the gallery) — the dashboard's Unpublish. Needs user_confirmed: true — the user's explicit yes (else user_confirmation_required). not_published when nothing is live, app_locked_by_admin for a taken-down app. Returns { app_id, unpublished_version, gallery_unlisted, note }.
set_visibility publish, editor+ destructive, idempotent, open world public or password on every host of the app (Settings → Visibility). The password is set only in the dashboard: password works for an app that already has one, otherwise password_not_set with settings_url. Making a password-protected app public drops its password and needs user_confirmed: true.
set_frame_ancestors write, editor+ not destructive, idempotent, open world Which other sites may embed the app (frame-ancestors on every host; Settings → Embedding): 'self' and/or up to 10 http(s) origins, validated like the dashboard (invalid_params otherwise); null = none. Replaces the whole list; returns it with previous.
release_lease write, editor+ not destructive, idempotent Frees the single-writer lease the caller's own writes hold (audited app.lock.release), so another member's agent can write at once; another user's lease stays (app_locked).
delete_app write, editor+ destructive, idempotent, open world Soft-deletes the app (Settings → Delete app): every host answers 404, it is gone from the dashboard and MCP, the slug is free after 30 days. Needs user_confirmed: true. Returns { deleted, app_id, slug_released_at, note }.
set_workspace_publishing publish, super-admin only not destructive, idempotent Sets a workspace's publishing: blocked (refused in every mode, its editors and admins e-mailed), allowed (may publish even under PUBLISH_APPROVAL=approval) or default (the server mode decides). Returns { workspace, publishing, mode, can_publish_now, changed }. Needs user_confirmed: true — the super-admin's explicit yes. Registered only for a super-admin's grant; live apps keep serving after a block (takedown_app takes one down).
skill_info read, any signed-in user read-only skill_info() lists the server's skills; skill_info('<name>') returns one (for a module also its SDK types, config schema, limits, secret names, its own error codes, and the facts the dashboard's workspace Modules page shows: version, source, contract range, availability, required modules, slots with their contributors and its own contributions). An opt-in module carries availability: "opt-in"; with app_id it also says enabled_for_workspace for that app's workspace.
configure_module write, editor+ destructive, idempotent Sets an app's module config (a JSON merge patch). Risky changes come back as pending_confirmation with a confirm_url for the owner; one made while another waits joins it (merged_with_pending), and the owner confirms or rejects the combined change. Secrets are refused.
query_data read, viewer+ read-only Records of one collection of the app's data module (≤ 100 per call, filters, sort, cursor), inside an untrusted envelope.
create_records write, editor+ not destructive, not idempotent 1–500 new records in a declared collection, as the app's owner (the Data tab: no end-user rules, no _owner), stored all or nothing: a record the schema refuses is invalid_params with its index and issues[], a quota (DATA_MAX_DOCS_PER_APP, DATA_MAX_BYTES_PER_APP, DATA_MAX_DOC_BYTES) limit_exceeded with limit + value — nothing stored. Skips the app's write rate limit, never a quota. Returns { app_id, collection, created, ids, note }; audited data.record_create (collection + count).
update_record write, editor+ destructive, idempotent Changes one record (id = its _id): fields merged onto the stored ones like the SDK's update, or with replace: true the record's own fields become exactly fields (the dashboard's JSON editor); _owner and _created_at stay. Schema and quotas checked; audited data.record_update.
delete_record write, editor+ destructive, idempotent Deletes one record for good (the Data tab's Delete); not_found for an unknown record; audited data.record_delete.
delete_collection write, editor+ destructive, idempotent Deletes a collection with its records and its declaration in the data config, in one transaction (the Data tab's Delete collection). Needs user_confirmed: true — the user's explicit yes (else user_confirmation_required with the record count); takes the app's single-writer lease. Audited data.collection_delete with the agent as the actor.
purge_orphan_records write, editor+ destructive, idempotent Deletes the records of collections the data config no longer declares (the Data tab's Orphan records) — every orphan collection, or the one named in collection. Needs user_confirmed: true (else user_confirmation_required with the orphans); no orphans → purged: []. Audited data.collection.purge.
get_logs read, viewer+ read-only kind: runtime (browser errors from the beacon — uncaught error / unhandledrejection, resource for a file that failed to load, csp for a request the CSP blocked, each with the version its page was served from, plus the latest version's page loads and errors on the envelope — and failed runs of a module's scheduled job, type module_job with module and job), compile (the compile history) or requests (daily request and module-call stats with the top failing paths per status class, path only), browser (the errors the preview and version pages raised in the browser — uncaught errors, unhandled rejections and console.error with an Error — deduplicated with a count, each with its version, page path and the stack mapped to the app's src/…:line:column; kept 48 hours by default; "browserErrors": false in drobek.json turns the reporting off), sync (the latest runs of the app's sync sources: source, trigger, status, records, error) or webhooks (the latest incoming webhook deliveries: endpoint, status, HTTP status, bytes, reason, record id — never the body), ≤ 100 entries, 30-day window, inside an untrusted envelope.
get_analytics read, any role read-only The Analytics tab: page views of the production address and custom domains (HTML pages people opened; preview and version addresses are not counted), an estimate of the day's unique visitors (a one-way hash with a daily salt, no cookies) and bot views per UTC day over days (default 30, at most ANALYTICS_RETENTION_DAYS), today live; totals with bot_share, the top 20 pages (path, no query) and referrer hosts (__other__ = past 200 a day). Answers inside <untrusted-app-analytics …> (paths and referrers come from visitors); enabled: false when the server counts nothing. get_app carries the last 7 days as traffic.
sync_now write, editor+ destructive, not idempotent, open world Runs one of the app's sync sources (the sync module's scheduled imports) now and returns the run { source, trigger, started_at, duration_ms, status, records, inserted?, updated?, deleted?, error }; a paused source runs too, and a successful run resumes one paused after failed runs. A failed run is status: "failed" with its error, not a tool error — nothing changed. not_found (+ available), rate_limited (SYNC_NOW_PER_MINUTE per source, SYNC_RUNS_PER_HOUR_PER_APP), busy (reason: "sync_running"), limit_exceeded, module_not_enabled. Audited sync.run with the agent as the actor.
create_asset_upload write, editor+ not destructive A single-use upload URL (30 min) for ONE binary file — video, audio, image, font — at path, plus a curl -T <file> '<url>' line. The file never passes through the model; the preview serves it at /<path> next to the app's files, production after the next publish.
list_assets read, viewer+ read-only The app's draft assets (path, sniffed type, size, time, published), the paths production serves that the draft deleted (published_only), changes_pending_publish and the quota usage.
delete_asset write, editor+ destructive, idempotent Removes one asset from the draft; the preview stops serving it, production after the next publish.
list_form_submissions read, viewer+ read-only The app's form submissions (the dashboard's Forms tab, through the module that keeps them): forms with their counts, then the submissions newest first, filtered by form and an inclusive UTC day range (from, to), ≤ 100 per call (default 20) with next_cursor. Only inside an untrusted envelope (no structuredContent) — the fields are what visitors typed.
delete_form_submission write, editor+ destructive, idempotent Deletes one submission (the Forms tab's Delete); not_found for an unknown or deleted one. Audited forms.submission_delete with the agent as the actor.
list_end_users read, viewer+ read-only The app's end users (the Users tab): id, email, role (+ role_source), status, provider, created_at, last_sign_in_at, filtered by search (part of an address), ≤ 100 per call (default 50) with next_cursor. Only inside an untrusted envelope: the addresses are personal data.
set_end_user_role write, editor+ destructive, idempotent Makes an end user admin or user through the sign-in module, which changes its config (the auth module's adminEmails) under the app's single-writer lease. A change the module refuses is conflict with a reason (workspace_editor, too_many_admins, allowlist_full). Answers the id, role and status, never the address. Audited end_users.role with the agent as the actor.
set_end_user_blocked write, editor+ destructive, idempotent Blocks (blocked: true) or unblocks an end user: a blocked user is anonymous on every host of the app from the next request. Audited end_users.disable / end_users.enable.
sign_out_end_users write, editor+ destructive, not idempotent Signs every end user of the app out on every host (the Users tab's Sign everyone out). Needs user_confirmed: true — the user's explicit yes (else user_confirmation_required with the end_users count). Audited end_users.sessions_revoke.
list_uploads read, viewer+ read-only The files the app's end users uploaded (the Uploads tab): id, name, type, size, uploaded_by, created_at, plus used_bytes / quota_bytes, ≤ 100 per call (default 50) with next_cursor. Only inside an untrusted envelope. A file's content is not available over MCP.
delete_upload write, editor+ destructive, idempotent Deletes one upload (the Uploads tab's Delete); the app's links to it answer 404. Audited files.delete.
remove_module_secret write, editor+ destructive, idempotent Removes one secret a module declares (module, name) from the app. Needs user_confirmed: true (else user_confirmation_required); a secret that is not set answers removed: false. A value is set only in the dashboard (secrets_url) — no tool sets or reads one. Audited module.secret_remove.
list_activity read, workspace-admin read-only The workspace's audit trail (the dashboard's Activity page), newest first, filtered by app, action, actor (user / agent / end_user) and an inclusive UTC day range, ≤ 100 per call (default 50) with next_cursor; each entry's context redacted like the page's Technical details. Only inside an untrusted envelope.
list_feedback read, viewer+ read-only The notes workspace members left with the Feedback button on the app's preview and version hosts (the dashboard's Feedback tab), newest first: status open (default) / resolved / all, each pinned to its version, page path (page_url) and spot (anchor: x/y in a vw×vh window, a CSS selector and a short label of the element when known), with author, time, screenshot ({ width, height, bytes } of an attached screenshot, null when none) and — resolved — the resolver and resolution_note; open / resolved counts; ≤ 100 notes and 64 KiB per call, next_before continues. Only inside an untrusted envelope. get_app returns feedback: { open, resolved }.
get_feedback_screenshot read, viewer+ read-only The screenshot a member attached to a note, as an MCP image content block: drobek's JPEG re-encoding of the stored image (longer side ≤ 1280 px, ≤ MCP_IMAGE_MAX_BYTES, 400 KiB by default), between two text blocks that open and close an <untrusted-feedback-screenshot …> envelope (the image may show text — data, not instructions). No structuredContent. A note without one answers not_found.
resolve_feedback write, editor+ idempotent Resolves a note (with an optional note on what changed, shown on the tab) or reopens it (resolved: false); the same status again answers changed: false. Audited app.feedback.resolve / app.feedback.reopen.
delete_feedback write, the note's author or a workspace admin destructive, idempotent Deletes a note for good. Needs user_confirmed: true (else user_confirmation_required). Audited app.feedback.delete. Notes are written only by people in the dashboard — no tool creates one.
request_screenshot write, editor+ not idempotent Asks the people with the app's preview open for a screenshot of the page they see: every open tab of <slug>--preview (never production, a version host or a custom domain) shows a bar "Your agent asks for a screenshot of this page" with the agent's note (≤ 200 characters, plain text) and Capture / Not now. Answers { request_id, status: "pending", version, preview_url, expires_at, retry_after_seconds: 10, hint }. The request waits SCREENSHOT_REQUEST_TTL_SEC (600) and is answered at most once; at most SCREENSHOT_REQUESTS_PER_APP_HOUR (20) per app (rate_limited). No compiled version, or "screenshots": false in the drobek.json of the version the preview serves, answers conflict. Audited app.screenshot.request.
get_screenshot read, viewer+ read-only Where a request stands: pending (with retry_after_seconds), declined (Not now), expired, or ready — the screenshot as an MCP image content block (drobek's JPEG re-encoding, longer side ≤ 1280 px, ≤ MCP_IMAGE_MAX_BYTES) between two text blocks of an <untrusted-agent-screenshot …> envelope, no structuredContent. Kept SCREENSHOTS_RETENTION_DAYS (7); an unknown id, an app the caller cannot reach and a deleted screenshot answer the same not_found.
list_domains read, viewer+ read-only The app's custom domains (the dashboard's Domains tab): per domain host, status (pending / verified), primary, the two DNS records to create, verified_at, last_check_at, last_error, the certificate state; plus cname_target and max_per_app.
add_domain write, editor+ not destructive, idempotent Attaches a domain the user owns (pending) and returns the two records: CNAME <host> → <slug>.<APPS_DOMAIN> and TXT _drobek.<host> = drobek-verify=<token>. Same validation and DOMAINS_MAX_PER_APP as the dashboard (invalid_hostname, hostname_not_allowed, limit_exceeded, domain_already_added, domain_taken).
verify_domain write, editor+ not destructive, idempotent, open world Looks both records up now. Verified → the domain serves the published version. Otherwise domain_not_verified with cname / txt = ok / missing / wrong and the expected records (DNS can take up to 48 hours), or dns_unavailable (a lookup failed; nothing changed).
set_primary_domain publish, editor+ not destructive, idempotent, open world Makes a verified domain primary — <slug>.<APPS_DOMAIN> answers 302 to it — or clears it (host: null). Needs user_confirmed: true.
remove_domain write, editor+ destructive, idempotent, open world Detaches a domain; a verified one stops serving at once and needs user_confirmed: true, a pending one does not.
list_upstreams read, workspace-admin read-only The workspace's proxy upstreams (the dashboard's Upstreams page): name, base_url, allowed methods and path prefixes, auth_type, auth_header_name, has_secret (never the key), allow_streaming, the apps whose assignment was confirmed; plus upstreams_url.
register_upstream write, workspace-admin not destructive, idempotent Registers an external API for the proxy module with the dashboard's checks (public host, port 80/443, allowed methods and path prefixes). allow_streaming: true (default false) lets a text/event-stream answer reach the app as it arrives; otherwise every answer is buffered. auth_type: "none" registers at once. bearer / header need a key, which never passes through MCP: the answer is registered: false with secret_url, the Upstreams page with the fields filled in, where the user pastes the key. One upstream is one host; never register many similar hosts (a feed per region) without asking the user. A taken name answers upstream_already_registered; limit_exceeded (UPSTREAMS_MAX_PER_WORKSPACE), rate_limited (UPSTREAM_REGISTRATIONS_PER_HOUR, retry_after_seconds).
set_upstream_streaming write, workspace-admin not destructive, idempotent Turns streaming passthrough on or off for a registered upstream (the Upstreams page's Turn streaming on / off): on, a text/event-stream answer reaches the app as it arrives and holds a proxy slot until it ends (at most PROXY_STREAM_MAX_MS); off, every answer is buffered. Keeps the key and the app assignments; audited proxy.upstream.update. Returns { upstream, changed, note }.
remove_upstream write, workspace-admin destructive, idempotent Deletes an upstream and its key; every app calling it breaks at once, so it needs user_confirmed: true (without it: user_confirmation_required with the apps using it).
create_workspace write, any signed-in user not destructive, idempotent A team workspace — the "New team" form on /workspaces, with its rules: name 1–80 characters, slug 3–40 of [a-z0-9-], not reserved, unique on the server (slug_taken). The caller becomes its workspace-admin. Returns { workspace, name, kind, role, workspace_url, next }. Not audited, like the dashboard form.
list_members read, any role read-only The workspace's members (the dashboard's Members tab): email, role, you; plus the workspace kind, your role, can_manage (a workspace-admin of a team workspace) and members_url.
invite_member write, workspace-admin of a team workspace not destructive, not idempotent, open world E-mails email an invite to the workspace as viewer, editor or workspace-admin — the Invite page's checks (team workspace only, role, one valid address) and its member.invite audit row (the role, never the address), here with the agent as the actor. Needs user_confirmed: true — it e-mails a person outside the conversation. The link adds whoever opens it, so it travels only in the e-mail and never through MCP; when the e-mail cannot be sent the invite is withdrawn and the answer is unavailable (reason: "email_failed"). A link-only invite stays in the dashboard. Returns { workspace, email, role, invited, expires_in_days, note }.
set_member_role write, workspace-admin not destructive, idempotent Sets a member's role (viewer / editor / workspace-admin) in a team workspace; a new viewer's edit locks on the workspace's apps are released (released_locks). Never demotes the only workspace-admin (last_workspace_admin); a personal workspace answers personal_workspace. Audited member.role_change.
remove_member write, workspace-admin (any role to leave) destructive, idempotent Removes a member, or with your own e-mail leaves the workspace. The member loses access at once (not_found everywhere) and their edit locks are released; their apps and versions stay. Needs user_confirmed: true (without it: user_confirmation_required with the member's role). Never the only workspace-admin (last_workspace_admin), never a personal workspace (personal_workspace). Audited member.remove / member.leave.
delete_workspace write, workspace-admin destructive, idempotent Deletes a team workspace for good: every app (published or not) is deleted and purged at once with its versions, data, uploads and custom domains, and the memberships, pending invites, upstreams and module opt-ins go with the workspace. Needs user_confirmed: true (without it: user_confirmation_required with apps, published, members, pending_invites, upstreams; nothing changes). Returns { deleted, apps, members, note }; afterwards the workspace and its apps answer not_found. A personal workspace answers personal_workspace: it goes only with its owner's account, deleted in the dashboard. Audited workspace.delete (also in the deleting admin's personal workspace).
set_workspace_module write, super-admin only destructive, idempotent Turns an opt-in module on or off for a workspace — the super-admin's switch on Workspace → Modules. Enabling while a required module is off is module_requires_not_enabled (missing); disabling turns its dependents off too (dependents_off). A plan or MODULE_ENABLED_<NAME>=1 still wins: enabled is the effective state, switch the row, source what decides. Needs user_confirmed: true; a switch already in that state answers changed: false. Audited module.workspace_enable / module.workspace_disable with the agent as the actor. Confirming or rejecting a module change that waits for a workspace admin stays in the dashboard.
takedown_app publish, super-admin only destructive, idempotent, open world The moderation queue's Take down: app is the app_id, the slug or one of its addresses (an app host or a verified custom domain), reason the category (phishing, malware, spam, copyright, illegal, other). Unpublishes the app, makes every address answer 451, refuses every change by its owners (app_locked_by_admin), resolves its open reports, ends a gallery listing and e-mails its owners the category. Needs user_confirmed: true (the confirmation lists the addresses, domains, open reports and gallery state); an app already taken down answers changed: false. Audited admin.takedown with the agent as the actor.
restore_app publish, super-admin only not destructive, idempotent, open world The queue's Restore: lifts a takedown; the app stays unpublished until its owner publishes, and its owners are e-mailed. Needs user_confirmed: true; an app that is not taken down answers changed: false. Audited admin.restore.
set_gallery_hidden publish, super-admin only not destructive, idempotent, open world The queue's Hide / Show: hidden: true takes the app off the public gallery and keeps its owner from listing it (gallery_hidden); false lets the gallery show it again while its owner lists it. Needs user_confirmed: true; the state it already has answers changed: false. Audited app.gallery_hidden / app.gallery_unhidden.

Every tool carries all four MCP annotations explicitly (readOnlyHint, destructiveHint, idempotentHint, openWorldHint; "idempotent" above means a repeated call with the same arguments has no further effect). They are hints for clients, never a security boundary — the scope and the role are. The per-tool values are in the tool manifest (@drobek/agent-dx tools.ts) and in every tools/list answer.

A failed call returns isError: true with { code, message, hint } from the error catalogue (@drobek/agent-dx errors-catalogue.ts, rendered into /llms-full.txt). A platform module's own route codes are declared by the module (errors): skill_info('<module>').errors returns them and /llms-full.txt lists them after the core codes, one section per active module. A query the database cut off (the server is under load) answers busy with reason: "database_timeout" from any tool. A compile error is not a tool failure: it is compile.ok: false with compile.errors[], and the version is stored.

Video, audio and big files (assets). write_files is text-only, and a binary must never travel through the model as base64. create_asset_upload({ app_id, path, size, content_type? }) checks everything that needs no bytes — the path (1–4 segments of [A-Za-z0-9._-], an allowed extension: png jpg jpeg gif webp avif ico svg mp4 m4v m4a webm mp3 ogg oga wav woff woff2), no app file at that path (asset_path_taken), APP_ASSET_MAX_BYTES (asset_too_large), APP_ASSETS_QUOTA (asset_quota_exceeded), a content_type that fits the extension (asset_type_not_allowed), APP_ASSET_UPLOADS_PER_HOUR (rate_limited) — and returns { upload_url, method: "PUT", expires_at, max_bytes, asset_path, asset_url, curl }. The URL is on the dashboard host (PUT /api/assets/upload/<token>), valid 30 minutes, good for exactly ONE upload of exactly size bytes, and needs no other credential; a browser GET on it shows an upload page, so the agent can hand the link to the user. The PUT streams the body to disk, sniffs the bytes (the type is the content's, never the name's) and answers 201 { name, path, size, type, replaced, url } or { code, message, hint } (asset_size_mismatch, upload_token_invalid, …, forbidden when that user is no longer an editor of the app). The upload is audited as the user who asked for the URL. Assets share the app's URL space — <video src="film.mp4" poster="poster.jpg"> and img/s1.jpg work unchanged, so a Claude artifact ports by writing its HTML/JS with write_files and uploading each binary at the relative path the page uses; the app's own file wins over an asset at the same path. Videos seek (HTTP Range). The dashboard's Assets tab does the same for the owner.

Assets honour publish. An upload, a replacement or a delete_asset changes the app's DRAFT assets: the preview shows it at once, the production URL (and the custom domains) only after publish — so a write-scoped agent never changes what a published app serves. publish freezes the draft for the version it puts live and answers assets: "draft" — the name says where the set came from; production serves it from that moment. Publishing an older version (the rollback) brings back the assets it served when it was last published, and restore_version of a published version resets the draft assets to those. list_assets marks each asset published or not. The quota counts every unique file of the draft and the published set once; sets of earlier publishes are kept for a rollback while they fit.

Custom domains. The domain tools are the dashboard's Domains tab over MCP and call the same @drobek/domains operations: the same checks and limits, the same audit rows (domain.add, domain.verify, domain.unverify, domain.primary, domain.remove, actor kind agent). The flow: add_domain({ app_id, host }) → show the user the CNAME and TXT records → verify_domain once they created them (domain_not_verified says which record is missing or wrong; verify again after a while, not in a loop) → a verified domain serves the published version and appears in publish's domains. What changes the public site asks for the user's explicit yes (user_confirmed: true, else user_confirmation_required): set_primary_domain (set or clear) and removing a verified domain. A taken-down app refuses adding, verifying and a primary domain; removing stays possible. See SELF-HOSTING.md for apex names, TLS and the daily re-check.

Porting a Claude artifact. drobek hosts what a Claude artifact is. The agent that has the artifact's files does the port; the server fetches nothing from claude.ai (there is no API for it, and a private artifact sits behind the user's sign-in). The general skill port-artifact (skill_info('port-artifact')) is the procedure: ask the user → create_app → every text file with write_files, paths and content unchanged → every binary with create_asset_upload at the same relative path (curl -T from the agent's sandbox, or the link for the user) → check compile.ok, list_assets and the preview → publish only when the user asks → offer the gallery (set_gallery_listing only after the user's explicit yes). It lists what changes on the way: scripts only from the app and esm.sh (a CDN <script src> becomes an esm.sh import or a copied file), fetch only to the app (external APIs through the proxy module), <iframe> only the curated embeds, and no window.claude.* runtime API (window.storage → localStorage or the data module). The plugin carries the same procedure as /drobek:port-artifact (Claude Code, Cursor) and the port-artifact-to-drobek skill (Codex). task eval -- --only d has a fresh agent port a fixture artifact and checks the result.

Porting an app from Lovable, Bolt or v0. Those tools export a Vite + React + TypeScript project (often Tailwind, shadcn/ui and a Supabase client). The general skill port-app (skill_info('port-app')) moves one to drobek without a rewrite: the agent inventories package.json, the routes, the env and the backend calls, shows the user the plan, then create_app (react-ts) and write_files in parts with the paths unchanged. drobek.json maps each dependency to a pinned esm.sh URL (?deps=react@<version> on every package that imports React, so the page has one React) and resolves the shadcn/ui @/ alias with "paths": { "@/*": ["src/*"] }; index.html loads /main.js and Tailwind v4's browser build, with the tailwind.config colors and @apply rules in a <style type="text/tailwindcss">; public/ binaries go up with create_asset_upload. Supabase Auth, tables (rows via create_records or a sync source), Storage and Edge Functions become the auth, data, files and proxy modules, client-side mail email, third-party forms forms, incoming webhooks webhooks; a public import.meta.env.VITE_* value becomes a constant, a secret the key of a proxy upstream. Build config, .env, server code and third-party scripts are not ported, and a Next.js, Remix or SvelteKit server part does not port at all. task eval -- --only e has a fresh agent port the Lovable-shaped fixture tests-eval/fixtures/lovable-export.

Compile warnings. Next to esbuild's own warnings, compile.warnings of write_files and create_app lists references the browser will fail to load — warnings only, the version is stored and compiles as usual. Each is { code, file, line, text } with the fix in text. missing_reference: a literal same-app path (HTML src/href of link, script, img, a, source, video and audio, icon <meta>s, web manifest icons, CSS url() and @import, a fetch() / new URL() of a /path) names a file the version does not have and that is not an uploaded asset — a 404. blocked_by_csp: a literal URL of another origin where the app CSP refuses it (a fetch() to an API → connect-src, a <script src> / import / drobek.json import from a host other than esm.sh → script-src, an http:// image or font), naming the directive, what it allows and the fix (a proxy upstream, an esm.sh URL, https, or the file in the app). The policy is read from one list in @drobek/compile (app-csp.ts) that the app hosts build their header from. Computed URLs, data:, blob:, mailto:, tel:, #…, /__drobek/…, extension-less paths (they get index.html) and the build's own outputs (main.js, main.css) are never reported; <a href> to another site is navigation and passes.

Publish readiness. write_files and publish answer a readiness report — the dashboard's app page shows the same report for the newest version above the version list: { ready, blocking, warnings, warnings_omitted? }, each entry { code, file?, line?, message, hint } from the error catalogue. blocking is the compile errors (the only thing that stops a publish, as before; a credential is refused before anything is stored); warnings never stop a write or a publish. The report is deterministic and reads only the version's source files and the app's module configs — no app code runs. The checks: missing_title (index.html has no, or an empty, <title>), missing_description (no, or an empty, <meta name="description"> in its head), missing_favicon (no <link rel="icon"> in its head and no favicon.ico file in the version — an uploaded favicon.ico counts once it is linked, since uploads are not version files), og_image_not_absolute (an og:image / twitter:image meta of any page that is not an absolute https:// URL — link previews ignore it), and the module rules audit over the app's module configs — data_public_write_no_schema / data_public_write_unbounded (a collection anyone may create or update without a schema, or with strings without maxLength / extra properties), data_public_read_personal (a public read of e-mail, phone or address fields), rule_needs_auth_module (a data, forms or proxy rule that needs a sign-in while the auth module is not active), proxy_public_upstream (an upstream anonymous visitors may call) and module_change_pending (a change still waiting for the owner's confirmation). Each names the collection, form or upstream and the exact configure_module fix. The forms module has no per-form limit or captcha setting (honeypot, time token and the per-IP / per-app limits always apply), so a public form is not a warning. xss_html_sink, xss_eval and xss_url_sink are the client-side XSS check (a token-level lint of the scripts and inline <script>s for innerHTML/outerHTML/insertAdjacentHTML/document.write/ dangerouslySetInnerHTML, eval/new Function/string timers, and DOM href/src/ location or a JSX frame/script src set from a value that is not a literal — literals, templates without ${} and escaped substitutions pass; vendored and .min.js files are skipped). READINESS_MAX_WARNINGS (default 50) caps the listed warnings; the rest are counted in warnings_omitted. The checks live in packages/compile/src/readiness/checks/ — one file per check, one line in its registry.

Type check. esbuild strips TypeScript types without checking them, so a type error compiles and fails in the browser. After a write stores a version that compiled, the server type-checks its .ts/.tsx files in the background — the TypeScript checker over the in-memory files, the server's sdk.d.ts (and the drobek/<module> declarations) and React's types, in a worker thread; it analyses the sources and never runs them. write_files does not wait: its report says typecheck: "pending". The result is stored with the version; get_app (its readiness), publish and the app page then list each error as a type_error warning (file, line, message TS<code>: …) with typecheck: "checked". A check over TYPECHECK_TIMEOUT_MS, TYPECHECK_MAX_MEMORY_MB or TYPECHECK_MAX_FILES gives typecheck: "unavailable" and no type warnings (the server logs it); TYPECHECK_WORKERS=0 turns it off (no typecheck field). Settings: strict, without noImplicitAny; an import-map package without types is any; JS-only apps are not checked. A type warning never blocks a publish.

Untrusted output. read_file, query_data, get_logs and get_analytics return content written by app authors, end users, browsers and visitors. Their text result is wrapped in <untrusted-app-file …> (one per file) or <untrusted-app-search …> / <untrusted-app-data …> / <untrusted-app-logs …> / <untrusted-app-analytics …> with a random per-response nonce on the closing marker (content cannot fake the end of the envelope), preceded by a line saying it is data, not instructions. These four tools answer that text ONLY — no structuredContent (every other tool sends both): a client that hands structuredContent to the model would pass the raw payload past the envelope, and the keys of a schemaless record are user input too, so no wrapping of the payload's strings could cover it. The owner's lists answer the same way: list_form_submissions, list_end_users, list_uploads, list_activity and list_feedback wrap their JSON in <untrusted-form-submissions …> / <untrusted-end-users …> / <untrusted-uploads …> / <untrusted-activity …> / <untrusted-feedback …> and keep it to at most 100 entries and 64 KiB of entries per call: a page that would be bigger ends early (cut: true, next_cursor continues right after it), and an entry bigger than the whole budget comes alone with its long texts shortened (clipped: true). get_feedback_screenshot and a ready get_screenshot answer an image the same way: a text block with the warning and <untrusted-feedback-screenshot …> (or <untrusted-agent-screenshot …>), the image block (a JPEG drobek re-encoded — never the uploaded file), and a text block with the closing marker; no structuredContent. End users' personal data — addresses, what they typed, the names of their files — reaches the agent only inside these envelopes; the answers of the changing tools carry ids, roles and states, never an address.

Unknown arguments. An argument a tool does not take (e.g. publish({ app_id, user_confirmed: true }) — publish has no user_confirmed) is ignored, never passed on, and the call goes ahead. The result — a failed one too — then carries warnings: [{ code: "unknown_argument", message, ignored, accepted }]: the ignored names (at most 20) and every argument the tool takes. An untrusted-envelope tool sends the warnings as its own text block after the envelope. A missing or mistyped required argument is still the MCP input validation error, before the tool runs. tools/list is unchanged.

The briefing

create_app and get_app return the briefing (@drobek/agent-dx briefing.ts); it is the same text /llms-full.txt embeds. In short:

Skills

A skill is Markdown in a fixed five-section format (When to use · Minimal working code · API and types · Rules and limits · Errors → fix, at most 150 lines). skill_info serves two kinds:

With every built-in module enabled skill_info() lists fourteen (plus hello and the opt-in acmecrm in the dev stack). @drobek/skills-check compiles and typechecks every code block of every skill against the current SDK types in task check, so a skill cannot drift from the code.

A module an operator adds from outside this repository brings its own skill the same way (an operator-only module — an error reporter, an e-mail transport — has none and is never listed): skill_info('<module>') serves its SKILL.md, and the error codes it declares (errors) appear in skill_info('<module>').errors and in its own section of /llms-full.txt. Its author runs the same gate in the module's tests — checkSkill(module) from @drobek/modules/testing, which the create-drobek-module scaffold wires into npm test — so an external skill is held to the format and the compile + typecheck rules of the built-in ones (MODULES.md → Writing a module).

skills/drobek is different: it is the platform skill an agent installs to reach drobek in the first place (cp -r skills/drobek ~/.claude/skills/drobek), so skill_info does not list it. The plugin (freema/drobek-plugin) ships Claude Code, Codex and Cursor variants of the same loop.

Where the contract is served

Surface What
/llms.txt the concise index: summary, links (incl. this document), plugin install lines, the MCP endpoint, every tool with its scope
/llms-full.txt the full contract: the OAuth flow, every tool with inputs, result shape and an example, the briefing, the limits, the error catalogue
/build-with-your-agent the human setup page (plugin, MCP endpoint, skill install)
MCP resources drobek://docs/llms-full, drobek://docs/tools the same content for a connected agent without web access

The docs links (this guide, the modules, self-hosting and security docs) point at the Markdown files in the GitHub repository, or — when the operator sets DOCS_URL — at <DOCS_URL>/<page> (/llms.txt links the .md twins, e.g. <DOCS_URL>/agent.md).

All of them render from the @drobek/agent-dx manifest (TOOL_DOCS, the briefing, LIMITS, the error catalogue). The drift guard packages/oauth/src/resource/tool-docs-parity.test.ts asserts that the tools the MCP server registers equal the manifest (names, input fields, annotations, scopes), and packages/agent-dx/src/skill.test.ts holds skills/drobek/SKILL.md to the tool list and the loop rules. A change to the tool surface or the SDK updates the manifest, skills/drobek and the plugin's skills in the same change.