Skip to content

Getting started

This guide takes you from download to your first reviewed run on the local desktop workbench. Available

The workbench is the one mode you can use today. Cross-party deployment, attested compute, enterprise identity, and hosted/embedded agents are Built or Planned — see the Roadmap & status table, which is the single source of truth for what's shipped.

Read this first: where your work goes

GaugeWright orchestrates locally, but it does not run a model locally. The workbench runs on your machine; the agent's reasoning is performed by a third-party LLM provider you configure, so during a run your prompts and the in-scope context are sent to that provider over the network. The provider sees that plaintext. Its retention and training terms are the provider's, not GaugeWright's.

This is the one counterintuitive truth to internalise before your first run. Full detail: Where your data goes. Removing the provider from the trust boundary (confidential inference) is Planned, not available today.

Step 0 — Pick a provider and place your credentials

Do this before you create anything. Without a working provider credential, a run cannot reach a model and will fail.

0.1 Choose a provider

The agent harness inside the workbench calls a standard LLM API. Supported providers today are the ones the harness speaks to natively:

Provider What you supply
OpenAI OAuth sign-in or an API key
Anthropic OAuth sign-in or an API key
Azure OpenAI endpoint + API key (enterprise / contracted) — the option to reach for when data may not go to a third-party model without a contract/DPA (see warning below)

Bring your own credentials

GaugeWright does not resell inference. You authenticate your own account, so the LLM relationship — and the provider's data terms — is yours: the provider is your subprocessor, not GaugeWright's. This is the BYO-credentials model.

Choose a provider you're allowed to send this data to

Because prompts and in-scope context leave your machine for the provider, if your data may not go to a third-party model, use a provider you have a contract/DPA with (e.g. Azure OpenAI with a no-training term), or wait for confidential inference. Planned

0.2 Place the credential

The credential is an LLM provider credential (used by the runtime when a run executes) — the agent harness presents it to the provider during a run. You have two ways to provide it:

The simplest path: link your OpenAI or Anthropic account from the workbench's provider settings. The token is encrypted at rest on the local desktop (AES-256-GCM) so it can be used by a run without sitting in plaintext on disk. Available Live multi-party (KMS-backed) encryption is Built. See Roadmap & status for the current state of KMS-backed encryption.

If you prefer a key, set it in the environment GaugeWright launches in, using the provider's standard variable:

  • OpenAI: OPENAI_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • Azure OpenAI: AZURE_OPENAI_API_KEY plus your endpoint

Each archetype records its model/provider choice in its .agent-config.json (you'll see this in Step 4). For your first run, don't pin a specific model — let the harness resolve the default for the provider you authenticated. Pinning an exact model that your credential isn't entitled to is the most common first-run failure.

Step 1 — Download and install

Supported platforms: macOS 12+ (Apple Silicon or Intel), Windows 10+ (64-bit), or a recent x86-64 Linux with WebKitGTK and git installed.

Which platform to run untrusted methods on

The kernel-enforced method-isolation sandbox is Available on Linux and macOS; Windows method-isolation is Planned. Until it ships, run untrusted methods on Linux/macOS. Exact per-build OS and runtime requirements ship with each build on the download page — see Roadmap & status for what is guaranteed.

Builds are currently unsigned

Code-signing and notarization are Not implemented today, so desktop builds are unsigned. Your OS will warn on first launch. The per-OS override is below — this is expected, not a sign of a bad download.

Get the build for your platform from gaugewright.com/download, then:

  1. Open the .dmg and drag GaugeWright to Applications.
  2. On first launch, Gatekeeper will block it. Right-click the app icon → Open, then confirm Open in the dialog. (Double-clicking will only offer "Move to Trash" — you must use the right-click menu.)
  1. Run the .msi installer.
  2. At the SmartScreen prompt, click More info → Run anyway.
  1. Either run the .AppImage (chmod +x it first) or install the .deb.
  2. Confirm git is installed (git --version) — the workbench uses git to store and version your workspace.

Step 2 — Create a project

A project is the home for one body of work — a trust and data boundary, not a folder. It holds the work's context, the agent placed on it, and (later) the people allowed to see it.

  1. From the workbench, create a project and give it a name.

A project opens with a default archetype already installed as its default placement, so you can run immediately without authoring anything. (Building your own agent is Step 4, optional for a first run.)

Step 3 — Add your context

Attach the files or folder the agent should work with. These become context resources, addressed by handle.

  1. Attach a local folder as the working context.
  2. The folder becomes the placement's git workspace (its main branch is the settled state).

A reference is not access

Attaching context records intent; it does not hand the agent the data. A handle conveys no read on its own — the boundary decides what's actually revealed during a run, under an explicit grant, and fails closed if a grant is missing. Available See How GaugeWright protects your work.

Step 4 — (Optional) Define your own agent

For a first run you can skip this and use the default archetype. To build your own, open an edit chat rooted on the archetype and edit its definition surface:

  • .pi/SYSTEM.md — the agent's persona / system prompt.
  • AGENTS.md — working conventions / instructions.
  • .agent-config.json — model/provider selection and protection posture.

Edit chat vs. work chat

Only an edit chat (rooted on an archetype) can change these files. A work chat (rooted on a placement, Step 5) can read the method but never write it — so a running agent can't rewrite its own instructions. This is enforced by an OS kernel sandbox, not convention. Available (Linux/macOS); the Windows method-isolation sandbox is Planned.

Full authoring workflow: Build an agent.

Step 5 — Run a task and review the diff

This is the first reviewed run — the whole point of the guide.

  1. Open a work chat on the project's placement. Its identity shows its lineage as archetype · project (e.g. default · acme-report), so it's always clear which method is running and where.

  2. Type a concrete task, e.g.:

    Read notes.md and write a one-paragraph summary into summary.md.

  3. Watch it work. The run executes in an isolated worktree off main. Your prompt and the in-scope context are sent to your configured provider for inference — see Where your data goes.

  4. When the turn finishes, the workbench shows a diff — the proposed change to your workspace.
  5. Keep it (the diff merges to main) or discard it. Nothing is applied without your decision, and every run is recorded in the append-only history, so you can audit what happened and roll it back with git. Available

That's a complete reviewed run: point an agent at your files, give it a task, get a result you reviewed and chose to keep.

First-contact troubleshooting

macOS/Windows won't let me open the app

Expected — builds are unsigned (see Step 1). On macOS, right-click the app icon and choose Open (the double-click "Move to Trash" path won't offer the override). On Windows, click More info → Run anyway at the SmartScreen prompt. Code-signing is Not implemented today.

A run was denied / nothing happened

A denial usually means a missing grant, not a bug — the boundary fails closed, so if a required access grant is missing, stale, or uncertain, the action is refused rather than allowed on doubt. Available Check that the file the agent tried to read is attached as context (Step 3) and inside the project's workspace. See How GaugeWright protects your work.

The run failed to reach a model / authentication error

Re-check Step 0: the provider credential must be linked (OAuth) or its *_API_KEY set in the environment GaugeWright launched in. If you pinned a specific model in .agent-config.json, your credential may not be entitled to it — clear the model selection and let the provider's default resolve.

Can I keep my data fully on my machine?

Not for inference — there is no local model. Orchestration and storage are local, but reasoning goes to your configured provider. If that's not acceptable, use a provider you've contracted, or wait for confidential inference (Planned). Detail: Where your data goes.

Can the agent reach the network or read files outside the project?

The boundary's egress chokepoint and consent rules are always on, but the workbench's network-egress default is open per project for low-friction first runs — a non-isolated project's containment ceiling is lower. You can opt a project into kernel-enforced network isolation (Linux/macOS). Available (Linux/macOS)

Next steps