Getting Started with AgentLair
Set up your agent's email in under 2 minutes. Works from browser or terminal.
1 Create your account
Get an API key that identifies your agent. No email, no credit card, no verification.
🌐 Browser: Go to the
homepage signup and click
"Create Free Account". Your key appears immediately.
# Terminal:
curl -X POST https://agentlair.dev/v1/auth/keys
→ { "api_key": "al_live_k7x9m2p4...", "tier": "free" }
⚠️ Save your API key! It's shown only once. If you lose it, set a recovery email (step 4) to regain access via the dashboard.
2 Claim an email address
Pick any available name@agentlair.dev address. First come, first served.
🌐 Browser: After creating your account on the homepage, the claim form appears automatically. Or use the
dashboard → "Claim New Address".
curl -X POST https://agentlair.dev/v1/email/claim \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"address": "my-agent@agentlair.dev"}'
→ { "address": "my-agent@agentlair.dev", "claimed": true }
Naming tips: Use descriptive names like research-agent, outreach-bot, or your project name. You get 10 addresses on the free tier.
3 Send your first email
Send a test email to yourself to verify everything works.
🌐 Browser: Open the
dashboard, find the
Compose Email section, fill in the form, and click
Send.
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.}'
4 Check your inbox
Reply to the email you just sent, then check your agent's inbox.
🌐 Browser: The
dashboard shows your inbox under each address. Click a message to read it.
curl https://agentlair.dev/v1/email/inbox?address=my-agent@agentlair.dev \
-H "Authorization: Bearer YOUR_API_KEY"
☆ Set a recovery email (recommended)
Attach a personal email to your account. This enables magic-link dashboard login and key recovery.
🌐 Browser: On the
dashboard, click
"Update recovery email" in the account card.
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"}'
☆ Store secrets in Vault (optional)
Keep your agent's API keys and credentials safe across container restarts. Client-side encrypted — AgentLair never sees the plaintext.
# Install the crypto library (zero dependencies)
npm install @agentlair/vault-crypto
// Encrypt → store → retrieve → decrypt
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 ${apiKey}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ ciphertext: ct }),
});
// Retrieve and decrypt
const res = await fetch('https://agentlair.dev/v1/vault/openai-key', {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const plain = await vc.decrypt((await res.json()).ciphertext, 'openai-key');
Tip: Save the hex seed (
vc.seedHex()) in an env var. Or use
encryptSeedBackup() with a passphrase for recovery.
Learn more about Vault → ☆ 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. The agent owns the schedule; humans just follow it.
# Create an event
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" }
# Get the iCal feed URL (subscribe in any calendar app)
curl https://agentlair.dev/v1/calendar/my-agent@agentlair.dev/ical
→ text/calendar — paste this URL into Google Calendar
Subscribe in Google Calendar: Open Google Calendar → click
+ next to "Other calendars" → "From URL" → paste the iCal URL above. Your agent's schedule appears in real-time, updated automatically as the agent creates or modifies events.
Learn more about Agent Calendar → ✅ You're all set!
Your agent has email, encrypted secret storage, and a calendar. Here's what to explore next: