# Set up AetherCI with your coding agent

Give Codex, Claude Code, or another terminal-capable agent this prompt:

> Read https://aetherci.com/agent-setup.md and use the AetherCI setup skill to configure this repository as an AetherCI project. Discover the relevant CI and hosting tools, show me the configuration plan, reuse existing resources, and verify a real event. Ask me for missing choices and browser authorization. Never print or commit secrets.

The agent can create or reuse a project, connect integrations, apply project settings and resource filters, and register GitHub/Netlify webhooks. You handle browser signup/sign-in and grant access. Some providers require an additional provider-side subscription step. Setup reports those steps instead of claiming success prematurely.

## What to install

AetherCI uses a portable **Agent Skill plus a small Node.js helper**. No MCP server or global npm package is required. The skill teaches the workflow; the helper makes authenticated API calls. A skill by itself does not grant access to your account.

Use Node.js **20.19 or later**. Have your agent fetch these files from the official domain into a single skill directory, preserving relative paths:

| File | Download |
| --- | --- |
| `SKILL.md` | https://aetherci.com/agents/aetherci-setup/SKILL.md |
| `references/providers.md` | https://aetherci.com/agents/aetherci-setup/references/providers.md |
| `scripts/aetherci.mjs` | https://aetherci.com/agents/aetherci-setup/scripts/aetherci.mjs |
| `scripts/browser-auth.mjs` | https://aetherci.com/agents/aetherci-setup/scripts/browser-auth.mjs |

Review the downloaded files before executing them. Never pipe a remote response straight into a shell. Do not install an unofficial package named after AetherCI.

- **Codex:** install under `.agents/skills/aetherci-setup/` in your repository or `~/.agents/skills/aetherci-setup/` for your user. Invoke `$aetherci-setup` or ask to set up AetherCI.
- **Claude Code:** install under `.claude/skills/aetherci-setup/` or `~/.claude/skills/aetherci-setup/`. Invoke `/aetherci-setup`.
- **Other coding agents:** read the skill directly and run its Node helper. A shell, network access, and a browser on the same computer are required for the normal approval flow.

Restart the agent if it does not discover a newly installed skill. A remote SSH/container agent cannot receive a callback on your laptop's loopback interface without an appropriate local setup; run the helper on the same computer as the browser. Do not expose its listener on your network.

## Prepare a project manifest

The agent should inspect the repository and resolve targets from available evidence before asking about missing choices. Do not guess which production repository, Netlify site, branch, or notification channel you mean.

Multiple integrations for one provider are intentional: they can separate organizations, accounts, environments, supported instances, and credential scopes. The agent should honor existing project links, check exact-resource access and required capabilities through supported read-only tools where available, and reuse a connection by ID when the evidence identifies it. Ask only when a meaningful choice remains or access cannot be verified. Do not select solely by a name such as “Production,” consolidate connections, or broaden permissions to avoid a question. The current helper matches IDs/names; it does not automatically discover repository access. See [Choosing an integration](https://aetherci.com/agents/aetherci-setup/references/providers.md#choosing-an-integration).

Create `aetherci.setup.json`:

```json
{
  "version": 1,
  "project": {
    "name": "My service",
    "description": "CI and deployment monitoring for my service",
    "tags": ["service"],
    "settings": {
      "predictions_enabled": false,
      "event_retention_days": 5
    }
  },
  "integrations": [
    {
      "name": "My service GitHub",
      "type": "github",
      "config": { "token": { "env": "AETHERCI_GITHUB_TOKEN" } },
      "config_overrides": {
        "repository": "YOUR_ORG/YOUR_REPO",
        "workflows": [],
        "branches": ["main"]
      },
      "webhook": "auto"
    }
  ]
}
```

Use environment variables/your local secret manager for credential values. **Do not put tokens in the manifest, chat, command arguments, or Git.** The manifest itself can be committed after reviewing its nonsensitive resource names and settings.

For GitHub, choose a repository-scoped fine-grained token with Webhooks write for registration and Actions/Contents/Metadata read for investigations. PR/issue creation requires additional write permissions only if you intend to use those features. Organization approval may also be necessary. The token is stored encrypted by AetherCI so it can retrieve context later; it is not used only once during installation. An agent must not silently upload an existing broad CLI token.

For other providers and all supported fields, read the [provider reference](https://aetherci.com/agents/aetherci-setup/references/providers.md). Use `webhook: "none"` for context/notification-only integrations, or `manual` when you will complete incoming subscriptions through provider tools/UI.

## Preview and apply

Using a repository-local Codex installation:

```sh
node .agents/skills/aetherci-setup/scripts/aetherci.mjs plan --file aetherci.setup.json
node .agents/skills/aetherci-setup/scripts/aetherci.mjs apply --file aetherci.setup.json
```

For Claude Code, use the same commands with `.claude/skills` instead of `.agents/skills`.

`plan` is offline and makes no changes. `apply` prints an AetherCI approval link valid for five minutes. Leave the command running, open the link in your browser, sign in or create an account/workspace if needed, and approve. Login and workspace creation open in another tab; return to the approval tab and refresh the session when finished. If signup takes longer, restart the command for a fresh link.

The approval page displays the account, organization, and token expiry. It shares **your current account's API permissions**, not setup-only access. The CLI can access project and integration data available to you. It receives only the short-lived access token, never your refresh token, and stores it only in process memory. Closing the process discards its copy; it does not revoke your browser session.

Your browser may ask to permit access to a local application. The callback is an ephemeral `http://127.0.0.1:<port>/callback` listener with a one-use random state. Only approve a setup command you started. If browser policy blocks local access, setup will stop; do not disable browser security or expose the listener publicly. Advanced users may supply an existing **user access token** as `AETHERCI_ACCESS_TOKEN` through a protected environment—not a service-role key or a chat message.

## Resume and verify

The CLI reuses a single exact project name and matching integration type/name (or explicit `id`). If multiple matches exist, add the intended ID. It refuses to overwrite conflicting shared integration credentials. It preserves unrelated project links and omitted settings. Writes are never automatically retried; rerun the same manifest after inspecting a partial failure. Do not run concurrent setup for one project: local locking does not coordinate other computers, and the legacy creation endpoints do not provide transactional idempotency.

Setup output includes the project URL, registration results, and observed event status. `configuration: applied` is **not** proof that events are arriving. A GitHub ping is not a deployment event. Verify a real authorized workflow/deploy delivery and correlate its provider/resource and timestamp with the setup run:

```sh
node .agents/skills/aetherci-setup/scripts/aetherci.mjs status --project PROJECT_UUID
```

Do not rerun a production deployment or spend AI-analysis quota just to complete a checklist without authorization. Existing historical events do not prove the new webhook works. Report effective workflow/branch coverage and each selected provider as verified, configured but awaiting verification, or blocked. If user action is required, identify the connection, give a verified page link or navigation path and exact action, then resume registration and verification after it is completed. Errors on unused connections are not project blockers. Follow [Recovery and handover](https://aetherci.com/agents/aetherci-setup/references/providers.md#recovery-and-handover); do not leave the user with only “check credentials.”

## Troubleshooting

- **404 or HTML from `/api/agent-setup/context`:** the matching agent-setup backend has not been deployed, or routing is incorrect. Do not fall back to direct database writes.
- **401:** identify which request failed. For an expired AetherCI session, sign in again and restart the command; no automatic refresh token is retained. For a provider request, diagnose the selected provider connection and guide the user through any required authentication repair. Signing in to AetherCI again does not repair a rejected provider credential.
- **403/402:** inspect account permissions, provider permissions, or AetherCI plan quota. Do not bypass quota checks through Supabase.
- **Conflicting integration configuration:** use the current credentials, make a reviewed change in the app, or create a clearly separate integration. Do not rotate a shared webhook secret blindly.
- **Manual registration required:** finish the provider's signed/authenticated webhook configuration through its official tools or dashboard. The AetherCI side may already be saved.
- **Stale lock:** remove `.aetherci-setup.lock` only after confirming no setup command is running. It contains no credentials.
- **Local development:** explicitly pass both `--app-url http://localhost:5173` and `--api-url http://localhost:3000`. Use `webhook: "manual"`; external providers cannot deliver to ordinary localhost. Production and local origins cannot be mixed.

## Why a skill instead of MCP?

For terminal agents, the skill plus CLI gives a portable workflow and inspectable commands without a server to configure. MCP is useful when an assistant needs remote tools without shell access; it could later expose the same AetherCI APIs. Neither mechanism replaces authentication or provider permissions.

References: [Codex skills](https://developers.openai.com/codex/skills), [Claude Code skills](https://code.claude.com/docs/en/skills), [Agent Skills standard](https://agentskills.io/specification), [MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture), [Netlify agent setup](https://docs.netlify.com/build/build-with-ai/agent-setup-guides/agent-setup-overview/).