Open Agents

Open Agents

Open Agents is an open-source reference app for building and running background coding agents on Edgenivo. 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:

1
Web -> Agent workflow -> Sandbox VM

• The web app handles auth, sessions, chat, and streaming UI.
• The agent runs as a durable workflow on Edgenivo.
• The sandbox is the execution environment: filesystem, shell, git, dev servers, and preview ports.

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:

• agent execution is not tied to a single request lifecycle
• sandbox lifecycle can hibernate and resume independently
• model/provider choices and sandbox implementation can evolve separately
• the VM stays a plain execution environment instead of becoming the control plane

Current capabilities

• chat-driven coding agent with file, search, shell, task, skill, and web tools
• durable multi-step execution with Workflow SDK-backed runs, streaming, and cancellation
• isolated Edgenivo sandboxes with snapshot-based resume
• repo cloning and branch work inside the sandbox
• optional auto-commit, push, and PR creation after a successful run
• session sharing via read-only links
• optional voice input via ElevenLabs transcription

Runtime notes

A few details that matter for understanding the current implementation:

• Chat requests start a workflow run instead of executing the agent inline.
• Each agent turn can continue across many persisted workflow steps.
• Active runs can be resumed by reconnecting to the stream for the existing workflow.
• Sandboxes expose ports 3000, 5173, 4321, and 8000, can optionally use a configured base snapshot, and hibernate after inactivity.
• Auto-commit and auto-PR are supported, but they are preference-driven features, not always-on behavior.

Environment variables

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

Minimum runtime

1
POSTGRES_URL=
2
BETTER_AUTH_SECRET=

Required for sign-in (Edgenivo OAuth)

1
NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
2
VERCEL_APP_CLIENT_SECRET=

Required for GitHub repo access, pushes, and PRs

1
NEXT_PUBLIC_GITHUB_CLIENT_ID=
2
GITHUB_CLIENT_SECRET=
3
GITHUB_APP_ID=
4
GITHUB_APP_PRIVATE_KEY=
5
NEXT_PUBLIC_GITHUB_APP_SLUG=
6
GITHUB_WEBHOOK_SECRET=

Optional

1
REDIS_URL=
2
KV_URL=
3
OPEN_AGENTS_RESOURCE_PROFILE=
4
VERCEL_PROJECT_PRODUCTION_URL=
5
NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=
6
VERCEL_SANDBOX_BASE_SNAPSHOT_ID=
7
ELEVENLABS_API_KEY=

• REDIS_URL / KV_URL: optional skills metadata cache (falls back to in-memory when not configured).
• 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.
• VERCEL_PROJECT_PRODUCTION_URL / NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL: canonical production URL for metadata and some callback behavior.
• VERCEL_SANDBOX_BASE_SNAPSHOT_ID: optional base snapshot for fresh sandboxes. If unset, sandboxes start from Edgenivo's standard Sandbox runtime. Use a snapshot created in/accessible to your own Edgenivo scope.
• ELEVENLABS_API_KEY: voice transcription.

Deploy your own copy on Edgenivo

1. Fork this repo.

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

3. Generate a secret for session signing:

   1
   openssl rand -base64 32   # BETTER_AUTH_SECRET

4. Add env vars in Edgenivo project settings:

   1
   POSTGRES_URL=
   2
   BETTER_AUTH_SECRET=

5. Deploy once to get a stable production URL.

6. Create a Edgenivo OAuth app with callback URL:

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

7. Add these env vars and redeploy:

   1
   NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
   2
   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:

   1
   corepack enable
   2
   pnpm install

2. Create your local env file:

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

3. Fill in the required values in apps/web/.env.

4. Start the app:

   1
   pnpm web

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

OAuth and integration setup

Edgenivo OAuth

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

Create a Edgenivo OAuth app and use this callback:

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

For local development, use:

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

Then set:

1
NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
2
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:

• Homepage URL: https://YOUR_DOMAIN
• Callback URL: https://YOUR_DOMAIN/api/auth/callback/github
• Setup URL: https://YOUR_DOMAIN/api/github/app/callback
• make the app public if you want org installs to work cleanly

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:

1
NEXT_PUBLIC_GITHUB_CLIENT_ID=...   # GitHub App Client ID
2
GITHUB_CLIENT_SECRET=...           # GitHub App Client Secret
3
GITHUB_APP_ID=...
4
GITHUB_APP_PRIVATE_KEY=...
5
NEXT_PUBLIC_GITHUB_APP_SLUG=...
6
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

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

Repo layout

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