Open Agents

Open Agents is an open-source reference application for building and running background coding agents on Vercel. It follows a three-layer architecture designed to decouple agent execution from the execution environment:

1. Web App: Handles authentication, sessions, chat, and the streaming UI.
2. Agent Workflow: Runs as a durable workflow on Vercel.
3. Sandbox VM: The execution environment containing the filesystem, shell, git, dev servers, and preview ports.

Key Design Principle: The agent does not run inside the VM. It runs outside the sandbox and interacts with it via tools (file reads, edits, search, shell commands). This allows agent execution to be independent of request lifecycles and enables the sandbox to hibernate/resume independently.

The bash tool in packages/agent enforces safety through a default approval model. It distinguishes between safe read-only operations and operations that could modify the system or escape the sandbox.

Approval Logic:

1. Auto-approve: Commands that are read-only, match known safe prefixes, and stay within the sandbox working directory.
2. Require Approval:
   • Commands that attempt to access paths outside the sandbox working directory.
   • Commands matching dangerous patterns (e.g., destructive actions).
   • Any unknown command patterns.

The sandbox moves through several states managed by a lifecycle workflow:

1. provisioning: The initial state when a sandbox is being created.
2. active: The sandbox is running. It tracks lastActivityAt and hibernateAfter (inactivity window) and sandboxExpiresAt (hard timeout).
3. hibernating: Triggered when inactivity or hard timeout is reached. The system performs a snapshot() and stops the sandbox.
4. hibernated (paused): The state after hibernation. The user can manually trigger a restore (resume).

Transitions:

• Active → Active: User sends a message (refreshes activity via chat route).
• Active → Hibernating: No activity for I minutes OR hard timeout T+H reached.
• Hibernated → Active: User clicks "Resume" (triggers snapshot restore).

Authentication is managed via Better Auth. To enable Vercel OAuth, create a Vercel OAuth app with the following callback settings:

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

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

Then, configure these environment variables:

• NEXT_PUBLIC_VERCEL_APP_CLIENT_ID
• VERCEL_APP_CLIENT_SECRET

To run Open Agents locally, follow these steps:

1. Install Dependencies:

   corepack enable
   pnpm install

2. Configure Environment:

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

   Fill in the required values in apps/web/.env.
3. Run the Application:

   pnpm web

Note: If you have a linked Vercel project, you can pull environment variables using vc env pull.

The client-side UI synchronizes with the server's lifecycle state by polling GET /api/sandbox/status every 15 seconds. The UI determines the status chip display as follows:

• Active: Server state is active AND local timeout (calculated from createdAt + timeout) has not expired.
• Paused: Server state is hibernated, or there is no runtime sandbox state with an available snapshot.
• No sandbox: No runtime state and no snapshot exists.

A forced status sync is triggered immediately after a chat completion (streaming → ready) to ensure the UI reflects the server state quickly.

Open Agents uses a GitHub App (rather than a standard OAuth app) to provide installation-based repository access and OAuth credentials.

GitHub App Configuration:

• Homepage URL: https://YOUR_DOMAIN (or http://localhost:3000 for local)
• Callback URL: https://YOUR_DOMAIN/api/auth/callback/github (or http://localhost:3000/api/auth/callback/github for local)
• Setup URL: https://YOUR_DOMAIN/api/github/app/callback (or http://localhost:3000/api/github/app/callback for local)

Required Environment Variables:

• NEXT_PUBLIC_GITHUB_CLIENT_ID (GitHub App Client ID)
• GITHUB_CLIENT_SECRET (GitHub App Client Secret)
• GITHUB_APP_ID
• GITHUB_APP_PRIVATE_KEY (Can be PEM contents with escaped newlines or base64-encoded PEM)
• NEXT_PUBLIC_GITHUB_APP_SLUG
• GITHUB_WEBHOOK_SECRET

To improve UX and reduce costs, the system uses a 'lazy' approach to sandbox provisioning. Instead of creating a sandbox immediately upon session creation, the sandbox is provisioned only when the first message is sent or an explicit resume action is taken. This separates durable session state from the ephemeral runtime sandbox.

### Recommended Workflow
1. Create a session.
2. Navigate to the chat immediately.
3. Let the user send the first message without waiting for sandbox creation.
4. On first send:
   - reuse an already-active sandbox if one exists
   - otherwise reconnect to an existing runtime if if possible
   - otherwise restore from snapshot if appropriate
   - otherwise create a new sandbox
5. Persist the resulting runtime state (`sandboxId`, expiry, branch, lifecycle data).
6. Start the agent turn.
7. Reuse that sandbox for later messages.