diff --git a/app/content/setup/prompt.md b/app/content/setup/prompt.md new file mode 100644 index 0000000..c015921 --- /dev/null +++ b/app/content/setup/prompt.md @@ -0,0 +1,323 @@ +# 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 the plugins the user chose +- `datum-mcp`, the Datum MCP server, connected to this agent +- the hosted Datum Docs MCP server, connected to this agent +- the Datum skills for the products the user chose +- if the user uses Claude Code, Datum's [Claude Code plugin marketplace](https://github.com/datum-cloud/claude-code-plugins) and plugins, whichever agent you are +- a signed-in `datumctl`, pointed at the right organization and project + +The user doesn't need anything installed beforehand. You download everything from GitHub with `curl` and `tar` (macOS, Linux) or PowerShell (Windows), into a folder in the user's home directory. Never use `sudo` or ask for admin rights. + +Run every command below yourself. Do not ask the user to run them. The user answers one set of questions in step 0 and approves the sign-in in their browser in step 5; nothing else. 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. + +## 0. Ask the user first + +Ask these together, in one message, and wait for the answer. If you have a tool for asking the user structured questions, use it; otherwise ask in the chat. + +> I'll install datumctl (the Datum CLI) and the Datum MCP server, and connect them to this agent. A few choices first: +> +> 1. **datumctl plugins** add commands for DNS, compute, load balancers, networking, billing and more, and I'll add my skills for the same products. Install all of them (recommended), pick which ones, or none? +> 2. **Claude Code:** do you also use Claude Code? If so, I'll add Datum's plugin marketplace to it, with the plugins for the products you chose. +> 3. **Agent instructions:** add one line to your global instructions file (``) so I use datumctl and the Datum MCP server for Datum work in every project? Yes or no? + +If you are Claude Code, leave out question 2: the answer is yes. + +If the user says to go ahead with the defaults, install all plugins, add the line, and set up Claude Code only if you are Claude Code. + +## 1. Install datumctl and datum-mcp + +Run this every time, even if they are already installed: it replaces an existing copy in the same folder with the latest release, and steps 2 and 5 need a recent `datumctl`. + +### macOS and Linux + +```bash +BIN="$HOME/.local/bin" +mkdir -p "$BIN" +case "$(uname -s)" in + Darwin) os=Darwin; mos=darwin ;; + Linux) os=Linux; mos=linux ;; + *) echo "Unsupported OS: $(uname -s)" >&2; exit 1 ;; +esac +case "$(uname -m)" in + x86_64 | amd64) arch=x86_64; march=amd64 ;; + arm64 | aarch64) arch=arm64; march=arm64 ;; + *) echo "Unsupported CPU: $(uname -m)" >&2; exit 1 ;; +esac +curl -fsSL "https://github.com/datum-cloud/datumctl/releases/latest/download/datumctl_${os}_${arch}.tar.gz" \ + | tar -xz -C "$BIN" datumctl +curl -fsSL -o "$BIN/datum-mcp" \ + "https://github.com/datum-cloud/datum-mcp/releases/latest/download/datum-mcp_${mos}_${march}" +chmod +x "$BIN/datumctl" "$BIN/datum-mcp" +``` + +The binaries are now at `~/.local/bin/datumctl` and `~/.local/bin/datum-mcp`. + +### Windows (PowerShell) + +```powershell +$bin = Join-Path $env:LOCALAPPDATA 'Programs\Datum' +New-Item -ItemType Directory -Force -Path $bin | Out-Null +$arm = $env:PROCESSOR_ARCHITECTURE -eq 'ARM64' +$arch = if ($arm) { 'arm64' } else { 'x86_64' } +$march = if ($arm) { 'arm64' } else { 'amd64' } +$zip = Join-Path $env:TEMP 'datumctl.zip' +$unzipped = Join-Path $env:TEMP 'datumctl' +Invoke-WebRequest "https://github.com/datum-cloud/datumctl/releases/latest/download/datumctl_Windows_$arch.zip" -OutFile $zip +Expand-Archive $zip -DestinationPath $unzipped -Force +Copy-Item (Join-Path $unzipped 'datumctl.exe') $bin -Force +Invoke-WebRequest "https://github.com/datum-cloud/datum-mcp/releases/latest/download/datum-mcp_windows_$march.exe" -OutFile (Join-Path $bin 'datum-mcp.exe') +``` + +The binaries are now in `%LOCALAPPDATA%\Programs\Datum`. + +### Put the folder on PATH + +Check whether the folder is already on the user's `PATH`. If it isn't, add it, so the user and their tools can run `datumctl` and `datum-mcp` by name: + +- **macOS and Linux:** append `export PATH="$HOME/.local/bin:$PATH"` to the startup file of the user's shell (`~/.zshrc` for zsh, `~/.bashrc` for bash, `~/.config/fish/config.fish` with `fish_add_path ~/.local/bin` for fish), unless a line like it is already there. +- **Windows:** `[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ";$bin", 'User')`, unless the folder is already in the user `Path`. + +Your current shell won't see the change. For the rest of this guide, run `datumctl` by its full path (`~/.local/bin/datumctl`, or `$bin\datumctl.exe` on Windows) wherever it says `datumctl`. + +If `command -v datumctl` (or `Get-Command datumctl`) finds a copy somewhere else first, an older install is shadowing this one. Tell the user, and keep using the full path. + +## 2. Install datumctl plugins + +Do what the user chose in step 0. + +**All:** install every plugin in Datum's official `datum` catalog: + +```bash +datumctl plugin install --all-available +``` + +It installs what is missing, upgrades what is behind, and leaves alone any plugin of the same name the user installed from somewhere else. It only uses the official catalog, so it needs no confirmation. Do not add `--index` or `--yes`. + +**Pick:** list the plugins, show the user each one's name and description, and ask which they want: + +```bash +datumctl plugin search --index datum +``` + +Then install each one they choose with `datumctl plugin install `. + +**None:** skip this step. + +## 3. Connect this agent + +Follow the section for the agent you are. If you are not Claude Code but the user said in step 0 that they use it, also follow the Claude Code section, so both agents are set up. + +Each agent gets two MCP servers: + +| Name | Kind | Value | +| ------------------ | ------------- | ------------------------------------ | +| `datum-mcp` | local (stdio) | the full path to `datum-mcp` | +| `datum-cloud-docs` | remote (HTTP) | URL `https://www.datum.net/docs/mcp` | + +Use the full path to `datum-mcp` from step 1, written out (for example `/Users/alex/.local/bin/datum-mcp` or `C:\Users\alex\AppData\Local\Programs\Datum\datum-mcp.exe`). Config files don't expand `~` or `$HOME`, and editors started from the Dock or Start menu don't see the shell's `PATH`. + +If an entry with the same name already exists, update it instead of adding a duplicate. Keep every other setting in the file. + +The skills come in groups, one per product. Install the groups that match the user's answer in step 0: + +| Install when | Claude Code plugin | Skills repository (other agents) | +| ----------------------------- | ------------------ | --------------------------------------- | +| always | `datum-cloud` | `datum-cloud/skills` | +| they chose `compute` | `datum-compute` | `datum-cloud/compute` | +| they chose `dns` | `datum-dns` | `datum-cloud/dns-operator` | +| they chose `alb` or `network` | `datum-networking` | `datum-cloud/network-services-operator` | +| they chose `telemetry` | `milo-observe` | `milo-os/telemetry` | + +"All" means every row. The other datumctl plugins have no skills of their own. Leave out `milo-activity` (`milo-os/activity`) even though the marketplace lists it: it needs the separate `activity` MCP server and a kubeconfig, which this setup doesn't provide. + +### Claude Code + +Do this if you are Claude Code, or if the user said in step 0 that they use it. It needs the `claude` command: if `command -v claude` (or `Get-Command claude`) finds nothing, skip this section, tell the user, and give them the commands below to run once Claude Code is installed. + +Add Datum's plugin marketplace, then install `datum-cloud` first and each other plugin from the table after it. Do not use `claude mcp add` or `npx skills` for Claude Code: `datum-cloud` registers both MCP servers, and the plugins bring the skills. + +```bash +claude plugin marketplace add datum-cloud/claude-code-plugins +claude plugin marketplace update datum-claude-code-plugins +claude plugin install datum-cloud@datum-claude-code-plugins --scope user +claude plugin install @datum-claude-code-plugins --scope user # once per row that applies +``` + +- Install at user scope, as above. A project-scoped install only loads in the folder it was installed from, and silently stops the plugin loading anywhere else. +- If the marketplace is already added, `add` says so; carry on. `update` makes sure you install the latest versions. +- If `claude plugin list` shows `datum-cloud@datum-cloud`, from the older `datum-cloud/skills` marketplace, remove it so the MCP servers aren't registered twice: `claude plugin uninstall datum-cloud@datum-cloud`. + +Claude Code doesn't update third-party marketplaces unless asked to, so turn auto-update on for this one. `claude plugin marketplace add` writes this entry under `"extraKnownMarketplaces"` in `~/.claude/settings.json`. Add `"autoUpdate": true` to it, keeping every other setting in the file: + +```json +"datum-claude-code-plugins": { + "source": { "source": "github", "repo": "datum-cloud/claude-code-plugins" }, + "autoUpdate": true +} +``` + +If the entry isn't there (an older Claude Code, or a marketplace added from inside a session), add the whole entry. Don't edit `~/.claude/plugins/known_marketplaces.json`: Claude Code keeps its own state there. + +`datum-cloud` starts `datum-mcp` by name, so it relies on the `PATH` change from step 1. Tell the user to run `/reload-plugins` in Claude Code, or to restart it if you changed `PATH`. You cannot do either yourself. + +### Every other agent: install the skills + +Do this for the agent you are, if you are not Claude Code. + +If `npx` is available, run this once for each repository in the table that applies: + +```bash +npx -y skills add --skill '*' --yes --global +``` + +If it isn't, use Datum's skill index at . For each skill whose `plugin` is one you are installing, download its `url` to `//SKILL.md` (for example `~/.codex/skills//SKILL.md` for Codex; check your agent's docs for others), and check the file's SHA-256 against its `digest` (`shasum -a 256` on macOS, `sha256sum` on Linux). Skip any file that doesn't match. + +Then register the MCP servers in the agent's config, as below. + +### Codex + +```bash +codex mcp add datum-mcp -- "$HOME/.local/bin/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": "", "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\":\"$HOME/.local/bin/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": [""], "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": "", "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. Add the agent instructions line + +Only if the user said yes in step 0. 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. If you set up Claude Code as well as yourself, add it to `~/.claude/CLAUDE.md` too. + +```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 and the user named an organization and project, switch to it and go on to datum-mcp: + +```bash +datumctl ctx use / +``` + +Otherwise, sign in. Tell the user a browser window is about to open for them to sign in to Datum Cloud, then run the login yourself. If they named an organization and project: + +```bash +datumctl login --project / +``` + +If they didn't: + +```bash +datumctl login +``` + +- The command waits until the user finishes in the browser, which can take a few minutes. If your shell tool has a time limit, run it in the background and wait for it to exit rather than cutting it off. +- Without `--project`, login picks the context itself only when the user has a single one. Otherwise it signs in and leaves the context unset. Then run `datumctl ctx`, ask the user which project to use, and run `datumctl ctx use /`. +- On a machine with no browser (SSH, a container, a remote box), add `--no-browser`. It prints a URL and a short code instead: run it in the background, read its output, give the user the URL and code to approve on any device, and wait for it to exit. + +Run `datumctl whoami` afterwards to check the account and context. + +### 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 --client +datumctl plugin list +datumctl whoami +datumctl ctx +``` + +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 , in +✓ Plugins +✓ datum-mcp , registered with +✓ Docs MCP https://www.datum.net/docs/mcp +✓ Skills +✓ Claude Code +✓ Instructions +✓ PATH +✓ Signed in , context / + +⚡ Restart your agent (Claude Code: /reload-plugins, or a restart if PATH changed) 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: +- Plugin marketplace: +- Skill index: +- 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 498b304..662cddf 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` and the plugins you choose, the Datum MCP and Docs MCP servers, the matching Datum skills, and sign-in. Nothing needs to be installed first. 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,7 +368,7 @@ 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', 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} +
+ +
+