# Connect an agent

An agent needs two things: the **skill**, which teaches it how to work with Acahti, and a **connection** to your instance.

```text
Install https://acahti.dev/skill.md
```

| Your agent | Connect with |
|---|---|
| Claude Code, Codex, or another MCP client | [MCP](mcp.md) at `<instance>/mcp`, using OAuth or a personal Access Token. No CLI. |
| Cursor or Codex, all in one install | The [editor plugin](plugin.md), which bundles the skill and MCP |
| A shell agent, script, or pipeline job | The [CLI](cli.md), with a host and an access token |

MCP and the CLI share one catalog. IDE agents keep MCP; shells keep the CLI. Details on installing the skill: [Agent skills](skills.md).

## Product and instances

This site is the product: the docs, the agent skill and the install guide. Each
team runs its own **instance**, such as `https://acahti.example.com`, which
serves the web app, MCP at `/mcp`, the REST API at `/acahti/v1`, Git over HTTPS
and the package registries. An agent installs the skill once and connects to
whichever instance it works on; everything specific to the instance (URL, org,
Git identity, admin and creation rights, installed plugins) comes from the
instance's `whoami`.

## Codex first use

1. Install the skill ([Agent skills](skills.md)).
2. Add the instance MCP server and authenticate. Prefer OAuth on a desktop:

```bash
codex mcp add acahti --url https://acahti.example.com/mcp
codex mcp login acahti
```

Or a personal Access Token from the avatar menu → Access tokens, via an environment variable:

```bash
export ACAHTI_TOKEN=…
codex mcp add acahti --url https://acahti.example.com/mcp --bearer-token-env-var ACAHTI_TOKEN
```

3. Ask the agent to call `whoami` and `inbox`. Skill install alone is not connection success. Do not install the CLI for Codex.

Reuse an existing connection rather than adding a duplicate.

## Benchyard first use

Install the skill, then ask: **连接 Acahti 并检查我的身份和待办**. The agent checks existing configuration and guides only the missing steps. Installation alone cannot run onboarding; the first invocation starts it.

1. Open your instance's avatar menu → **Access tokens** and create a personal token.
2. In Benchyard Secrets, set **ACAHTI_ROOT_URL** to the instance URL and **ACAHTI_TOKEN** to the token. Bind the secret to that instance's host. Each member uses their own token.
3. Make the variables available to the current task. The agent uses the CLI (installing from GitHub Packages only if it is missing) and verifies identity and inbox. No localhost callback is involved.

```bash
# @acahti-ai/acahti is private on GitHub Packages, not registry.npmjs.org
echo '@acahti-ai:registry=https://npm.pkg.github.com' >> ~/.npmrc
# authenticate with a GitHub PAT that has read:packages for acahti-ai
npm install -g @acahti-ai/acahti
acahti whoami
acahti inbox
acahti mcp tools
acahti mcp call whoami
```

Never paste the token into the conversation. Benchyard's host-bound secret placeholders are used directly in requests, not copied to local credential files.

## Git identity

Commits bound for Acahti use the identity the instance returns: `whoami.git_name` and `whoami.git_email`, applied with `whoami.setup_local` (local Git config only). Commits bound for other hosts keep their own identity. The skill has the full procedure, including merges, rebases, and repositories with several remotes.

## Rules every agent follows

- Never paste tokens into chat.
- Never `git config --global`.
- Clone over HTTPS from `<instance>/<org>/<repo>.git`.
- Merge only through `pr_merge`, which requires a green pipeline.