Skip to content
Jz Desk

Set up Jz Desk

Jz Desk ships without a model account of its own; it uses yours, and talks to OpenAI directly. The quickest way is to sign in with ChatGPT — three steps, no keys, no files to edit.

  1. Step 1

    Download and install

    Get the build for your computer from the download page. Everything is inside the app, so there is nothing else to install.

    macOS — Open the .dmg, drag Jz Desk into Applications, then open it from Applications.

    Windows — Run the installer. It is not code-signed yet, so Windows may say it protected your PC: click More info, then Run anyway. Open Jz Desk from the Start menu when it finishes.

  2. Step 2

    Sign in with ChatGPT

    On first launch, Jz Desk asks you to connect an account. Click “Login with your ChatGPT account”: your browser opens OpenAI’s sign-in page, and once you have signed in there, Jz Desk finishes signing in by itself. Usage counts against your ChatGPT plan; there is no API key to create.

  3. Step 3

    Pick a folder and ask

    Choose a folder for Jz Desk to work in and give it something to do — a question about what is there is enough. A reply means you are set up.

Use an API key instead

The app’s sign-in screen only offers ChatGPT. To use an OpenAI API key instead, save it to a file once, and Jz Desk skips the sign-in screen from then on. Do this when:

  • you go through a relay or proxy that hands out its own key and address, rather than reaching OpenAI directly;
  • your network cannot reach OpenAI’s sign-in page;
  • you would rather pay per token on an API account than use a ChatGPT plan.
  1. Step 1

    Open Jz Desk once, then quit

    Install it as above and open it. When the sign-in screen appears, quit: ⌘Q on macOS; on Windows, right-click the Jz Desk icon in the notification area of the taskbar and choose Quit — closing the window only hides it. That first launch creates the settings folder the next steps write to.

  2. Step 2

    Save your key

    Run this with your own key in place of sk-your-key. It replaces the whole sign-in file, ChatGPT sign-in included — use the command rather than adding the key to the file by hand, or Jz Desk keeps using the old ChatGPT sign-in. If it says there is no such folder, your settings date from before the folder was renamed: write .jz-code where the command says .jz-desk, here and in the next step.

    macOS — in Terminal:

    echo '{"auth_mode": "apikey", "OPENAI_API_KEY": "sk-your-key"}' > ~/.jz-desk/auth.json && chmod 600 ~/.jz-desk/auth.json

    Windows — in PowerShell:

    Set-Content -Encoding ascii "$HOME\.jz-desk\auth.json" '{"auth_mode": "apikey", "OPENAI_API_KEY": "sk-your-key"}'
  3. Step 3

    Using a relay or proxy? Point Jz Desk at it

    Skip this step if your key is an OpenAI key used directly. Otherwise, open the config file. Change the model_provider line at the top to the first excerpt below, and add the second excerpt at the very end of the file, with your relay’s address in base_url. If the file has an openai_base_url line, delete it.

    macOS — opens it in TextEdit:

    open -e ~/.jz-desk/config.toml

    Windows — opens it in Notepad:

    notepad "$HOME\.jz-desk\config.toml" 
    model_provider = "relay"
    [model_providers.relay]
name = "Relay"
base_url = "https://your-relay.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
  4. Step 4

    Open Jz Desk again

    It finds the key and goes straight in. Pick a folder and ask something to check it works.

The relay’s address usually ends in /v1, and it must speak the OpenAI Responses API — a relay that only offers chat completions will not work. Use the block above rather than openai_base_url: with openai_base_url, Jz Desk talks to the relay over WebSockets, which many relays accept and then never answer, so every message waits forever.

Switching between ChatGPT and a key

  • From ChatGPT to a key: steps 2 to 4 above. There is no need to reinstall.
  • From a key back to ChatGPT: quit Jz Desk, delete auth.json, and if you added a relay, set model_provider back to "openai". If the file has a model line, delete it too — the newest models offered to API keys are refused under ChatGPT sign-in. Open Jz Desk and it asks you to sign in again.
  • Uninstalling Jz Desk keeps your settings folder, so a reinstall picks up the sign-in and settings you had.

Everything lives in one folder: ~/.jz-desk on macOS, %USERPROFILE%\.jz-desk on Windows. auth.json holds the sign-in, config.toml the settings. A computer that had Jz Desk before the folder was renamed keeps the old one, .jz-code, and Jz Desk goes on using it.

Choosing a model

Pick the model in the app’s model picker; each way of signing in starts on its own default. Signed in with ChatGPT, you get the models OpenAI offers your account in Jz Desk; which ones depends on your ChatGPT plan, and may include only some of the GPT-6 family. With a key, you get the GPT-6 family, starting with GPT-6.1-Sol, and any other model your key or relay serves works by name. Smaller or older models will struggle with longer, multi-step tasks.

Choosing which models the picker lists

Signed in with ChatGPT, the picker shows the models OpenAI offers your account. With a key, it shows the GPT models Jz Desk ships with. To list your own — say, exactly what your relay serves — save a model list like this one as a JSON file. It replaces the whole list, under either sign-in, so include every model you want: slug is the model id your account or relay serves, visibility "list" puts it in the picker, and base_instructions is the standing instruction the model works under.

{
  "models": [
    {
      "slug": "gpt-6.1-sol",
      "display_name": "GPT-6.1-Sol",
      "description": "Through our relay",
      "base_instructions": "You are Jz Desk, an AI assistant working on the user's computer. Be precise and concise.",
      "visibility": "list",
      "priority": 1,
      "supported_in_api": true,
      "shell_type": "unified_exec",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Faster" },
        { "effort": "medium", "description": "Balanced" },
        { "effort": "high", "description": "Deeper" }
      ],
      "support_verbosity": true,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "context_window": 272000,
      "experimental_supported_tools": []
    }
  ]
}

Then point model_catalog_json in config.toml at the file’s full path — a file on your computer, not a URL — and reopen Jz Desk. Put the line near the top, before any [section]. On Windows, keep the single quotes so the backslashes are read as-is:

model_catalog_json = "/Users/you/.jz-desk/models.json"
model_catalog_json = 'C:\Users\you\.jz-desk\models.json'

If it does not work

The browser sign-in never finishes
Leave the browser tab open until Jz Desk shows you are signed in — the last step hands the sign-in back to the app on your computer. If OpenAI’s page will not load at all, your network cannot reach it; use an API key through a relay instead (above).
It waits and never replies
With a relay, the usual cause is openai_base_url: Jz Desk then tries WebSockets, which many relays accept and never answer. Set the relay up with the block in step 3 instead. Otherwise the address is unreachable — check it, or check your network can reach OpenAI. A config.toml left by an older install is never overwritten, so it may still carry an old setting.
Model is not supported
The model is not one your account serves. Under ChatGPT sign-in, pick one from the model picker, or delete the model line from config.toml; with a key, use a model id your key or relay serves. Start a new chat afterwards — an existing one keeps the model it was created with.
401 or 403
With a key: it is mistyped, expired, or the account has no billing set up — save it again with the step 2 command. If the key is right and the error still says invalid, auth.json is still in ChatGPT mode, which happens when the key was added to the file by hand; run the step 2 command. With ChatGPT: the sign-in has lapsed; delete auth.json and open Jz Desk to sign in again.
The key command fails on Windows
Run it in PowerShell, not Command Prompt, and after opening Jz Desk once — the folder it writes to does not exist before that.