Use with your coding agent

Guide version: 2026-10-23.1. Last reviewed: 2026-10-23. Canonical agent-readable guide: openpond.ai/agent-setup.md.

Use OpenPond from Codex, Claude Code, Cursor, or another agent with terminal access and Agent Skills support. Skills teach workflows; the OpenPond CLI and SDK perform operations. Desktop already includes all five customer skills enabled by default, so setup inside Desktop needs no extra skill installation.

Give your coding agent this prompt:

Read https://openpond.ai/agent-setup.md and set up OpenPond for this coding agent. Reuse my existing OpenPond home and account, install only missing capabilities for this client, and verify access with read-only commands. Keep credentials private and report any incomplete step. Do not start workloads or change cloud resources.

Inspect before installing

Identify the current client and whether the user wants project or user scope. Inspect that client's existing skills before making changes. Do not configure every detected client or replace a customized skill without reviewing the difference.

Check the existing CLI with openpond version and openpond --help. If missing, install the official npm package with npm install -g openpond; the package currently requires Node.js >=24.18.0 <25. Use the installed package's engine requirement if it changes. Installing skills and installing the CLI are separate steps.

Select the OpenPond home before checking credentials. Stable Desktop normally uses ~/.openpond, nightly uses ~/.openpond-nightly, and development Desktop normally uses ~/.openpond/openpond-app-dev. Reuse an explicit home override when present. Pass --home on each CLI operation using that account; do not diagnose a missing Desktop account from a different home.

For an existing development Desktop:

For a standard installation, use the selected home instead. profiles list reports account handles, origins, the active account, and credential-presence booleans. It does not print secret values or prove a successful authenticated request. A session credential and an API key are different capabilities: if a session-only account cannot use a particular public API, report that boundary before requesting API-key setup. Never read credential-store files, copy session cookies, or put keys into prompts, source, or shell history.

Local Profile inspection and source authoring remain available without cloud authentication. Do not force cloud login for local-only work.

Install the maintained skills

The OpenPond repository is the maintained skill source, licensed under MIT. Desktop and the npm CLI customer pack use these same files. Each npm pack includes dist/skills/manifest.json with the package version and SHA-256 hashes of the complete customer sources.

The standard Skills CLI handles discovery, client links, updates, and removal. Commands below were checked against skills@1.7.4; inspect its current help before using a different version. Discovery does not install anything:

Install for the intended client only. This example uses Codex and project scope:

Replace codex with claude-code or cursor for those clients. Keep project scope unless the user requests skills across projects; add --global for user scope. Review the installer plan and any overwrite prompts. The developer-only openpond-desktop-harness skill is excluded from this selection. Do not use --all or --skill '*' for customer setup.

For reproducible setup, replace openpond/openpond with a GitHub tree URL using a verified release tag or full commit, such as https://github.com/openpond/openpond/tree/<verified-ref>/apps/cli/skills. Record that ref alongside the CLI version. Do not invent a release tag or claim that a source revision has been published to npm. A release's unpacked dist/skills directory is also a supported local source for skills add, so a pinned npm artifact can supply the pack without a second source copy. For local sources, update by rerunning skills add from the reviewed replacement pack; the installer does not fetch updates for a local path.

Open a new agent session if its skill catalog does not refresh. Confirm the selected names appear in the client and that the agent can load openpond-cli and its references. A successful file copy alone does not verify client discovery.

Reuse or establish authentication

If the selected account already has the credential required for the requested API, reuse it. If an API key is needed, have the user provide it through a private terminal or the execution environment. The supported interactive command is:

Replace the example home with the selected installation. OPENPOND_API_KEY is also supported for an execution environment; never ask the user to paste its value into chat. Keep the account's web/API origins together, and preserve staging versus production. If a command fails, report its status and corrective action without repeating credential-bearing output.

Verify with harmless reads

Perform only the checks relevant to the user's requested surface. Start by inspecting installed help for the exact family. These reads do not start inference, evaluation, training, serving, or deployment:

Confirm account identity from the returned account, and use the workspace explicitly selected by the user or supplied by the Console. If a workspace ID is still unknown, ask which workspace to use instead of assuming one. Verify access with a bounded workspace inventory read, replacing the placeholder with that exact ID:

Use the selected account's apiBaseUrl from profiles list for <selected-account-api-origin>; the dataset command requires this explicit flag. An empty inventory is a successful read. A permission failure is not a missing installation. For local app-backed datasets, inspect openpond datasets --help and use --local with the selected running app rather than silently switching to the cloud. Setup does not authorize imports, uploads, evaluation runs, model requests, training, or activation.

Report four separate results: skills discovered by the client; CLI version and selected home; authenticated account and verified workspace (or local-only); and tool connection, if one was requested. Include the failing step and next action for partial setup. Never label setup complete from an install receipt alone.

Update and remove

Inspect the installed source and scope before an update. Preserve intentional local edits before accepting an overwrite. For the project-scoped operational skill:

Name only the skills being updated or removed. For the complete customer pack, pass the same five names used during installation. Use --global instead of project scope for a user installation and the intended --agent when listing. Named-skill removal cleans the shared skill and its client links in that scope; review the removal plan if several clients share it. In skills@1.7.4, limiting removal to --agent codex can leave the shared skill discoverable, so verify removal with skills list and the client catalog instead of relying on its success message. To advance a pinned GitHub ref, rerun skills add with the reviewed new tree URL and explicit names, then repeat discovery and harmless-read verification. Removing agent skills does not remove the CLI, credentials, Profiles, datasets, or cloud resources. npm uninstall -g openpond removes a globally installed CLI when requested.

MCP connection status

CLI onboarding works independently of MCP. The general CLI/API MCP package is implemented. Its production connection is https://api.openpond.ai/mcp/app, served directly by the API backend; browser sign-in and consent use the website. Production availability is release-gated and is not yet qualified by this guide. Do not invent a connection URL or configure the existing specialized sandbox MCP as a substitute. Connect the general MCP only through its published package and authentication instructions once the relevant release and endpoint have been verified. Skills installation, MCP connection, authentication, and a successful read each need their own evidence.

For CLI commands and configuration, use the maintained CLI reference and OpenPond home documentation. Client skill behavior is documented by Codex, Claude Code, and Cursor.