Workspaces

A workspace is the durable unit of state in OpenSteer. If you want a browser profile, saved persist keys, saved extraction descriptors, or local discovery state to survive across runs, use a named workspace.

Where it lives

Named workspaces live here:

.opensteer/workspaces/<workspace>/

If you create Opensteer without workspace, it uses a temporary root in the system temp directory and cleans it up on close.

What gets stored

.opensteer/
  workspaces/
    <workspace>/
      workspace.json
      browser/
        manifest.json
        user-data/
      live/
        local.json
        cloud.json
      artifacts/
      traces/
      observations/
      registry/
        descriptors/
        interaction-traces/
        saved-network.sqlite

The important parts for most users are:

• browser/user-data/: persistent browser profile data
• live/: the active local or cloud session record
• registry/descriptors/: DOM persist keys and extraction descriptors
• registry/interaction-traces/: captured interaction traces
• registry/saved-network.sqlite: local and local-cloud saved request history used by network query and network detail

Managed cloud runtimes do not durably copy raw saved-network history into Convex. They keep raw discovery traffic in runtime-local scratch storage and only persist promoted registry artifacts such as descriptors and interaction traces.

How to choose a workspace

Use one workspace per durable automation context.

Examples:

• one workspace per target site
• one workspace per logged-in account
• one workspace per cloud agent

That keeps cookies, saved targets, and local discovery traffic scoped to the right context.

CLI and SDK usage

CLI:

opensteer open https://example.com --workspace demo

SDK:

const opensteer = new Opensteer({
  workspace: "demo",
  rootDir: process.cwd(),
});

Good defaults

• Add .opensteer/ to .gitignore.
• Reuse the same workspace when you want persistent login state or saved descriptors.
• Start a fresh workspace when a site has changed enough that old state is now misleading.