{"id":51195295,"url":"https://github.com/clerk/eve-agents","last_synced_at":"2026-06-27T20:01:00.110Z","repository":{"id":367586982,"uuid":"1273632153","full_name":"clerk/eve-agents","owner":"clerk","description":"A starter kit for using clerk auth with eve agents.","archived":false,"fork":false,"pushed_at":"2026-06-26T17:12:29.000Z","size":559,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T17:14:09.898Z","etag":null,"topics":["ai","ai-agents","clerk","clerk-auth"],"latest_commit_sha":null,"homepage":"https://eve-agents-with-clerk-dashboard.clerkstage.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clerk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T18:02:36.000Z","updated_at":"2026-06-26T15:23:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clerk/eve-agents","commit_stats":null,"previous_names":["clerk/eve-agents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/clerk/eve-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Feve-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Feve-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Feve-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Feve-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clerk","download_url":"https://codeload.github.com/clerk/eve-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Feve-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34866118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","clerk","clerk-auth"],"created_at":"2026-06-27T20:00:29.504Z","updated_at":"2026-06-27T20:01:00.092Z","avatar_url":"https://github.com/clerk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://clerk.com?utm_source=github\u0026utm_medium=eve_examples\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n    \u003cimg src=\"https://images.clerk.com/static/logo-light-mode-400x400.png\" height=\"64\" alt=\"Clerk logo\"\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003ch1 align=\"center\"\u003eeve agents with Clerk\u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord)\n[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github\u0026utm_medium=eve_examples)\n[![Follow on X](https://img.shields.io/twitter/follow/clerk?style=social)](https://x.com/intent/follow?screen_name=clerk)\n\n\u003c/div\u003e\n\nA monorepo showing how to secure [eve](https://vercel.com/eve) agents with [Clerk](https://clerk.com?utm_source=github\u0026utm_medium=eve_examples). One auth connector handles every Clerk token type — session, API key, M2M, OAuth — with optional permission, scope, and role gates. Includes agent-to-agent M2M auth, enriched agent instructions, and tool-call authorization.\n\n## What's inside\n\n1. **Clerk auth helpers** — eve-compatible channel auth and helpers for securing subagents and tool calls.\n2. **Two sample apps** — a Next.js dashboard with a chat UI and a colocated `main-agent` that delegates work, plus a `project-agent` subagent reachable only via M2M.\n3. **Dynamic instructions** — Enriched prompts with Clerk auth context.\n4. **shadcn registry** — pull Clerk auth helpers into an existing eve project with shadcn.\n\n| Workspace | Description |\n| --- | --- |\n| [`apps/dashboard`](apps/dashboard) | Next.js app featuring Clerk-authenticated chat UI with a colocated `main-agent` (mounted via `withEve`). |\n| [`apps/project-agent`](apps/project-agent) | Remote subagent that communicates with `main-agent` (port 3002). Reachable machine-to-machine only. |\n| [`packages/clerk-eve-auth`](packages/clerk-eve-auth) | Clerk helpers and channel auth for eve agents. |\n\n\n## Quick start\n\n\u003e [!TIP]\n\u003e Want to use Clerk auth in an existing eve project? Skip the quickstart and [install the auth helpers with shadcn.](#install-with-shadcn)\n\nPrerequisites:\n\n- [Bun](https://bun.sh) 1.3+ and [Node.js](https://nodejs.org) 24+ (eve requires Node 24).\n- A [Clerk application](https://dashboard.clerk.com/sign-up?utm_source=github\u0026utm_medium=eve_examples). The session and M2M flows work out of the box; to exercise every flow, enable [**API keys**](https://dashboard.clerk.com/~/platform/api-keys) in the Clerk Dashboard and add a **GitHub** [social connection](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/github) with **custom credentials** (the `list_repos` tool requests the `repo` scope at connect time, which Clerk only allows with custom credentials — not the shared development ones).\n- A [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) API key. The agents default to a free-tier model (`anthropic/claude-haiku-4.5`), so a new account runs the demo without adding credits — to use a more capable model, set it in `apps/*/agent/agent.ts` and confirm your account has access ([available models](https://vercel.com/d?to=%2F%5Bteam%5D%2F~%2Fai-gateway%2Fmodels)).\n\n```bash\nbun install\n```\n\nCopy the `.env.example` templates into `.env.local`:\n\n```bash\ncp apps/dashboard/.env.example apps/dashboard/.env.local\ncp apps/project-agent/.env.example apps/project-agent/.env.local\n```\n\nFill in the Clerk keys and `AI_GATEWAY_API_KEY` in each `.env.local` — the dashboard reads `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, the project-agent reads `CLERK_PUBLISHABLE_KEY` (the `.env.example` files already use the right names). Then create the two Clerk machines with M2M scopes in one shot:\n\n```bash\nbun run demo:create-machines\n```\n\nCopy each printed secret into `CLERK_MACHINE_SECRET_KEY` — the main-agent secret in `apps/dashboard/.env.local`, the project-agent secret in `apps/project-agent/.env.local` — then:\n\n```bash\nbun run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000), sign in, and chat. Use the auth-flow dropdown or ask the agent to archive a project to watch M2M in action.\n\n## Install with Shadcn\n\nUse shadcn to install Clerk auth helpers into an existing eve project.\n\n```bash\nbunx --bun shadcn@latest add clerk/eve-agents/auth\n```\n\nDrop `clerkAuth()` into your eve channel's auth list to verify Clerk callers on every inbound request:\n\n```ts\n// agent/channels/eve.ts\nimport { clerkAuth } from '@/lib/clerk-auth'\nimport { eveChannel } from 'eve/channels/eve'\n\nexport default eveChannel({\n  auth: [clerkAuth()],\n})\n```\n\nUse `clerkInstructions()` to rebuild the system prompt per session with the authenticated caller's context:\n\n```ts\n// agent/instructions.ts\nimport { clerkInstructions } from '@/lib/clerk-auth/instructions'\n\nexport default clerkInstructions((auth, userInfo) =\u003e [\n  'You are a helpful assistant.',\n  userInfo\n])\n```\n\nPair `clerkM2MToken()` with eve's `bearer()` to sign outbound calls to a remote subagent with a short-lived Clerk M2M token:\n\n```ts\n// agent/subagents/\u003cname\u003e.ts\nimport { clerkM2MToken } from '@/lib/clerk-auth/m2m'\nimport { defineRemoteAgent } from 'eve'\nimport { bearer } from 'eve/agents/auth'\n\nexport default defineRemoteAgent({\n  url: process.env.SUBAGENT_URL!,\n  description: 'Delegates to the subagent.',\n  auth: bearer(clerkM2MToken()),\n})\n```\n\nUse `clerkConnect()` as a tool's `auth` to call a provider API on the caller's behalf, with Clerk brokering the OAuth:\n\n```ts\n// agent/tools/list_repos.ts\nimport { clerkConnect } from '@/lib/clerk-auth/connect'\nimport { defineTool } from 'eve/tools'\n\nexport default defineTool({\n  inputSchema: z.object({}),\n  auth: clerkConnect('github', { scopes: ['repo'] }),\n  async execute(_input, ctx) {\n    const { token } = await ctx.getToken() // the caller's GitHub token\n  },\n})\n```\n\n## Configuring `clerkAuth()`\n\n`clerkAuth()` verifies any Clerk token type and maps the caller to an eve principal. Default behavior returns `null` on failure so the chain walks to the next authenticator. Every option is opt-in — combine them freely.\n\n```ts\n// agent/channels/eve.ts\nimport { clerkAuth } from '@clerk/eve-auth'\nimport { eveChannel } from 'eve/channels/eve'\n\nexport default eveChannel({\n  auth: [clerkAuth()],\n})\n```\n\nFor the full list of options with examples for each, see [docs/configuration.md](docs/configuration.md).\n\nAfter `clerkAuth()` succeeds, eve exposes the caller as `ctx.session.auth.current`:\n\n```ts\n{\n  authenticator: 'clerk',\n  principalType: 'user' | 'machine',\n  principalId: string,\n  subject: string,\n  attributes: { /* per token type */ },\n}\n```\n\nAttributes differ by principal and Clerk token type. See [docs/attributes.md](docs/attributes.md) to see type definitions for each.\n\n\n## Provider OAuth in tools\n\n`clerkConnect()` lets a tool call a third-party API on the caller's behalf, with Clerk brokering the OAuth. Used as an eve tool `auth` strategy, it reads the caller's stored provider token and — when it's missing or under-scoped — surfaces a **Connect** link that runs Clerk's frontend connect flow and resumes the turn once authorized.\n\n```ts\n// agent/tools/list_repos.ts\nimport { clerkConnect } from '@clerk/eve-auth/connect'\n\nexport default defineTool({\n  inputSchema: z.object({}),\n  auth: clerkConnect('github', { scopes: ['repo'] }),\n  async execute(_input, ctx) {\n    const { token } = await ctx.getToken() // the caller's GitHub token\n    // …call the provider API\n  },\n})\n```\n\nInteractive connect only resolves for signed-in **user** callers. Machine tokens use a non-interactive connection mode. See [`apps/dashboard/agent/tools/list_repos.ts`](apps/dashboard/agent/tools/list_repos.ts).\n\n\n## How it works\n\n### Authorized agent delegation and collaboration\n\nAgents can call each other securely over M2M with short-lived [machine tokens](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens), with scope enforced by Clerk.\n\nSee [docs/m2m.md](docs/m2m.md) for how agents map to Clerk machines, the scope model, and the setup script.\n\n### Enriching dynamic instructions\n\n`clerkInstructions()` is a helper that uses [dynamic instructions](https://eve.dev/docs/guides/dynamic-capabilities#dynamic-instructions) and runs on every `session.started` event, returning a prompt enriched with the Clerk caller's auth context.\n\n```ts\n// agent/instructions.ts\nimport { clerkInstructions } from '@clerk/eve-auth/instructions'\n\nexport default clerkInstructions((auth, userInfo) =\u003e [\n  'You are a helpful assistant.',\n  userInfo \u0026\u0026\n    `Use the following info about the caller to personalize your response:\\n${userInfo}`,\n])\n```\n\nFor a signed-in user, `userInfo` looks like:\n\n```\ntokenType: session_token\norgId: org_123\nrole: org:admin\npermissions: org:projects:archive, org:projects:read\nname: John Doe\n```\n\nThe callback receives three arguments:\n\n- `auth` — the Clerk-backed eve principal, or `null` when no caller authenticated.\n- `userInfo` — a pre-built newline-separated `key: value` summary of `auth.attributes` (empty string when unauthenticated). \n- `ctx` — the raw `DynamicResolveContext` for advanced use (session id, message history, channel metadata).\n\n### Sending auth context from client\n\nDynamic instructions run when a session starts. For per-turn context coming from the browser (user name, active org ID), use `clientContext` instead — it's ephemeral, sent on each turn, and passed to the model alongside the message.\n\n```ts\n// apps/dashboard/src/components/chat/chat.tsx\nconst agent = useEveAgent({\n  prepareSend: input =\u003e ({\n    ...input,\n    clientContext: { \n      user: user?.fullName ?? null, \n      orgId: orgId ?? null \n    },\n  }),\n})\n```\n\nSee eve docs on [attaching page context](https://eve.dev/docs/guides/frontend/overview#attach-page-context-per-turn) for the full guide.\n\n\n## Deploying to production\n\nSee [docs/production.md](docs/production.md).\n\n## Support\n\nFor help, visit our [support page](https://clerk.com/contact/support?utm_source=github\u0026utm_medium=eve_examples) or join our [Discord](https://clerk.com/discord).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclerk%2Feve-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclerk%2Feve-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclerk%2Feve-agents/lists"}