Connect an agent

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

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

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

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).
2. Add the instance MCP server and authenticate. Prefer OAuth on a desktop:

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:

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.

# @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.