Skip to main content
A workspace is the top-level container in ish. Everything you create lives inside exactly one workspace: studies, asks, the people you generate, the sources you upload, secrets, and the references you compare against. Pick a workspace first, then operate within it. Most flows start there. The backend calls a workspace a “product”. The CLI and MCP server surface the agent-friendly name everywhere, so you never see “product” in a tool signature or a flag. Treat the two as the same thing if you read the underlying API.

​
What a workspace holds

One workspace is the scope for a body of related work, usually one product, site, or campaign. Inside it:
  • Studies and asks. A study is a persistent research artifact (a modality plus interview questions); an ask is a quick one-off question to a set of people. Both belong to one workspace.
  • People and sources. The people you generate and the sources you upload are visible to every study and ask in the same workspace, and only there.
  • A default base URL. base_url is the origin studies in the workspace target by default, and the origin site-access credentials bind to.
  • Site-access credentials. Login details, session cookies, or basic-auth pairs for a gated site, stored encrypted and scoped to this workspace.
A workspace carries an alias with the w- prefix (for example w-6ec) derived from its UUID. The alias is accepted anywhere a workspace ID is, so you rarely type a full UUID.

​
How you select one

ish resolves which workspace a command or tool acts on in a fixed order. The first source that is set wins.
1

An explicit flag or parameter

The CLI --workspace <id> flag, passed on the subcommand itself, or the workspace_id parameter on an MCP tool. A subcommand-level --workspace overrides one passed at the program root, so ish --workspace w-a study list --workspace w-b acts on w-b.
2

The program-root flag

ish --workspace <id> <command>, when the subcommand has no --workspace of its own.
3

The ISH_WORKSPACE environment variable

A workspace ID in ISH_WORKSPACE, for scripting without a flag on every call.
4

The saved active workspace

The workspace set with ish workspace use <id>, persisted in ~/.ish/config.json (override the config directory with ISH_HOME).
With none of these set, a workspace-scoped CLI command stops and tells you to run ish workspace use <id> or pass --workspace. It does not guess. On the MCP side there is no saved active workspace, so the agent passes workspace_id explicitly. Discover one by calling workspace_get with no id: it lists every accessible workspace, default first, then most recently active. See the workspace tools.

​
Caps and credits are scoped here

A workspace surfaces two independent quotas. They are easy to confuse, so keep them apart.

Entity caps

How many studies and how many custom people the plan lets you keep stored in each workspace. A create or generate call that would exceed the cap fails up front with a usage-limit error, before any simulation runs. A null cap means unlimited (paid tiers).

Simulation credits

The allowance each participant run draws from. Credits come with the subscription and are not charged per call, so once the pool has headroom you can run freely. Paid tiers refresh the pool monthly; the free tier gets a one-time signup grant; purchased credits never expire.
The entity caps are per-workspace: each workspace can hold up to the tier’s limit of studies and custom people independently, so a second workspace gets its own allotment. The cap value comes from the account’s plan, but it applies to each workspace on its own. Simulation credits are different: the pool is account-wide and shared across every workspace. Read both through a workspace with ish workspace info (CLI) or workspace_get with a workspace_id (MCP). Each returns the studies and people used against their caps plus the credit pool. Reading this before a create or a run lets an agent branch instead of firing a call it knows will be rejected.
In list mode, workspace_get tags each workspace with has_headroom, a cheap hint for whether it can still take a new study under the plan cap. Use it to pick a workspace to reuse without a second round-trip.

​
Creating and reusing

Create a workspace by name. On the CLI a base URL is optional at create time; on the MCP server workspace_create takes the same name, description, and base URL.
Creating blind is not safe on a full account. When the account is at its workspace cap, workspace_create returns a usage-limit error on the first call, which trips up a cold-start agent told to “make a fresh workspace, then run a study”. Inspect existing workspaces first and reuse one, or on the CLI use the idempotent ish workspace create --name <name> --ensure, which returns the existing workspace of that name instead of failing. The full saturated-account walkthrough is its own guide.

​
References: comparison workspaces

A reference is a workspace in disguise. When you want to benchmark your study against a competitor or an alternative version on the same panel, you create a reference under a parent workspace. At the data layer a reference is a workspace with a parent set and a product_type of reference; ish gives it its own reference namespace so you reason about it as a comparison target, not a top-level container. Because a reference is a workspace underneath, it shares the w- alias prefix. Any tool that takes a workspace ID accepts a reference alias and resolves it. The reverse is not true the other way you might expect: workspace_get lists only standard workspaces, never references, and reference_get lists only the references under a given parent. The benchmark flow is two steps. Create one reference per comparison target, then run a single benchmark that clones the study to every reference. Each clone gets its own iteration to fill in with that reference’s URL or media, so the same questions and panel run against each variant.
Deleting a workspace is the widest destructive action in ish. It cascades to every study, ask, person, source, secret, and reference inside it, and there is no soft archive. Deleting a reference cascades to its cloned studies and iterations. Both are irreversible. The CLI requires -y / --yes to delete in a non-interactive context. Full flags are in the workspace CLI reference and the reference tools.

Studies

The persistent research artifact every workspace holds, one of many.

Credits and limits

How the entity caps and the credit pool scoped here behave in full.

Benchmarks and references

Reference workspaces and the benchmark that clones a study across them.

workspace commands

Every CLI flag for workspace create, use, info, and delete.

workspace tools

The MCP workspace_get and workspace_create parameters and return shapes.