Quick Start

Prerequisites

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

Quick Start

1. Install the skill

npx skills add alien-id/agent-id

Claude Code only

Alternatively, install via the plugin marketplace:

/plugin marketplace add alien-id/agent-id
/plugin install alien-agent-id@alien-agent-id
/reload-plugins

Sometimes the reload does not work properly the first time — restarting Claude usually helps.

2. Set up your Agent ID

When the plugin is loaded, run the skill:

/alien-agent-id

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.

3. Add the signing key to GitHub

The agent will output an SSH public key after setup. Add it to your GitHub account:

Go to 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:

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

Other Agents

Any agent with shell access can use skills/alien-agent-id/SKILL.md directly. The agent needs Node.js 18+, git 2.34+, and permission to run node cli.mjs ... commands.

Instruct the agent however your platform supports it — system prompt, instructions file, initial message — to read SKILL.md and follow the bootstrap steps.

CI/CD

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

In CI, the bootstrap blocks waiting for QR approval. For attended CI, the QR 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:

node cli.mjs bootstrap

This generates the keypair, starts OIDC auth with Alien SSO, shows a QR code, waits for human approval, creates the owner binding, and configures git signing — all in one step.

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

If bootstrap doesn’t work for your setup, run each step individually:

# Step 1: Generate keypair
node cli.mjs init
 
# Step 2: Start OIDC auth (returns QR code / deep link)
node cli.mjs auth --provider-address <PROVIDER_ADDRESS>
 
# Step 3: Wait for human approval (blocks up to 5 min)
node cli.mjs bind
 
# Step 4: Configure git signing
node cli.mjs git-setup --email user@example.com

What a Signed Commit Looks Like

✓ Verified

feat: implement auth flow

Agent-ID-Fingerprint: 945d41991dac118776409673019ed0fba36e13fc9d6b5534145f9e31128a3ec6
Agent-ID-Owner: 00000003010000000000539c741e0df8
Agent-ID-Binding: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Anyone can trace: this code → this agent (fingerprint) → this human (owner address) → verified AlienID holder.

Verify It Works

# Check status
node cli.mjs status
 
# Make a signed commit
node cli.mjs git-commit --message "feat: first signed commit" --push
 
# Verify provenance
node cli.mjs git-verify --commit HEAD

Environment Variables

Next Steps

• Credential Vault — Store API keys and secrets securely
• Session Refresh — Renew SSO sessions without human interaction
• Git Commit Signing — Trailers, proof bundles, verification
• External Services Auth — Authenticate to services
• CLI Reference — All commands and flags