open-agents README

The project's README from github.com/vercel-labs/open-agents. As one markdown file: README.md.

Open Agents

Deploy with Vercel

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.

The repo is meant to be forked and adapted, not treated as a black box.

What it is

Open Agents is a three-layer system:

Web -> Agent workflow -> Sandbox VM

The key architectural decision: the agent is not the sandbox

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.

That separation is the main point of the project:

Current capabilities

Runtime notes

A few details that matter for understanding the current implementation:

Environment variables

See apps/web/.env.example for the full list. Summary:

Minimum runtime

POSTGRES_URL=
BETTER_AUTH_SECRET=

Required for sign-in (Vercel OAuth)

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

Required for GitHub repo access, pushes, and PRs

NEXT_PUBLIC_GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
NEXT_PUBLIC_GITHUB_APP_SLUG=
GITHUB_WEBHOOK_SECRET=

Optional

REDIS_URL=
KV_URL=
OPEN_AGENTS_RESOURCE_PROFILE=
VERCEL_PROJECT_PRODUCTION_URL=
NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=
VERCEL_SANDBOX_BASE_SNAPSHOT_ID=
ELEVENLABS_API_KEY=

Deploy your own copy on Vercel

  1. Fork this repo.

  2. Import the repo into Vercel. Neon Postgres is auto-provisioned if you use the deploy button above.

  3. Generate a secret for session signing:

    openssl rand -base64 32   # BETTER_AUTH_SECRET

  4. Add env vars in Vercel project settings:

    POSTGRES_URL=
BETTER_AUTH_SECRET=

  5. Deploy once to get a stable production URL.

  6. Create a Vercel OAuth app with callback URL:

    https://YOUR_DOMAIN/api/auth/callback/vercel

  7. Add these env vars and redeploy:

    NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

  8. If you want the full GitHub-enabled coding-agent flow, create a GitHub App using:

    • Homepage URL: https://YOUR_DOMAIN
    • Callback URL: https://YOUR_DOMAIN/api/auth/callback/github
    • Setup URL: https://YOUR_DOMAIN/api/github/app/callback

    In the GitHub App settings:

    • use the GitHub App's Client ID and Client Secret for NEXT_PUBLIC_GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
    • make the app public if you want org installs to work cleanly

  9. Add the GitHub App env vars and redeploy.

  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.

Local setup

  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.

OAuth and integration setup

Vercel OAuth

Authentication is handled by Better Auth with Vercel and GitHub as social providers. All auth routes are served from the /api/auth/[...all] catchall.

Create a Vercel OAuth app and use this callback:

https://YOUR_DOMAIN/api/auth/callback/vercel

For local development, use:

http://localhost:3000/api/auth/callback/vercel

Then set:

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
VERCEL_APP_CLIENT_SECRET=...

GitHub App

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.

Create a GitHub App for installation-based repo access and configure:

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.

Then set:

NEXT_PUBLIC_GITHUB_CLIENT_ID=...   # GitHub App Client ID
GITHUB_CLIENT_SECRET=...           # GitHub App Client Secret
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY=...
NEXT_PUBLIC_GITHUB_APP_SLUG=...
GITHUB_WEBHOOK_SECRET=...

GITHUB_APP_PRIVATE_KEY can be stored as the PEM contents with escaped newlines or as a base64-encoded PEM.

Useful commands

pnpm web                    # run dev server
pnpm check                  # lint + format check
pnpm fix                    # lint + format fix
pnpm typecheck              # typecheck all packages
pnpm run ci                 # full CI: check, typecheck, tests, migration check
pnpm sandbox:snapshot-base  # refresh sandbox base snapshot

Repo layout

apps/web         Next.js app, workflows, auth, chat UI
packages/agent   agent implementation, tools, subagents, skills
packages/sandbox sandbox abstraction and Vercel sandbox integration
packages/shared  shared utilities

open-agents (vercel-labs/open-agents)

Searching Database…

5.8K ·GitHub
Open-agents
What is this?Open Agents is an open-source reference app for building and running background coding agents on Vercel, including the web UI, agent runtime, sandbox orchestration, and GitHub integration needed to go from prompt to code changes.
Is this a ready-made product or a template I deploy myself?It's a template meant to be forked and adapted rather than used as a black box — you fork it, deploy your own copy to Vercel, and customize it for your needs.
How do I get this running?Fork the repo and import it into Vercel (Neon Postgres is auto-provisioned), generate a session secret, add the required env vars, create a Vercel OAuth app, and deploy; for local development install deps with pnpm, copy the env example, fill in values, and run the dev script.
Do I need a Vercel account and a GitHub App to use it?Yes — a Vercel account is required for OAuth sign-in and hosting, and a GitHub App is needed for the full coding-agent flow (repo cloning, pushes, and PR creation); an ElevenLabs key is only needed if you want voice input.
Does the agent run inside the sandbox VM?No — the agent runs outside the sandbox and talks to it through tools like file reads, edits, search, and shell commands, which is the project's core architectural decision so the VM stays a plain execution environment.
What happens to a sandbox when it's idle?Sandboxes hibernate after inactivity and can resume from a snapshot, so the execution environment doesn't need to stay running between agent turns.
Does it support voice input?Yes, optional voice input is available through ElevenLabs transcription.
Can I share a running agent session with someone else?Yes, sessions can be shared via read-only links so others can watch the agent's progress.
What are similar projects?crm, cloudflare-os, open-swe, LibreChat, trueforge, remix, chatbot, useagent
Which topics is it in?turbo, pnpm, voice, full-stack, serverless, speech-to-text, template, oauth, monorepo, sandbox, github, workflow-automation
Creator
vercel-labs
Size
10.8 MB
Stars
5.8K
Updated
CommitJun 04
Age
9mo
Commits · 90 Days