Skip to main content
For most studies ish reaches the artifact directly. You point an iteration at a public URL, attach a file, or wire up a chatbot endpoint, and the simulation runs. Site access is for the case where the URL is not reachable as-is: a staging gate, a preview link behind a token, a page that only renders after a login. Site access lives on a site inside your workspace. A site is one web site or one native app, and it holds its own access. You configure how ish should get past a site’s gate once, and every study whose URL (or app) belongs to that site reuses it. A workspace can hold several sites, each with its own access. Site access is an interactive-study concern, not a media or chatbot one.

​
When you need it

An interactive study sends simulated people through a real cloud browser pointed at the iteration’s URL. If that browser cannot load the page, the simulation has nothing to react to. Site access closes that gap for the three common ways a URL is gated:
  • A staging site behind HTTP basic auth (the browser dialog that wants a username and password before any page loads).
  • A preview link gated on a session cookie: a Vercel preview, a Lovable preview, anything that checks for a token cookie and otherwise shows a wall.
  • A site behind a login form: a real sign-in page the participant fills in and submits to reach the part of the product under test.
If the URL is already public, you do not need site access at all. A study against a live marketing page or a published prototype just runs.

​
Public versus gated

ish does not require you to declare that a public site is public. The default is that no credentials are attached and the browser loads the URL as any anonymous visitor would. The one thing the public method adds is an explicit affirmation: you are telling ish, on the record, that this site needs nothing. Tools and UI read that flag to stop nudging you about credentials on a site you have already confirmed is open. That makes “public” a real, separate state, not the absence of configuration: The two are mutually exclusive by design: a site you just handed a password to is not one you are also calling open. Saving any credential (basic auth, cookie, or login) withdraws the site’s public affirmation, and affirming a site public is refused while it still holds a credential.

​
The four methods

Each method matches how the gate actually works. Pick the one that describes the wall in front of your URL. Every method belongs to one site.
HTTP basic auth: the credentials the browser sends before any page renders, the username and password behind the native browser prompt. Configured as a username plus a password. ish presents them to the origin the run opens, so the page loads.
Username and password for a real sign-in form. Unlike basic auth and cookie, these are not handed to the browser up front: the participant types them into the site’s own login page if it meets one during the task, the way a real person signs in. The login belongs to its site, so only runs on that site see it. It is the only method a native app site takes.
Not a credential. An affirmation that the site needs no access at all, which silences the prompt asking whether it does.

​
Sites and hosts

A site is a place your studies go: a web site, identified by its host, or a native app, identified by its app artifact (the bundle id or path the iteration stores). A site is created the first time you give it access, and is named after its host or app. A web site answers on one or more hosts. Its first host is its address; add others when the same site answers somewhere else, for example shop.se beside shop.com, a sign-in subdomain such as auth.shop.com, or localhost:3000 for a local build. www and the bare domain are already the same host, so you never add both. A host belongs to one site only. A study’s URL picks its site by host, and the run uses that site’s access and never another site’s:
  • Basic auth and the cookie go to exactly one origin: the one the run opens. That is the study URL’s origin, or, for a localhost site, the tunnel that ish connect opens for it, so a local site keeps its access through the tunnel. They are never sent to every host of the site; hosts only decide which site a study belongs to.
  • A run on a host outside its site gets none of that site’s access, and dispatch warns.
  • A study on a host no site covers runs with no access. When other sites in the workspace do hold access, ish study run warns at dispatch, which is the tell for a typo or a host you have not added yet.
You rarely have to spell the site out. Name it by URL (--origin, created on first use), by name (--site), or by app (--app); with none of them, ish uses the site for the workspace’s base_url. Clearing access and editing hosts always need the site named. A write that makes a new site says so (created: true), and lists the other sites that already hold access, so a mistyped origin shows up straight away instead of as a run that silently loads without credentials.

​
Where the credentials live

Credentials (passwords and cookie values) are stored encrypted at rest. Neither the CLI nor the MCP server ever reads one back: both report only which methods each site has. A site’s hosts are ordinary workspace data, so a status read lists every site with its hosts and methods, plus the hosts your browser studies target that no site covers yet.
The old secret names BASIC_AUTH_*, SESSION_COOKIE_*, and LOGIN_* stay reserved. The plain secret commands refuse them and point you here. Always go through the site-access surface.

​
Reading and changing it

Both developer surfaces expose the same configure verbs, a hosts edit, a status read, and a clear. The status read never returns a secret value. The example below shows the parity across surfaces, not a procedure to follow in order.
Keep secrets out of your shell history. On the CLI, pass - for --password or --value and pipe the value on stdin: printf %s "$STAGING_PW" | ish workspace site-access basic-auth --username alice --password -.

​
Where to go next

Workspaces

The scope your sites belong to, and how base_url names the default site.

Iterations

The unit that carries the URL a run targets. Site access decides whether ish can reach it.

site_access tools

Every parameter and return shape for site_access_get, site_access_set, and site_access_clear.

workspace commands

Full flags for ish workspace site-access and the rest of the workspace surface.