Vyspec CLI

The Vyspec CLI is a thin, customer-operated browser executor. It runs on a developer or CI machine, opens the customer’s local application, captures bounded browser observations, and executes typed actions returned by the Vyspec API.

The runner does not contain the model provider key, private agent prompts, QA orchestration, or licensing authority. Those remain in the Vyspec API. Treat the runner as inspectable and tamperable because it runs on the customer’s machine.

Local setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Set the local application port in the repository's ignored .env:

VSY_APP_PORT=3000

Then connect that Git repository to an existing Vyspec Project:

vsy init

vsy init checks for the Chromium build required by the installed CLI and offers to download it when it is missing. You may defer that download and run vsy install-browser later. CI should keep installing the browser explicitly before vsy run.

The CLI opens Vyspec in the browser and asks the signed-in user to select and authorize one Project. When origin points to GitHub, GitLab, or Bitbucket, Vyspec detects the provider and continues that same browser tab directly into the repository connection flow. Repositories without a supported remote keep the normal local authorization flow. The CLI then adds an owner-readable Project API key to that .env:

VSY_PROJECT_API_KEY=revocable-project-api-key
VSY_HEADLESS=false

The Project API key is the only Vyspec credential accepted by the runner. Never put an OpenAI, Browserbase, AWS, or private Vyspec model credential in this file.

Running vsy init again reuses a valid connection. Use vsy init --reauthorize to replace it. Then run the agent from that repository with vsy run --profile <run-profile-id>.

Commands

vsy --version
vsy install-browser
vsy init
vsy connect
vsy doctor
vsy run
vsy run --profile <run-profile-id>
vsy run --profile <run-profile-id> --headless

Interactive local runs ask whether to use a visible or headless browser. Pass --headless to skip that choice and keep it hidden. CI always uses a headless browser.

In a terminal, vsy run finds the nearest .env inside the current Git repository, authenticates its Project API key, displays that Project and directory, and lists only the active Run Profiles belonging to that Project. Local runs use VSY_APP_PORT from that repository's .env. Supplying --profile skips profile selection.

For ad hoc QA without creating a saved Profile, supply instructions directly:

vsy run --instructions "Verify the corrected checkout total"
vsy run --instructions-file qa.md
vsy run --instructions-file qa.md \
  --session-profile <session-profile-id> \
  --start-path /account/records/42

Direct Runs start at / in a fresh desktop Chrome session with balanced execution defaults. If the page or record belongs to a signed-in user, pass an automatic-login Session Profile and the origin-relative page to open after login. Select the Session Profile under the Project's Configuration area; its ID is the final segment of that Profile's page URL. Add that Session Profile's required VSY_... credential variables to the repository .env for local runs or the provider's secret store for CI. Credential values stay on the runner machine and are never sent to the Vyspec API or model.

vsy connect keeps the initialized repository visible to the Vyspec web application while that terminal remains open. It authenticates with the repository's Project API key, reports whether the configured loopback application is reachable, and disconnects cleanly on Ctrl+C. This presence command does not start a Run by itself.

CI contract

The CLI enters CI mode when CI, GITHUB_ACTIONS, or GITLAB_CI is explicitly set to true, 1, yes, or on. Values such as CI=false do not enable CI behavior. Bitbucket Pipelines is detected from its numeric BITBUCKET_BUILD_NUMBER variable.

CI execution has one deterministic contract:

• VSY_PROJECT_API_KEY must contain the Project API key supplied through the CI secret store.
• vsy run must receive either --profile <run-profile-id>, --instructions, or --instructions-file; saved Profile IDs must belong to the connected Project.
• Session Profile credential names must exist in the CI environment when a saved or direct Run selects an automatic-login Session Profile.
• The customer application must listen on loopback port 3000; VSY_APP_PORT is ignored in CI.
• The browser is always headless, profile selection is never interactive, and vsy init is rejected.
• Every Run creates a new isolated browser context. Automatic-login Profiles require credentials from the repository or CI environment, and the runner executes the configured login flow before QA.

The GitHub Action owns CLI installation, the hosted API endpoint, and invocation. Customers provide only their Project API key, selected Run Profile, application process, and profile-specific test credentials.

The supported wrapper is published separately as the public vyspec-action repository. Invoke its released major version after the application has been started in an earlier workflow step:

- name: Run Vyspec QA
  uses: Vyspec/vyspec-action@v1
  with:
    github-token: ${{ github.token }}
    project-api-key: ${{ secrets.VSY_PROJECT_API_KEY }}
    run-profile-id: 123e4567-e89b-42d3-a456-426614174000

The action currently targets GitHub-hosted Ubuntu runners. It installs Python 3.12, its pinned public CLI release, and the CLI-pinned Playwright Chromium build. It waits up to 120 seconds for the application on port 3000, preserves the CLI's original operational and cancellation status, and creates or updates one pull-request report.

The runner always connects to http://127.0.0.1:<port>. It does not accept an arbitrary target hostname, so QA can only operate against an application running on the same developer or CI machine.

vsy run exits with 0 whenever execution completes and produces a definitive passed or failed QA verdict. A failed QA verdict is reported in the terminal, result file, and pull-request comment; it is not an operational process failure. Exit 2 means execution could not produce a definitive result. User or CI cancellation exits with 130. SIGTERM is normalized to the same cancellation path so the runner closes the browser and makes a best-effort failure update before exiting.

The project token starts a run and is immediately exchanged for a short-lived credential scoped to that exact run attempt. The server returns the saved run profile's start URL, host allowlist, browser preset, and step limit. For each observation the runner requests a short-lived upload grant, uploads the PNG directly to storage, and sends only the artifact reference to:

POST /api/v1/runner/runs/{runId}/turn

The server returns a bounded batch of native computer actions. The runner executes only supported actions, refuses navigation outside the configured loopback host, caps screenshots, and never executes arbitrary JavaScript returned by the server.

Trust boundary

Customer machine                         Vyspec API
────────────────                         ──────────────
Chromium + local app
Screenshots only          ────────────►  License/auth checks
Native computer actions   ◄────────────  Private prompts + Luna
Loopback host enforcement                 Run state and workflow

The runner intentionally has no SQS, ECS, AWS, Browserbase, Cloudflare, or direct OpenAI integration. Each model turn is a short authenticated API request; there is no hosted worker process to manage.

Operational error reporting

The CLI reports operational crashes to Vyspec's Sentry project so broken releases and recurring runner failures can be diagnosed. Reports include the CLI version, command name, CI/local source, exception type, and sanitized stack locations. They exclude command arguments, environment values, credentials, emails, prompts, screenshots, browser contents, request bodies, URLs, and local paths.

Set VSY_TELEMETRY_DISABLED=1 to disable CLI error reporting.