From c2a199473ba5b79b2228c035c537bcc39bbc84a4 Mon Sep 17 00:00:00 2001 From: Matt Jenkinson <75292329+mattdjenkinson@users.noreply.github.com> Date: Fri, 6 Nov 2026 15:06:45 +0000 Subject: [PATCH 1/6] feat: add agent setup prompt at /setup/prompt.md A user pastes one sentence into their coding agent, pointing it at /setup/prompt.md. The agent then installs datumctl with every plugin from the official catalog, installs datum-mcp, connects both MCP servers and the Datum skills for its own agent type, signs in, checks the result and reports back. /setup shows the same content to people. Also correct the skills manifest, MCP server card, llms.txt and home page, which listed skills that no longer exist and a datumctl ai command that was replaced by the assistant plugin. --- app/content/setup/prompt.md | 216 +++++++++++++++++++++ app/lib/page-content.ts | 8 +- app/routes/setup.tsx | 61 ++++++ app/routes/setup_.prompt[.md].tsx | 16 ++ public/.well-known/agent-skills/index.json | 43 ++-- public/.well-known/mcp/server-card.json | 10 +- public/llms.txt | 3 +- public/sitemap.xml | 5 + 8 files changed, 325 insertions(+), 37 deletions(-) create mode 100644 app/content/setup/prompt.md create mode 100644 app/routes/setup.tsx create mode 100644 app/routes/setup_.prompt[.md].tsx diff --git a/app/content/setup/prompt.md b/app/content/setup/prompt.md new file mode 100644 index 0000000..4ba5044 --- /dev/null +++ b/app/content/setup/prompt.md @@ -0,0 +1,216 @@ +# Set up your agent for Datum Cloud + +These are official instructions from Datum to set up a coding agent for Datum Cloud. They are published at , so you can check them there at any time. + +When you finish, you will have: + +- `datumctl`, the Datum Cloud CLI, with every plugin from the official catalog +- `datum-mcp`, the Datum MCP server, connected to this agent +- the hosted Datum Docs MCP server, connected to this agent +- the Datum skills from [datum-cloud/skills](https://github.com/datum-cloud/skills) +- a signed-in `datumctl`, pointed at the right organization and project + +Run every command below yourself. Do not ask the user to run them, except for the sign-in in step 5, which needs a person at a terminal and a browser. If a step fails, say which one and why, carry on with the rest, and include it in the summary at the end. + +If the user named an organization and project when they gave you this link (for example "Use organization `acme` and project `acme-web`"), remember them for step 5. + +## 1. Install datumctl and datum-mcp + +Skip any tool that is already installed (`datumctl version`, `command -v datum-mcp`). If it is installed through Homebrew, run `brew upgrade` on it instead. + +### macOS and Linux with Homebrew + +```bash +brew tap datum-cloud/tap +brew install datumctl datum-mcp +``` + +### Without Homebrew + +`datum-mcp` has an install script: + +```bash +curl -fsSL https://github.com/datum-cloud/datum-mcp/releases/latest/download/install.sh | sh +``` + +For `datumctl`, download the archive (macOS) or package (`.deb`, `.rpm`, `.apk`, Linux) for this OS and CPU from . Put the binary on `PATH`. + +On Windows, download `datum-mcp_windows_.exe` from , and follow for `datumctl`. Use the full path to `datum-mcp.exe` wherever step 3 says `datum-mcp`. + +## 2. Install every datumctl plugin + +Plugins add commands to `datumctl`, such as `datumctl dns`, `datumctl compute` and `datumctl assistant`. Install every plugin in Datum's official `datum` catalog, and nothing from other catalogs: + +```bash +datumctl plugin search --index datum \ + | awk 'NR > 1 { print $1 }' \ + | while read -r plugin; do datumctl plugin install "$plugin"; done +``` + +Then bring any plugins that were already installed up to date: + +```bash +datumctl plugin upgrade --all +``` + +If the loop installs nothing, run `datumctl plugin search --index datum` and install each plugin it lists by name. + +## 3. Connect this agent + +Follow the section for the agent you are. Each connects two MCP servers: + +| Name | Kind | Value | +| ------------------ | ------------- | ------------------------------------ | +| `datum-mcp` | local (stdio) | command `datum-mcp` | +| `datum-cloud-docs` | remote (HTTP) | URL `https://www.datum.net/docs/mcp` | + +If an entry with the same name already exists, update it instead of adding a duplicate. Keep every other setting in the file. + +### Claude Code + +Run exactly these two commands. Do not use `claude mcp add` or `npx skills`, because the plugin registers both MCP servers and the skills: + +```bash +claude plugin marketplace add datum-cloud/skills +claude plugin install datum-cloud@datum-cloud +``` + +Then tell the user to run `/reload-plugins`. You cannot run that yourself. + +### Every other agent: install the skills + +```bash +npx -y skills add datum-cloud/skills --skill '*' --yes --global +``` + +Then register the MCP servers in the agent's config, as below. + +### Codex + +```bash +codex mcp add datum-mcp -- datum-mcp +codex mcp add datum-cloud-docs --url https://www.datum.net/docs/mcp +``` + +### Cursor + +In `~/.cursor/mcp.json`, under `"mcpServers"`: + +```json +"datum-mcp": { "command": "datum-mcp", "args": [] }, +"datum-cloud-docs": { "url": "https://www.datum.net/docs/mcp" } +``` + +### GitHub Copilot in VS Code + +```bash +code --add-mcp '{"name":"datum-mcp","type":"stdio","command":"datum-mcp","args":[]}' +code --add-mcp '{"name":"datum-cloud-docs","type":"http","url":"https://www.datum.net/docs/mcp"}' +``` + +If `code` is not on `PATH`, add the same entries under `"servers"` in the workspace's `.vscode/mcp.json` instead. VS Code uses `"servers"`, not `"mcpServers"`. + +### OpenCode + +In `~/.config/opencode/opencode.json` (or `opencode.jsonc`), under `"mcp"`: + +```json +"datum-mcp": { "type": "local", "command": ["datum-mcp"], "enabled": true }, +"datum-cloud-docs": { "type": "remote", "url": "https://www.datum.net/docs/mcp", "enabled": true } +``` + +### Windsurf + +In `~/.codeium/windsurf/mcp_config.json`, under `"mcpServers"`. Windsurf uses `serverUrl`, not `url`, for remote servers: + +```json +"datum-mcp": { "command": "datum-mcp", "args": [] }, +"datum-cloud-docs": { "serverUrl": "https://www.datum.net/docs/mcp" } +``` + +### Any other agent + +Add the two servers from the table above wherever the agent keeps its MCP config. Check the agent's own docs for the format. + +## 4. Tell the agent how to use Datum + +Add this line to your user-level instructions file, unless it is already there: `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex, `~/.config/opencode/AGENTS.md` for OpenCode, or your agent's equivalent. + +```text +For Datum Cloud, use the datum-mcp tools in a session and `datumctl` (with its plugins) from the shell. Run `datumctl api-resources` and `datumctl explain ` to learn the API instead of guessing field names. +``` + +## 5. Sign in + +`datumctl` and `datum-mcp` sign in separately and keep separate credentials in the system keyring. + +### datumctl + +Check first: + +```bash +datumctl whoami +``` + +If that shows a signed-in user, skip to choosing a project below. Otherwise the user has to sign in themselves: `datumctl login` opens a browser and then shows an organization and project picker, and the picker needs an interactive terminal. When run without one, it fails for anyone with more than one project and saves nothing. Ask the user to run: + +```bash +datumctl login +``` + +In Claude Code they can type `! datumctl login` in the prompt. On a machine with no browser (SSH, a container), use `datumctl login --no-browser`, which prints a URL and a code to approve from any device. Wait for the user to say they have finished, then run `datumctl whoami` again. + +If the user named an organization and project, make it the active context: + +```bash +datumctl ctx use / +``` + +Otherwise leave the one they chose in the picker. `datumctl ctx` lists every organization and project they can use. + +### datum-mcp + +`datum-mcp` signs in by opening a browser on its first tool call. It may not be loaded until the agent restarts (Claude Code: after `/reload-plugins`). If its tools are available now, call its `context` tool to sign in and check the active organization and project. If they are not, tell the user it will ask them to sign in the first time it is used. + +## 6. Check + +Run these and note the result of each: + +```bash +datumctl version +datumctl plugin list +datumctl whoami +datumctl ctx +command -v datum-mcp +``` + +Then check that the MCP servers are registered, with whatever the agent offers. For example: `claude mcp list` or `claude plugin list`, `codex mcp list`, or reading back the config file you edited. + +## 7. Tell the user + +Finish with a summary in this shape. Replace each value with what you actually found, and mark anything that failed or was skipped with `✗` and the reason: + +```text +Datum Cloud agent setup complete + +✓ datumctl +✓ Plugins +✓ datum-mcp , registered with +✓ Docs MCP https://www.datum.net/docs/mcp +✓ Skills datum-cloud/skills +✓ Signed in , context / + +⚡ Restart your agent (Claude Code: /reload-plugins) to load the MCP servers. +``` + +Then suggest a first thing to try, such as "List the DNS zones in my project" or "What's running in my project?" + +## Reference + +- datumctl: and +- datumctl plugin catalog: +- datum-mcp: +- Skills: +- Datum Docs MCP: +- Service accounts for CI and agents running without a person present: +- Agent home: diff --git a/app/lib/page-content.ts b/app/lib/page-content.ts index c61ab53..c23f580 100644 --- a/app/lib/page-content.ts +++ b/app/lib/page-content.ts @@ -350,6 +350,10 @@ export const SECTIONS: readonly SectionData[] = [ { kind: 'rows', rows: [ + { + label: 'Agent setup', + text: 'One prompt that sets up any coding agent for Datum Cloud: `datumctl` with every official plugin, the Datum MCP and Docs MCP servers, the Datum skills, and sign-in. Paste "Fetch and execute the appropriate instructions to set me up for Datum Cloud from https://agents.datum.net/setup/prompt.md" into your agent. [/setup](/setup)', + }, { label: 'llms.txt', text: 'A concise, standardized index of Datum pages and resources that makes the site instantly readable to any AI model or intelligent agent. [https://www.datum.net/llms.txt](https://www.datum.net/llms.txt)', @@ -364,11 +368,11 @@ export const SECTIONS: readonly SectionData[] = [ }, { label: 'Datum MCP', - text: 'An official, self-hosted MCP server, tightly integrated with Cursor. The `datumctl ai` tools also run as an MCP server for Claude Desktop or any MCP client.', + text: 'The official Datum MCP server, `datum-mcp`: tools for organizations, projects, networking, DNS, compute and more, for Claude Code, Cursor, Codex or any MCP client. It runs locally over stdio and signs in through your browser on first use. [https://github.com/datum-cloud/datum-mcp](https://github.com/datum-cloud/datum-mcp)', }, { label: 'Skills', - text: 'Pre-built, task-specific instructions that teach coding agents how to use Datum features: `ai-edge`, `client-traffic`, `dns`, `domains`, `httproute`, `metrics-export`. Drop a skill into your project context to help your agent know exactly what to do. [https://github.com/datum-cloud/skills](https://github.com/datum-cloud/skills)', + text: 'Instructions that teach coding agents to work with Datum Cloud: `sign-in`, `ci-service-account` and `datum-cloud-assistant`. In Claude Code they install as a plugin that also registers the Datum MCP and Docs MCP servers; other agents install them with `npx skills add datum-cloud/skills`. [https://github.com/datum-cloud/skills](https://github.com/datum-cloud/skills)', }, { label: 'CLI', diff --git a/app/routes/setup.tsx b/app/routes/setup.tsx new file mode 100644 index 0000000..130f9b3 --- /dev/null +++ b/app/routes/setup.tsx @@ -0,0 +1,61 @@ +import { Footer } from '@/components/layout/Footer'; +import { Header } from '@/components/layout/Header'; +import { PageContainer } from '@/components/layout/PageContainer'; +import { Markdown } from '@/components/ui/Markdown'; +import prompt from '@/content/setup/prompt.md?raw'; +import { buildMeta } from '@/lib/seo'; +import type { MetaFunction } from 'react-router'; + +const SETUP_PROMPT = + 'Fetch and execute the appropriate instructions to set me up for Datum Cloud from https://agents.datum.net/setup/prompt.md'; + +export const meta: MetaFunction = ({ matches }) => { + const parentMeta = matches.flatMap((match) => match.meta ?? []); + return [ + ...parentMeta, + ...buildMeta({ + title: 'Datum — Set up your agent', + description: + 'One prompt that sets up a coding agent for Datum Cloud: datumctl and its plugins, the Datum MCP and Docs MCP servers, Datum skills, and sign-in.', + path: '/setup', + type: 'article', + }), + ]; +}; + +export default function AgentSetup() { + return ( + <> +
+
+ + +
+

+ Paste this into Claude Code, Codex, Cursor, GitHub Copilot, OpenCode, Windsurf or any + other coding agent. It follows the instructions below to set itself up for Datum + Cloud. +

+ 
+              {SETUP_PROMPT}
+
+
+
+ {prompt} +
+ +
+