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 the workspace. You configure how ish should get past the gate once, and every study in that workspace whose URL matches reuses it. It applies to URLs ish loads in a real browser, so it 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 origin needs nothing. Tools and UI read that flag to stop nudging you about credentials on a URL you have already confirmed is open. That makes “public” a real, separate state, not the absence of configuration:
StateWhat it meansWhat ish does
Nothing configuredNo credentials, no affirmationLoads the URL anonymously; may still prompt “does this need access?”
Public affirmedYou confirmed the origin is openLoads anonymously; stops prompting for that origin
A method configuredbasic auth, cookie, or login is setApplies that method when a study targets the matching origin
Saving any credential (basic auth, cookie, or login) clears a prior public affirmation. The two are mutually exclusive by design: an origin you just handed a password to is not one you are also calling open.

​
The four methods

Each method matches how the gate actually works. Pick the one that describes the wall in front of your URL.
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, bound to an origin. ish presents them to the matching origin 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 and submits it, the way a real person signs in. Not bound to an origin, because the login happens wherever the study sends the participant.
Not a credential. An affirmation that the origin needs no access at all, which silences the prompt asking whether it does. Bound to an origin like the other URL-based methods.

​
How an origin gets matched

Three of the four methods (basic auth, session cookie, and public) bind to an origin: the bare https://host form of a URL, scheme and host only, no path. When a study runs against a URL, ish checks whether a configured method binds to that URL’s origin and applies it. The login method is the exception, since it has no fixed origin to bind to; the participant signs in wherever the study takes them. You do not have to spell out the origin every time. If you leave it off, ish binds to the workspace’s base_url. So a workspace whose base_url is set to your staging host can attach basic auth with no origin argument, and it binds to that host. If neither an explicit origin nor a base_url is available, the call fails and tells you to pass one or set the workspace base_url first. ish never guesses the origin.
An origin is host-level, not path-level. Basic auth bound to https://staging.example.com covers every URL on that host. To gate a different host, configure that origin separately.

​
Where the credentials live

Site-access credentials are workspace-level secrets, stored encrypted at rest. Neither the CLI nor the MCP server ever reads a password or a cookie value back: both report only which methods are configured and the origin each is bound to. The origins are stored as plain values, not secrets, so a status read can show you the bound host to confirm you wired the right one. Because credentials sit on the workspace, every study in that workspace inherits them. Configure access to your staging host once, and every interactive study you point at that host reuses it without re-entering anything.
Site-access keys are reserved. Do not write or delete them through the plain secret commands: those reject the reserved keys and point you back here. The paired keys (a basic-auth username and its password, a cookie name and its value) are created together in one write, so the pairing invariant the backend enforces is never half-satisfied. Always go through the site-access surface.

​
Reading and changing it

Both developer surfaces expose the same four configure verbs plus a status read and a clear. The status read tells you which methods are set and the bound origin; it never returns a secret value. The example below shows the parity across surfaces, not a procedure to follow in order. 
# What is configured on the active workspace
ish workspace site-access status

# A staging gate (basic auth), bound to the workspace base_url
ish workspace site-access basic-auth --username alice --password hunter2

# A preview cookie (Vercel, Lovable, etc.)
ish workspace site-access cookie --name session --value abc123

# A login form the participant fills in
ish workspace site-access login --username demo --password demo

# Affirm a public origin to silence the prompt
ish workspace site-access affirm-public

# Clear one method, or everything
ish workspace site-access clear cookie
ish workspace site-access clear all
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

Where site-access credentials live, and how base_url supplies the default origin they bind to.

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.