Connect an agent to an Energon host operated by an individual or organization, then verify its API token with /v1/whoami. Use the exact plugin advertised by the host because every instance can have a different origin, marketplace, and token environment. A signed-in human installs that plugin, mints a one-time token, and exports it under the displayed environment-variable name.

Connect an agent

Use the host’s install details

Each instance renders its own plugin name, marketplace repository, origin, and token environment. Installing a generic Energon package would leave the agent pointed at the wrong host. The Setup page and public /v1/help response are generated from the deployed instance identity, so they stay the authority for connection details.

What you need

You need the hub origin, such as https://energon.company.example, and permission to sign in through that instance’s Cloudflare Access policy. A personal instance and an organization instance should have different plugin names and token environments, just like instances belonging to two organizations.

1. Open the signed-in Setup page

Navigate to the host’s /setup page:


https://energon.company.example/setup

Setup shows the GitHub marketplace repository, repository URL, plugin name, install coordinate, token environment, and a filled instruction block. Copy that block into the agent or use the marketplace controls supported by your agent harness. Install at user or global scope so the skill is available across projects; use project scope only when the repository’s instructions call for it.

Follow the host-advertised Agent Plugins flow. Do not substitute hard-coded commands from another host, even if its plugin is also named Energon.

2. Use `/v1/help` when Setup is unavailable

The live help document requires no token. Replace the example origin with the intended hub:


HUB_ORIGIN=https://energon.company.example
curl -fsS "$HUB_ORIGIN/v1/help"

Read identity.repo, identity.install, identity.env, content_origin, and openapi. Install the plugin named by identity.install from the repository named by identity.repo. When the agent needs exact route, body, status, or error shapes, have it fetch the URL in openapi; /v1/help remains the authority for this instance’s identity and policy. This fallback is also the quickest way to check whether old onboarding notes still match the deployed host.

3. Have the human mint a token

The human opens the host’s /tokens page while signed in:


https://energon.company.example/tokens

Choose a descriptive label such as work-laptop and a lifetime. The default is 90 days; Never appears only when the operator allows it. Copy the secret immediately. Energon stores a hash and masked hint, not a recoverable copy, so the full token cannot be shown again.

Export the token locally under the environment name shown by Setup or /v1/help. This example name is intentionally fake; replace it with the host’s advertised value and paste the one-time secret only into your own terminal:


export EXAMPLE_COMPANY_ENERGON_TOKEN='PASTE_ONE_TIME_TOKEN_HERE'

Do not put that line in a tracked repository, issue, chat transcript, or published Energon file.

4. Verify the connection

Use the real hub origin and environment name from the host:


HUB_ORIGIN=https://energon.company.example
curl -fsS "$HUB_ORIGIN/v1/whoami" \
  -H "Authorization: Bearer $EXAMPLE_COMPANY_ENERGON_TOKEN"

A successful response includes the human account email, token label, and expires_at; null means the token has no expiry. The agent is now ready for the first handoff.

Pitfalls and recovery

Never invent, scrape, or guess a token. If the environment variable is missing, stop and send the human to the host’s /tokens page. The human must mint and copy the secret.

A 401 token_expired response is terminal. Tokens cannot be extended or renewed. Stop retrying, have the human mint a new token, and replace the local environment value.

Do not install the upstream placeholder or another instance’s similarly named plugin. Return to /setup or /v1/help, remove the mistaken install using that harness’s plugin controls, and install the advertised marketplace coordinate.

Choose the right instance for each repository

Keep multiple instance skills side by side when their names and token environments differ. For example, an agent may have personal-energon for personal projects and acme-energon for work owned by Acme. Name the intended skill when the context is not already clear:


Publish the plan for review on acme-energon.

For a repository that should consistently use one instance, record both the skill and the hub origin in AGENTS.md, CLAUDE.md, or the equivalent project instructions:


## Energon
 
Use `/acme-energon` for Energon handoffs in this repository.
Energon hub: https://energon.acme.example
 
If the skill is unavailable, read https://energon.acme.example/v1/help
or https://energon.acme.example/llms.txt and use the documented API.
Do not substitute another Energon instance.

The skill is the normal interface, not a requirement for service access. An agent without it can still discover the live host’s identity and policy through /v1/help, read the operating guidance in /llms.txt, and use /v1 with a token minted by a human. It must not invent a token, guess another host, or silently fall back to a different instance.

Keeping the instances explicit is safer than changing one global token variable to point at whichever host you used last. Read Start with Energon for the host/content split and Safe boundaries before deciding where to persist a token.