IdentityEmailVaultTrust

Getting Started with AgentLair

Register your agent, send email, store secrets, and check your trust score. Under 5 minutes.

1

Register your agent

One call creates your account. No email, no credit card, no verification — instant access. You get an API key, a persistent agent identity, and a built-in @agentlair.dev email address.

Browser: Go to agentlair.dev/register and click "Create Free Account". Your API key appears immediately.
Terminal
curl -X POST https://agentlair.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
→ {
    "api_key": "al_live_k7x9m2p4...",
    "account_id": "acc_7kX9mP2qR4wL",
    "email_address": "my-agent@agentlair.dev",
    "tier": "free"
  }
Save your API key! It's shown only once. Store it as AGENTLAIR_API_KEY in your environment. Your email_address is auto-assigned and ready to use immediately.
2

Send your first email

Use the email_address from step 1 to send an email from your agent. The text field carries the plain-text body.

Browser: Open the dashboard, find the Compose Email section, fill in the form, and click Send.
Terminal
curl -X POST https://agentlair.dev/v1/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "my-agent@agentlair.dev",
    "to": ["your-real-email@gmail.com"],
    "subject": "Hello from AgentLair!",
    "text": "This is my agent speaking."
  }'
Use an external address for testing. Sending to another @agentlair.dev address works — it delivers to their inbox. For this test, use Gmail, Outlook, or any external address so you can verify receipt directly in your regular email client.
3

Store a secret in Vault

Keep your agent's credentials safe across container restarts. Zero-knowledge design: secrets are encrypted client-side before leaving your machine — AgentLair stores only ciphertext. The vault API accepts PUT /v1/vault/{key} with a {"ciphertext": "..."} body.

Install
npm install @agentlair/vault-crypto
vault.ts
import { VaultCrypto } from '@agentlair/vault-crypto';

const seed = VaultCrypto.generateSeed();
const vc = VaultCrypto.fromSeed(seed);

// Encrypt before storing
const ct = await vc.encrypt('sk-openai-abc123', 'openai-key');
await fetch('https://agentlair.dev/v1/vault/openai-key', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.AGENTLAIR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ciphertext: ct }),
});

// Retrieve and decrypt later
const res = await fetch('https://agentlair.dev/v1/vault/openai-key', {
  headers: { 'Authorization': `Bearer ${process.env.AGENTLAIR_API_KEY}` },
});
const plain = await vc.decrypt((await res.json()).ciphertext, 'openai-key');
Save the seed hex. Call vc.seedHex() and store it in an env var — you need it to decrypt. Or use encryptSeedBackup() with a passphrase for recovery. Learn more about Vault →
4

Check your trust score

Every agent starts with a cold-start score of 30. Trust builds through consistent, transparent behavior observed across all services using AgentLair for verification.

Terminal
# Use your account_id from step 1
curl https://agentlair.dev/v1/trust/acc_7kX9mP2qR4wL \
  -H "Authorization: Bearer YOUR_API_KEY"
→ {
    "agentId": "acc_7kX9mP2qR4wL",
    "score": 30,
    "atfLevel": "intern",
    "trend": "stable",
    "dimensions": {
      "consistency":  { "score": 30 },
      "restraint":    { "score": 30 },
      "transparency": { "score": 30 }
    },
    "observationCount": 1
  }
LevelScoreMeaning
intern0–39No behavioral history — you start here
junior40–59Some signal, limited cross-org coverage
senior60–79Established behavioral baseline
principal80–100Deep history, high transparency
Score builds through consistent behavior, transparent audit trails, and cross-organizational verification. Use the Audit Logger to log agent actions and accelerate trust accumulation.
✓

Your agent is live

You registered, sent email, stored a secret, and have a live trust score. Here's what to explore next:

Concepts

What is an AAT? What is L4 behavioral trust? How does JWKS verification work?

API Reference

All endpoints: registration, email, vault, trust scoring, tokens.

Vault

Zero-knowledge encrypted secret store. Versioned. Recoverable.

Agent Calendar

Create events via REST. Share an iCal feed. Humans subscribe in any calendar app.

Agent Pods

Multi-tenant isolation. Each pod gets its own API key, email, vault, and calendar.

Audit Logger

Log agent actions to build behavioral history and improve your trust score.

Python SDK

pip install git+https://github.com/piiiico/agentlair-python.git — async-first, typed, zero extra dependencies.

MCP Server

npx @agentlair/mcp@latest — give Claude Code, Cursor, or Windsurf email, vault, and calendar tools.

Optional setup

5

Claim additional email addresses

(optional)

Pick any available @agentlair.dev address for your agent. You can claim up to 10 on the free tier.

Terminal
curl -X POST https://agentlair.dev/v1/email/claim \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "research-agent@agentlair.dev"}'
→ {
    "claimed": true,
    "address": "research-agent@agentlair.dev"
  }
6

Check your inbox

(optional)

After an external address replies to your email, check what arrived.

Browser: The dashboard shows your inbox under each address. Click a message to read it.
Terminal
curl https://agentlair.dev/v1/email/inbox?address=my-agent@agentlair.dev \
  -H "Authorization: Bearer YOUR_API_KEY"
7

Set a recovery email

(optional)

Attach a personal email to your account. Enables magic-link dashboard login and API key recovery.

Terminal
curl -X POST https://agentlair.dev/v1/account/recovery-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
8

Set up your Agent Calendar

(optional)

Every agent address has a built-in calendar. Create events via REST, then share a public iCal URL — humans subscribe in Google Calendar, Apple Calendar, or any calendar app.

Terminal
curl -X POST https://agentlair.dev/v1/calendar/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "my-agent@agentlair.dev",
    "title": "Weekly sync",
    "start": "2026-04-01T10:00:00Z",
    "end": "2026-04-01T11:00:00Z"
  }'
→ { "event_id": "evt_abc123", "ical_url": "https://agentlair.dev/v1/calendar/my-agent@agentlair.dev/ical" }
Subscribe in Google Calendar: Open Google Calendar → click + next to "Other calendars" → "From URL" → paste the iCal URL. Learn more →
9

Use the Python SDK

(optional)

If you're building Python agents, install the official SDK and skip raw HTTP entirely. Async-first, fully typed, one dependency: httpx.

Install
pip install git+https://github.com/piiiico/agentlair-python.git
agent.py
import asyncio
import agentlair

async def main():
    async with agentlair.AgentLair("al_live_...") as lair:
        score = await lair.trust.score()
        print(f"Trust: {score['score']}/100 ({score['atfLevel']})")

        await lair.email.send(
            from_address="my-agent@agentlair.dev",
            to="you@example.com",
            subject="Hello from Python",
            text="Sent via the AgentLair Python SDK.",
        )

asyncio.run(main())
Full source and docs at github.com/piiiico/agentlair-python. PyPI publish is in progress — git-install works today.
10

Use the MCP Server

(optional)

Give Claude Code, Cursor, or Windsurf direct access to AgentLair email, vault, calendar, and task delegation — all from your AI assistant's chat.

Add this to your MCP client config (e.g. ~/.claude/settings.json for Claude Code):

~/.claude/settings.json
{
  "mcpServers": {
    "agentlair": {
      "command": "npx",
      "args": ["@agentlair/mcp@latest"],
      "env": {
        "AGENTLAIR_API_KEY": "al_live_..."
      }
    }
  }
}
No install needed. npx fetches the latest version automatically. After saving the config, restart your editor — AgentLair tools appear in your next session. Full MCP docs →
11

Issue an Agent Authentication Token (AAT)

(optional)

Issue a short-lived signed JWT your agent can present to any external service. The receiving service verifies it offline via AgentLair's JWKS endpoint — no round-trip needed. Attach it as a Bearer token in downstream requests.

Terminal
curl -X POST https://agentlair.dev/v1/tokens/issue \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-service-token",
    "ttl": 3600,
    "audience": "https://your-service.com",
    "scopes": ["read", "write"]
  }'
→ {
    "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_at": "2026-04-25T13:11:32.000Z",
    "expires_in": 3600,
    "jti": "aat_u6hT2o4LASbDsuGc",
    "audit_url": "https://agentlair.dev/v1/audit/aat_u6hT2o4LASbDsuGc"
  }
audience is the URI of the service you're calling — it gets embedded in the JWT so the receiver can confirm the token was minted for them. scopes must be a non-empty array. Verify tokens at your service with: GET https://agentlair.dev/.well-known/jwks.json. Full AAT reference →
12

Create an Agent Pod

(optional)

Pods give each of your clients a fully isolated environment — their own API key, email address, vault, and calendar — all under your master account. Ideal for multi-tenant products.

Browser: Open the Pods dashboard and click "Create Pod".
Terminal
curl -X POST https://agentlair.dev/v1/pods \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-corp"}'
→ {
    "pod_id": "pod_abc123",
    "api_key": "al_live_pod_...",
    "name": "acme-corp"
  }
One master key, many clients. Hand each pod's API key to your client — it's scoped exclusively to that pod's email, vault, and calendar. Learn more →
Need help? Email hello@agentlair.dev — we respond within 24 hours.