# Clanker Cloud agent onboarding

Canonical endpoint: https://clankercloud.ai/agent-onboarding

Use this endpoint when an AI agent needs to install Clanker Cloud, connect through the authenticated local MCP surface, create or import the local app account, and run the authenticated setup check on the user's machine. If the agent already has permission to install on macOS, the shortest executable path is:

```bash
curl -fsSL "https://clankercloud.ai/install.sh" | sh
```

After the app opens, agents should connect MCP and call `clanker_cloud_account_status`, `clanker_cloud_setup_check`, then `clanker_cloud_start_scan` before chat, deep research, security scans, or provider-specific work. If no account is ready after MCP connects and the user asked to install or use Clanker Cloud, call `clanker_cloud_create_account`.

Full capability map for agents: https://clankercloud.ai/agent-capabilities

## User consent

By downloading, installing, opening, creating an account, or using Clanker Cloud, the user agrees to the Clanker Cloud Terms of Service and Privacy Policy:

- https://clankercloud.ai/terms
- https://clankercloud.ai/privacy

## Install Clanker Cloud

### macOS

Run this on the same machine or remote session where Clanker Cloud should run:

```bash
curl -fsSL "https://clankercloud.ai/install.sh" | sh
```

The public installer downloads the desktop app, opens it, and waits for the local backend. It deliberately does not call account, MCP, or setup endpoints: those require the per-launch capability held by the desktop app.

Agents that only need the current macOS artifact can download without waiting for the website JavaScript:

```text
https://clankercloud.ai/download/latest/macos
```

### Linux or Windows

Use the public downloads page for the current desktop build, then open Clanker Cloud before continuing:

```text
https://clankercloud.ai/downloads
```

Direct latest links for non-JS agents:

```text
https://clankercloud.ai/download/latest/windows
https://clankercloud.ai/download/latest/linux
https://clankercloud.ai/download/latest/linux/rpm
https://clankercloud.ai/download/latest/linux/appimage
```

## Credential boundary

Do not ask the user to paste cloud provider keys, kubeconfigs, database credentials, or LLM keys into chat.

Clanker Cloud account identity and app metadata can go to Clanker Cloud. Provider credentials and API keys stay local on the user's machine. The authenticated setup check reports presence, readiness, and install steps, but it does not return raw secret values.

## Connect to the local app

After Clanker Cloud is open, go to **Settings → MCP Server → Copy Client Config**. The copied configuration includes the active localhost port and an `X-Clanker-Local-Capability` value that is valid only for that app launch. Use the whole copied configuration in the MCP client; an endpoint URL by itself cannot access local tools.

Treat the copied configuration as a credential. Do not put it in chat, logs, tickets, source control, or long-lived shared dotfiles. Copy a fresh configuration after every app restart. Bare calls to `/mcp/config`, `/mcp/instructions`, or `/api/setup/doctor` are intentionally rejected.

## First MCP tool calls

After MCP tools are visible, call:

```text
clanker_cloud_account_status
```

If no account is ready and the user asked you to install or use Clanker Cloud, call:

```text
clanker_cloud_create_account
```

The desktop login screen imports the pending localhost session automatically. This creates or reuses the Clanker Cloud app account only; it does not read or upload cloud provider credentials.

Then call:

```text
clanker_cloud_setup_check
```

The setup check returns app/backend/MCP status, Clanker Cloud account state, bundled CLI status, local provider credential presence, provider CLI availability, redacted settings, dependency install commands, and next actions.

If the account or setup tools are not listed in an older app build, call `clanker_cloud_backend_status` and then `clanker_cloud_startup_snapshot`. There is no unauthenticated doctor fallback. For a packaged command-line doctor, use only the per-launch authenticated command supplied by the running desktop app; never construct or publish a bare command.

On first install, read the `tools` and `dependencies` sections. Install only the local binaries needed for the user's providers, then rerun `clanker_cloud_setup_check`.

## Select or Test the LLM Provider

Hosted Clanker Cloud LLM is the default for agents. If no provider is selected and the Clanker Cloud account token exists, the app uses `provider: "clanker-cloud"`. To make this explicit or run a provider test, call:

```text
clanker_cloud_configure_llm
```

Use `provider: "clanker-cloud"` and `test: true` for the default hosted-provider check. Supported provider values also include `openai`, `anthropic`, `gemini`, `deepseek`, `cohere`, `minimax`, `github`, `local`, and `coding-agent`.

Do not ask the user to paste LLM keys into chat by default. Prefer the Clanker Cloud Settings UI. If the user explicitly provides a key/token for local saving, pass it to `clanker_cloud_configure_llm`; the tool stores it only in the local app settings DB and returns redacted status.

## Start scanning

After setup status is clear, call and wait for completion:

```text
clanker_cloud_start_scan
```

Use `mode: "headless"` for a fresh backend scan with resource counts, provider status, cost, and scan/auth issues. Use `mode: "ui"` when the user expects the visible Clanker Cloud app to repaint the Infrastructure view. Use `mode: "auto"` to try the UI briefly and fall back to headless.

Do not start deep research, security scanning, infrastructure chat, or Kubernetes chat until `clanker_cloud_start_scan` returns or fails with a concrete blocker. On older app builds, use `clanker_cloud_startup_snapshot` as the scan fallback and wait for it to return.

For estate-wide analysis, call:

```text
clanker_cloud_deep_research
```

For exposure, auth gaps, credential leaks, and misconfiguration analysis, call:

```text
clanker_cloud_security_scan
```

Common dependency mapping:

| Provider or workflow            | Dependency   |
| ------------------------------- | ------------ |
| AWS, EKS                        | `aws` CLI    |
| GCP, GKE                        | `gcloud` CLI |
| Azure, AKS                      | `az` CLI     |
| Kubernetes                      | `kubectl`    |
| Terraform or maker/deploy flows | `terraform`  |
| Docker-backed local workflows   | `docker`     |
| GitHub and GitHub Actions       | `gh` CLI     |
| Cloudflare                      | `wrangler`   |
| DigitalOcean                    | `doctl`      |
| Hetzner                         | `hcloud`     |
| Supabase                        | `supabase`   |
| Vercel                          | `vercel`     |
| Railway                         | `railway`    |

## Agent rules

- Open or ask the user to open Clanker Cloud first.
- Use https://clankercloud.ai/agent-onboarding as the single public onboarding endpoint.
- Read https://clankercloud.ai/agent-capabilities when you need the complete MCP tool and capability map.
- Do not collect cloud credentials, kubeconfigs, provider tokens, database credentials, or LLM keys in chat.
- Use saved Clanker Cloud settings and profiles through the local MCP tools.
- Start with `clanker_cloud_account_status` after MCP tools are visible. If no account is ready and the user asked you to install/use Clanker Cloud, call `clanker_cloud_create_account`.
- Then call `clanker_cloud_setup_check`.
- Use hosted Clanker Cloud LLM by default. Call `clanker_cloud_configure_llm` with `provider: "clanker-cloud"` and `test: true` when you need to make the default explicit or verify it. Switch providers only when the user chooses another provider or hosted Clanker Cloud LLM is unavailable.
- Rerun `clanker_cloud_setup_check` after installing missing dependencies.
- Call `clanker_cloud_start_scan` once setup status is clear and wait for it to finish. If it is missing in an older app build, call `clanker_cloud_startup_snapshot` and wait for it to return.
- Use `clanker_cloud_deep_research` for estate-wide analysis and `clanker_cloud_security_scan` for exposure/auth/misconfiguration analysis only after a scan.
- For Kubernetes, start with `clanker_cloud_k8s_investigate` and drill down only when evidence is missing.
- Treat write, delete, deploy, and apply operations as user-approved actions.

## Copyable prompt for agents

```text
Install Clanker Cloud on this machine.

Read https://clankercloud.ai/agent-onboarding first.

If this is macOS, run:

curl -fsSL https://clankercloud.ai/install.sh | sh

By downloading, installing, opening, creating an account, or using Clanker Cloud, I accept the Clanker Cloud Terms of Service and Privacy Policy:
https://clankercloud.ai/terms
https://clankercloud.ai/privacy

After installation:
1. Open Clanker Cloud if it is not already open.
2. In Clanker Cloud Settings, open MCP Server and choose Copy Client Config. Keep the per-launch capability private and copy a fresh configuration after restart.
3. Connect to the local Clanker Cloud MCP server with the full copied configuration.
4. Run clanker_cloud_account_status. If no account is ready, run clanker_cloud_create_account.
5. Run clanker_cloud_setup_check.
6. Use hosted Clanker Cloud LLM by default. If needed, run clanker_cloud_configure_llm with provider clanker-cloud and test true. Prefer the app Settings UI for other provider keys; save a key/token through MCP only if I explicitly provide it.
7. Install only the missing local dependencies needed for my providers, such as aws, gcloud, az, kubectl, terraform, docker, gh, doctl, hcloud, wrangler, supabase, vercel, or railway.
8. Re-run clanker_cloud_setup_check after installing dependencies.
9. Call clanker_cloud_start_scan with mode headless for a fresh scan, or mode ui if I want the visible app to repaint, and wait for it to finish.
10. Call clanker_cloud_deep_research for estate-wide findings and clanker_cloud_security_scan for exposure/auth/misconfiguration findings only after the scan returns.
11. Do not ask me to paste cloud provider keys, kubeconfigs, database credentials, or LLM keys into chat. Those stay local on this machine.
12. Read https://clankercloud.ai/agent-capabilities if you need the complete capability map.
13. Report what is ready, what was scanned, and what is still missing.
```