Browser-Use Template Library

Template collection for the browser-use CLI init command.

Structure

.
├── templates.json               # Template registry and metadata
├── gitignore.template           # Shared .gitignore for complex templates
├── AGENTS.md.template           # Shared AGENTS.md for coding agents (every template)
│
├── Simple Templates (single Python files)
├── default_template.py          # Example: Minimal setup
├── ...                          # See templates.json for complete list
│
└── Complex Templates (full project scaffolding)
    └── shopping/                # Example: E-commerce automation
        ├── main.py
        ├── launch_chrome_debug.py
        ├── README.md
        ├── pyproject.toml.template
        └── .env.example.template
    └── ...                      # See templates.json for complete list

For a complete list of all available templates, see templates.json.

Usage

This repository is used as a git submodule by the main browser-use repository.

Templates are loaded by the browser-use init CLI command:

uvx browser-use init --template default
uvx browser-use init --template shopping
uvx browser-use init --template job-application
uvx browser-use init --template agentmail

Browser Use Cloud starters

cloud-starters/ has small examples that run on Browser Use Cloud browsers ($0.02 per browser-hour, billed per second): Playwright over CDP (TypeScript and Python), Puppeteer over CDP (TypeScript), the browser-use Agent with Browser(use_cloud=True), the hosted v4 agent API, 50 parallel browsers, a password + TOTP 2FA login saved to a profile, and scraping through proxies.

uvx browser-use init --template cloud-playwright

The two TypeScript starters are plain npm projects in the same folder (not installed by init, which writes Python files).

Testing Templates Locally

To test your templates before submitting a PR, you can modify the browser-use CLI to use your fork/branch:

1. Fork this repository and create a branch with your changes
2. Clone the browser-use repository and locate browser_use/init_cmd.py
3. Find the TEMPLATE_REPO_URL variable (line 27, typically set to https://raw.githubusercontent.com/browser-use/template-library/main)
4. Replace it with your fork and branch: https://raw.githubusercontent.com/YOUR_USERNAME/template-library/YOUR_BRANCH
5. From the browser-use directory, test your template:

   # Interactive mode (select from list)
   python -m browser_use.init_cmd
   
   # Direct template selection
   python -m browser_use.init_cmd --template your-template --output test.py

This allows you to verify:

• ✓ Template files are copied correctly
• ✓ next_steps display properly
• ✓ File permissions are set (executable files)
• ✓ Binary files work (PDFs, images, etc.)
• ✓ Variable substitution works ({template}, {output})

Adding New Templates

Every template ships AGENTS.md.template as AGENTS.md, so coding agents that read AGENTS.md (Codex, Cursor and others) see how to run locally vs on Browser Use Cloud. Add this to the template's files array:

{
    "source": "AGENTS.md.template",
    "dest": "AGENTS.md"
}

Simple Template (Single File)

1. Create your template file in the root directory:

   # Example: my_template.py

2. Add an entry to templates.json:

   "my-template": {
       "file": "my_template.py",
       "description": "Brief description of what this template does"
   }

Complex Template (Multiple Files)

1. Create a new directory with your template files:

   mkdir my-template/
   # Add files: main.py, README.md, pyproject.toml.template, .env.example.template

2. Add a complete entry to templates.json:

   "my-template": {
       "file": "my-template/main.py",
       "description": "Brief description of what this template does",
       "files": [
           {
               "source": "my-template/main.py",
               "dest": "main.py"
           },
           {
               "source": "my-template/pyproject.toml.template",
               "dest": "pyproject.toml"
           },
           {
               "source": "gitignore.template",
               "dest": ".gitignore"
           },
           {
               "source": "my-template/.env.example.template",
               "dest": ".env.example"
           },
           {
               "source": "my-template/README.md",
               "dest": "README.md"
           }
       ],
       "next_steps": [
           {
               "title": "Navigate to project directory",
               "commands": ["cd {template}"]
           },
           {
               "title": "Set up your API key",
               "commands": [
                   "cp .env.example .env",
                   "# Edit .env and add your API_KEY"
               ],
               "note": "(Get your key at https://example.com/api-keys)"
           },
           {
               "title": "Install dependencies",
               "commands": ["uv sync"]
           },
           {
               "title": "Run the script",
               "commands": ["uv run {output}"]
           },
           {
               "footer": "📖 See README.md for detailed instructions"
           }
       ]
   }

Template Structure Reference

templates.json Schema

Each template entry in templates.json supports the following fields:

Required Fields

Field	Type	Description
file	string	Path to the main template file (e.g., "my_template.py" or "my-template/main.py")
description	string	Short description shown in CLI (1-2 sentences)

Optional Fields

Field	Type	Description
files	array	List of files to copy for complex templates (see File Specification below)
next_steps	array	Custom post-installation instructions (see Next Steps below)
featured	boolean	Mark template as featured (shown prominently in CLI)
author	object	Template author information (see Author Information below)

File Specification

Each entry in the files array:

{
    "source": "path/to/source/file",
    "dest": "destination/filename",
    "binary": true,      // Optional: true for PDFs, images, etc. (default: false)
    "executable": true   // Optional: true to set +x permission (default: false)
}

Examples:

// Text file
{
    "source": "my-template/main.py",
    "dest": "main.py"
}

// Binary file (PDF, image, etc.)
{
    "source": "my-template/resume.pdf",
    "dest": "resume.pdf",
    "binary": true
}

// Executable script
{
    "source": "my-template/launch_script.py",
    "dest": "launch_script.py",
    "executable": true
}

Next Steps Configuration

Each entry in the next_steps array can be:

Regular step:

{
    "title": "Step title",
    "commands": ["command1", "command2"],
    "note": "(Optional helpful note)"
}

Footer (shown at the end):

{
    "footer": "Final message with helpful links or tips"
}

Variable Substitution:

The CLI automatically replaces these variables in commands:

• {template} → Template name (e.g., "shopping")
• {output} → Output filename specified by user

Example:

{
    "title": "Run your script",
    "commands": ["cd {template} && uv run {output}"]
}
// Becomes: "cd shopping && uv run my_bot"

Author Information

The optional author object allows you to add attribution to your template:

{
    "name": "Jane Smith",                          // Optional: Author name or username
    "github_profile": "https://github.com/janesmith",  // Optional: GitHub profile URL
    "last_modified_date": "2025-11-12"             // Optional: Last update date (YYYY-MM-DD)
}

Example:

"my-template": {
    "file": "my-template/main.py",
    "description": "Advanced web scraping with AI",
    "files": [...],
    "next_steps": [...],
    "author": {
        "name": "Jane Smith",
        "github_profile": "https://github.com/janesmith",
        "last_modified_date": "2025-11-12"
    }
}

Notes:

• All fields within author are optional
• Default templates (default, advanced, tools) typically don't need author information
• Community-contributed templates should include author information when possible
• The last_modified_date should be updated whenever the template is significantly changed

Featured Templates

The optional featured boolean flag marks templates for prominent display in the CLI's template selector UI.

{
    "featured": true
}

Example:

"shopping": {
    "file": "shopping/main.py",
    "description": "E-commerce automation with structured output",
    "featured": true,
    "files": [...],
    "next_steps": [...]
}

Notes:

• Featured templates are shown in a dedicated "Featured Templates" section in the CLI
• Default templates (default, advanced, tools) are always shown separately and don't need the featured flag
• Use this to highlight high-quality, well-maintained, or popular community templates
• Currently featured templates: shopping, job-application, agentmail, llm-arena, slack, all-openai-jobs

Best Practices

1. README.md: Include detailed setup instructions, customization tips, and troubleshooting
2. .env.example.template: Document all required environment variables with example values
3. pyproject.toml.template: Pin dependencies to working versions
4. Description: Be specific about what the template does (e.g., "E-commerce automation with Instacart" vs "Shopping bot")
5. next_steps: Provide clear, ordered instructions that work out of the box

Contributing

Workflow

1. Fork this repository
2. Create a new branch for your template
3. Add your template files and update templates.json
4. Submit a PR with:
   • Clear description of what the template does
   • Use case or problem it solves
   • Any special requirements or dependencies

Quality Checklist

• Template code is tested and working
• README.md includes clear setup instructions
• .env.example.template documents all required API keys
• pyproject.toml.template has all necessary dependencies
• next_steps guide users through setup correctly
• Template name is descriptive and follows kebab-case convention

License

Same as browser-use