Local Caching

Local Cache writes action results to your filesystem so they persist across script runs. It works in both LOCAL and BROWSERBASE environments. When you specify a cacheDir, Stagehand saves every action and agent step to a local file on first run, then replays those cached actions on subsequent runs with no LLM calls, no token cost, and no network round-trip to Browserbase. This is especially useful for:

CI/CD pipelines - commit your cache directory to version control for consistent, deterministic runs across environments
Local development - iterate on automations without burning tokens on repeated runs
Cross-machine sharing - cache files are portable and can be shared across machines

Local caching can be used independently or together with Server Caching.

Caching with `act()`

Cache actions from act() by specifying a cache directory in your Stagehand constructor.

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "act-cache", // Specify a cache directory
});

await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/iframe-same-proc-scroll/");

// First run: uses LLM inference and caches
// Subsequent runs: reuses cached action
await stagehand.act("scroll to the bottom of the iframe");

// Variables work with caching too
await stagehand.act("fill the username field with %username%", {
  variables: {
    username: "fakeUsername",
  },
});

Caching with `agent()`

Cache agent actions (including Computer Use Agent actions) the same way. Just specify a cacheDir. The cache key is automatically generated based on the instruction, start URL, agent execution options, and agent configuration. Subsequent runs with the same parameters will reuse cached actions.

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "agent-cache", // Specify a cache directory
});

await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/drag-drop/");

const agent = stagehand.agent({
  mode: "cua",
  model: "google/gemini-3-flash-preview",
  systemPrompt: "You are a helpful assistant that can use a web browser.",
});

await page.goto("https://play2048.co/");

// First run: uses LLM inference and caches
// Subsequent runs: reuses cached actions
const result = await agent.execute({
  instruction: "play a game of 2048",
  maxSteps: 20,
});

console.log(JSON.stringify(result, null, 2));

Cache Directory Organization

You can organize your caches by using different directory names for different workflows:

// Separate caches for different parts of your automation
const loginStagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "cache/login-flow"
});

const checkoutStagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "cache/checkout-flow"
});

const dataExtractionStagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "cache/data-extraction"
});

Best Practices

Use descriptive cache directories

Organize caches by workflow or feature for easier management:

// Good: descriptive cache names
cacheDir: "cache/login-actions"
cacheDir: "cache/search-actions"
cacheDir: "cache/form-submissions"

// Avoid: generic cache names
cacheDir: "cache"
cacheDir: "my-cache"

Clear cache when DOM changes

If the website structure changes significantly, clear your cache directory to force fresh inference:

rm -rf cache/login-actions

Or programmatically:

import { rmSync } from 'fs';

// Clear cache before running if needed
if (shouldClearCache) {
  rmSync('cache/login-actions', { recursive: true, force: true });
}

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  cacheDir: "cache/login-actions"
});

Commit cache for CI/CD

Consider committing your cache directory to version control for consistent behavior across environments:

# .gitignore
# Don't ignore cache directories
!cache/

This ensures your CI/CD pipelines use the same cached actions without needing to run inference on first execution.

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Caching with `act()`

Caching with `agent()`

Cache Directory Organization

Best Practices

​Caching with act()

​Caching with agent()

​Cache Directory Organization

​Best Practices

Caching with `act()`

Caching with `agent()`

Cache Directory Organization

Best Practices