Skip to content
Back to search

open-agents

An open source template for building cloud agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vercel-labs--open-agents/badge.svg)](/listings/vercel-labs--open-agents)

HTML

<a href="/listings/vercel-labs--open-agents"><img src="/api/listings/vercel-labs--open-agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install dependencies:

   corepack enable
   pnpm install

2. Create your local env file:

   cp apps/web/.env.example apps/web/.env

3. Fill in the required values in `apps/web/.env`. 4. Start the app:

   pnpm web

If you already have a linked Vercel project, you can pull env vars locally with `vc env pull`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 236 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Open Agents
  2. [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?project-name=open-agents&repository-name=open-agents&repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fopen-agents&demo-title=Open+Agents&demo-description=Open-source+reference+app+for+building+and+running+background+coding+agents+on+Vercel.&demo-url=https%3A%2F%2Fopen-agents.dev%2F&env=POSTGRES_URL%2CBETTER_AUTH_SECRET%2CNEXT_PUBLIC_VERCEL_APP_CLIENT_ID%2CVERCEL_APP_CLIENT_SECRET%2CNEXT_PUBLIC_GITHUB_CLIENT_ID%2CGITHUB_CLIENT_SECRET%2CGITHUB_APP_ID%2CGITHUB_APP_PRIVATE_KEY%2CNEXT_PUBLIC_GITHUB_APP_SLUG%2CGITHUB_WEBHOOK_SECRET&envDescription=Neon+can+provide+POSTGRES_URL+automatically.+Generate+BETTER_AUTH_SECRET+yourself%2C+then+add+your+Vercel+OAuth+and+GitHub+App+credentials+for+a+full+deployment.&products=%255B%257B%2522type%2522%253A%2522integration%2522%252C%2522protocol%2522%253A%2522storage%2522%252C%2522productSlug%2522%253A%2522neon%2522%252C%2522integrationSlug%2522%253A%2522neon%2522%257D%252C%257B%2522type%2522%253A%2522integration%2522%252C%2522protocol%2522%253A%2522storage%2522%252C%2522productSlug%2522%253A%2522upstash-kv%2522%252C%2522integrationSlug%2522%253A%2522upstash%2522%257D%255D&skippable-integrations=1)
  3. Open Agents is an open-source reference app for building and running background coding agents on Vercel. It includes the web UI, the agent runtime, sandbox orchestration, and the GitHub integration needed to go from prompt to code changes without keeping your laptop involved.
  4. The repo is meant to be forked and adapted, not treated as a black box.
  5. ## What it is
  6. Open Agents is a three-layer system:
  7. ```text
  8. Web -> Agent workflow -> Sandbox VM
  9. ```
  10. - The web app handles auth, sessions, chat, and streaming UI.
  11. - The agent runs as a durable workflow on Vercel.
  12. - The sandbox is the execution environment: filesystem, shell, git, dev servers, and preview ports.
  13. ### The key architectural decision: the agent is not the sandbox
  14. The agent does not run inside the VM. It runs outside the sandbox and interacts with it through tools like file reads, edits, search, and shell commands.
  15. That separation is the main point of the project:
  16. - agent execution is not tied to a single request lifecycle
  17. - sandbox lifecycle can hibernate and resume independently
  18. - model/provider choices and sandbox implementation can evolve separately
  19. - the VM stays a plain execution environment instead of becoming the control plane
  20. ## Current capabilities
  21. - chat-driven coding agent with file, search, shell, task, skill, and web tools
  22. - durable multi-step execution with Workflow SDK-backed runs, streaming, and cancellation
  23. - isolated Vercel sandboxes with snapshot-based resume
  24. - repo cloning and branch work inside the sandbox
  25. - optional auto-commit, push, and PR creation after a successful run
  26. - session sharing via read-only links
  27. - optional voice input via ElevenLabs transcription
  28. ## Runtime notes
  29. A few details that matter for understanding the current implementation:
  30. - Chat requests start a workflow run instead of executing the agent inline.
  31. - Each agent turn can continue across many persisted workflow steps.
  32. - Active runs can be resumed by reconnecting to the stream for the existing workflow.
  33. - Sandboxes expose ports `3000`, `5173`, `4321`, and `8000`, can optionally use a configured base snapshot, and hibernate after inactivity.
  34. - Auto-commit and auto-PR are supported, but they are preference-driven features, not always-on behavior.
  35. ## Environment variables
  36. See `apps/web/.env.example` for the full list. Summary:
  37. ### Minimum runtime
  38. ```env
  39. POSTGRES_URL=
  40. BETTER_AUTH_SECRET=
  41. ```
  42. ### Required for sign-in (Vercel OAuth)
  43. ```env
  44. NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
  45. VERCEL_APP_CLIENT_SECRET=
  46. ```
  47. ### Required for GitHub repo access, pushes, and PRs
  48. ```env
  49. NEXT_PUBLIC_GITHUB_CLIENT_ID=
  50. GITHUB_CLIENT_SECRET=
  51. GITHUB_APP_ID=
  52. GITHUB_APP_PRIVATE_KEY=
  53. NEXT_PUBLIC_GITHUB_APP_SLUG=
  54. GITHUB_WEBHOOK_SECRET=
  55. ```
  56. ### Optional
  57. ```env
  58. REDIS_URL=
  59. KV_URL=
  60. OPEN_AGENTS_RESOURCE_PROFILE=
  61. VERCEL_PROJECT_PRODUCTION_URL=
  62. NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=
  63. VERCEL_SANDBOX_BASE_SNAPSHOT_ID=
  64. ELEVENLABS_API_KEY=
  65. ```
  66. - `REDIS_URL` / `KV_URL`: optional skills metadata cache (falls back to in-memory when not configured).
  67. - `OPEN_AGENTS_RESOURCE_PROFILE`: optional deployment resource profile. Set to `hobby` to use Hobby-compatible defaults for chat and sandbox resources; leave unset for standard behavior.
  68. - `VERCEL_PROJECT_PRODUCTION_URL` / `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`: canonical production URL for metadata and some callback behavior.
  69. - `VERCEL_SANDBOX_BASE_SNAPSHOT_ID`: optional base snapshot for fresh sandboxes. If unset, sandboxes start from Vercel's standard Sandbox runtime. Use a snapshot created in/accessible to your own Vercel scope.
  70. - `ELEVENLABS_API_KEY`: voice transcription.
  71. ## Deploy your own copy on Vercel
  72. 1. Fork this repo.
  73. 2. Import the repo into Vercel. Neon Postgres is auto-provisioned if you use the deploy button above.
  74. 3. Generate a secret for session signing:
  75. ```bash
  76. openssl rand -base64 32 # BETTER_AUTH_SECRET
  77. ```
  78. 4. Add env vars in Vercel project settings:
  79. ```env
  80. POSTGRES_URL=
  81. BETTER_AUTH_SECRET=
  82. ```
  83. 5. Deploy once to get a stable production URL.
  84. 6. Create a Vercel OAuth app with callback URL:
  85. ```text
  86. https://YOUR_DOMAIN/api/auth/callback/vercel
  87. ```
  88. 7. Add these env vars and redeploy:
  89. ```env
  90. NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
  91. VERCEL_APP_CLIENT_SECRET=
  92. ```
  93. 8. If you want the full GitHub-enabled coding-agent flow, create a GitHub App using:
  94. - Homepage URL: `https://YOUR_DOMAIN`
  95. - Callback URL: `https://YOUR_DOMAIN/api/auth/callback/github`
  96. - Setup URL: `https://YOUR_DOMAIN/api/github/app/callback`
  97. In the GitHub App settings:
  98. - use the GitHub App's Client ID and Client Secret for `NEXT_PUBLIC_GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`
  99. - make the app public if you want org installs to work cleanly
  100. 9. Add the GitHub App env vars and redeploy.
  101. 10. Optionally add Redis/KV, `OPEN_AGENTS_RESOURCE_PROFILE=hobby` for Hobby-compatible resource defaults, the canonical production URL vars, and your own `VERCEL_SANDBOX_BASE_SNAPSHOT_ID` if you want fresh sandboxes to start from a preconfigured image.
  102. ## Local setup
  103. 1. Install dependencies:
  104. ```bash
  105. corepack enable
  106. pnpm install
  107. ```
  108. 2. Create your local env file:
  109. ```bash
  110. cp apps/web/.env.example apps/web/.env
  111. ```
  112. 3. Fill in the required values in `apps/web/.env`.
  113. 4. Start the app:
  114. ```bash
  115. pnpm web
  116. ```
  117. If you already have a linked Vercel project, you can pull env vars locally with `vc env pull`.
  118. ## OAuth and integration setup
  119. ### Vercel OAuth
  120. Authentication is handled by [Better Auth](https://www.better-auth.com/) with Vercel and GitHub as social providers. All auth routes are served from the `/api/auth/[...all]` catchall.
  121. Create a Vercel OAuth app and use this callback:
  122. ```text
  123. https://YOUR_DOMAIN/api/auth/callback/vercel
  124. ```
  125. For local development, use:
  126. ```text
  127. http://localhost:3000/api/auth/callback/vercel
  128. ```
  129. Then set:
  130. ```env
  131. NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
  132. VERCEL_APP_CLIENT_SECRET=...
  133. ```
  134. ### GitHub App
  135. You do not need a separate GitHub OAuth app. Open Agents uses the GitHub App's OAuth credentials as a Better Auth social provider, plus the App's installation tokens for repo access.
  136. Create a GitHub App for installation-based repo access and configure:
  137. - Homepage URL: `https://YOUR_DOMAIN`
  138. - Callback URL: `https://YOUR_DOMAIN/api/auth/callback/github`
  139. - Setup URL: `https://YOUR_DOMAIN/api/github/app/callback`
  140. - make the app public if you want org installs to work cleanly
  141. For local development, use `http://localhost:3000` as the homepage URL, `http://localhost:3000/api/auth/callback/github` as the callback URL, and `http://localhost:3000/api/github/app/callback` as the setup URL.
  142. Then set:
  143. ```env
  144. NEXT_PUBLIC_GITHUB_CLIENT_ID=... # GitHub App Client ID
  145. GITHUB_CLIENT_SECRET=... # GitHub App Client Secret
  146. GITHUB_APP_ID=...
  147. GITHUB_APP_PRIVATE_KEY=...
  148. NEXT_PUBLIC_GITHUB_APP_SLUG=...
  149. GITHUB_WEBHOOK_SECRET=...
  150. ```
  151. `GITHUB_APP_PRIVATE_KEY` can be stored as the PEM contents with escaped newlines or as a base64-encoded PEM.
  152. ## Useful commands
  153. ```bash
  154. pnpm web # run dev server
  155. pnpm check # lint + format check
  156. pnpm fix # lint + format fix
  157. pnpm typecheck # typecheck all packages
  158. pnpm run ci # full CI: check, typecheck, tests, migration check
  159. pnpm sandbox:snapshot-base # refresh sandbox base snapshot
  160. ```
  161. ## Repo layout
  162. ```text
  163. apps/web Next.js app, workflows, auth, chat UI
  164. packages/agent agent implementation, tools, subagents, skills
  165. packages/sandbox sandbox abstraction and Vercel sandbox integration
  166. packages/shared shared utilities
  167. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.