Skip to Content
GuideQuick Start
View .md

Quick Start

Prerequisites

  • Node.js 18+ (uses built-in crypto, fetch, fs — zero npm dependencies)
  • git 2.34+ (SSH commit signing support — only needed for agent-id-git)
  • Alien App with a verified AlienID
  • Provider address — an Alien provider address registered in the Developer Portal  (optional)

Claude Code

1. Add the marketplace and install the plugins

/plugin marketplace add alien-id/agent-id

Then install the plugins you need. agent-id-core is required by the other three; install only what you need:

/plugin install agent-id-core@alien-agent-id
/plugin install agent-id-git@alien-agent-id      # for signed commits
/plugin install agent-id-vault@alien-agent-id    # for credential storage
/plugin install agent-id-auth@alien-agent-id     # for DPoP service calls
/reload-plugins

If /reload-plugins does not pick up the new plugins on the first run, restarting Claude Code usually helps.

2. Bootstrap your Agent ID

/agent-id-core

Follow the instructions — the agent will generate a keypair, show a QR code, and wait for you to approve in the Alien App. Once done, your Agent ID is created and bound to your verified human owner.

3. Configure git signing

/agent-id-git

The plugin writes the SSH key files and prints the public key. Add it to your GitHub account:

GitHub → Settings → SSH and GPG keys → New SSH key → Key type: Signing Key. Commits will then show a “Verified” badge.

4. Use the skill to commit and push

You can pass arguments to the skill for common operations:

/agent-id-git stage, commit and push all files in the repo, follow the previous commits naming convention

Other Agents / CI

Any agent with shell access can drive the plugin CLIs directly. Requirements: Node.js 18+, git 2.34+, and permission to run node plugins/agent-id-<X>/bin/cli.mjs ... commands. Point the agent at plugins/agent-id-core/skills/agent-id-core/SKILL.md and have it follow the bootstrap steps.

CI/CD

# GitHub Actions example
- name: Bootstrap agent identity
  env:
    ALIEN_PROVIDER_ADDRESS: ${{ secrets.ALIEN_PROVIDER_ADDRESS }}
  run: node plugins/agent-id-core/bin/cli.mjs bootstrap

The bootstrap blocks (up to 5 minutes) waiting for QR approval in the Alien App. For attended CI, the deep link is printed to the log. For unattended CI, pre-bootstrap on the runner and persist ~/.agent-id/ across runs.

Manual Bootstrap

If you prefer to run the commands yourself, the one-shot bootstrap runs init + auth + bind:

node plugins/agent-id-core/bin/cli.mjs bootstrap

This generates the keypair, starts OIDC auth with Alien SSO, prints a deep link, waits for human approval, and persists the DPoP-bound owner session — all in one step. Git signing is not part of bootstrap; run agent-id-git setup separately afterwards.

If "alreadyBootstrapped": true appears in the output, the agent is already set up.

Provider Address Resolution

Bootstrap reads the provider address from (in order):

  1. --provider-address <addr> flag
  2. ALIEN_PROVIDER_ADDRESS environment variable
  3. default-provider.txt file next to the CLI

Step-by-Step

The single-call bootstrap blocks during the polling window. In environments where you need to surface the QR code to the user before polling starts, run the steps individually:

# Step 1: Generate the keypair
node plugins/agent-id-core/bin/cli.mjs init
 
# Step 2: Start OIDC auth (emits deep link + QR code text)
node plugins/agent-id-core/bin/cli.mjs auth --provider-address <PROVIDER_ADDRESS>
 
# Step 3: Poll for human approval (blocks up to 5 min)
node plugins/agent-id-core/bin/cli.mjs bind --timeout-sec 300
 
# Step 4: Configure git signing
node plugins/agent-id-git/bin/cli.mjs setup

setup derives the signer email automatically from the agent’s JWK thumbprint — there is no --email flag.

What a Signed Commit Looks Like

✓ Verified

feat: implement auth flow

Agent-ID-JKT: wEf6o2ux8sBAUG4oQYhP284gfpZwUJMTxXDPH5XxthY
Agent-ID-Owner: 00000003010000000000539c741e0df8
Co-Authored-By: Alien Agent <alienagentid@eti.co>

Anyone can trace: this code → this agent (Agent-ID-JKT thumbprint) → this human (Agent-ID-Owner SSO sub) → verified AlienID holder. Each commit also attaches a v3 bundle { version: 3, id_token, agent_jwk } as a git note so the chain can be verified without the agent’s local state.

Verify It Works

# Check identity / session state (agent-id-core)
node plugins/agent-id-core/bin/cli.mjs status
 
# Make a signed commit and push (agent-id-git)
node plugins/agent-id-git/bin/cli.mjs commit --message "feat: first signed commit" --push
 
# Verify a commit's provenance chain (agent-id-git)
node plugins/agent-id-git/bin/cli.mjs verify --commit HEAD

status returns the current identity state, e.g.:

{
  "ok": true,
  "initialized": true,
  "bound": true,
  "dpopBound": true,
  "jkt": "wEf6o2ux8sBAUG4oQYhP284gfpZwUJMTxXDPH5XxthY",
  "ownerSub": "00000003010000000000539c741e0df8",
  "providerAddress": "<your-provider-address>",
  "issuer": "https://sso.alien-api.com",
  "stateDir": "/home/agent/.agent-id"
}

dpopBound: true confirms the id_token carries a cnf.jkt matching the agent key — required to sign verifiable commits.

Environment Variables

VariablePurpose
ALIEN_PROVIDER_ADDRESSProvider address (avoids the --provider-address flag)
AGENT_ID_STATE_DIRCustom state directory (default: ~/.agent-id)

Next Steps

Last updated on
IntroductionCredential Vault