# Install Glosswork

This page is written for an AI agent. If you are a person, paste this page's address into your agent and ask it to set Glosswork up for you.

Agent: follow the steps in order. Where a step says **Ask your human**, stop, put the question to your human in words, and wait for the answer. Ask even when you think you already know the answer from context. Do not skip ahead.

## 1. What Glosswork is

Glosswork is a shared place where your human's agents and team keep structured information: object types, fields, records, comments, and a full history of who changed what. You design the structure yourself, through MCP tools, from a plain description of what your human wants to keep track of, and every type, field, and option carries a description written for the next agent that reads it. You can build and add freely, but you cannot delete a field or a type on your own: destructive schema changes become proposals a human approves in the Glosswork web UI.

## 2. Hosted or self-hosted

**Ask your human:** "Do you want Glosswork to run it for you (hosted), or do you want to run it yourself on a computer you control (self-hosted)? Self-hosting needs Docker and takes about ten minutes."

Ask this and wait for the answer, even if earlier messages make self-hosting look likely. A port number or container name your human mentioned is not an answer to this question.

- **Hosted:** hosted workspaces are not open yet. Give your human the waitlist link, https://glosswork.dev/waitlist, and tell them an email will follow when hosted workspaces open. Stop here, unless they would rather self-host now.
- **Self-hosted:** continue to step 3.

## 3. Check what you can do

You need to run shell commands on the computer that will host Glosswork.

- **If you can run shell commands** (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf), run the commands below yourself and read their output.
- **If you cannot** (for example, a chat app such as Claude Desktop), give your human each command one at a time, ask them to run it in a terminal, and ask them to paste the output back to you. The one exception is the access token in step 7: your human creates it in the Glosswork web page and pastes it into the installer's own prompt in step 8, not into this chat.

**Ask your human:** "Should I install Glosswork on this computer?" Ask this and wait for the answer, even if you are already running on a computer that has Docker. If they name a different computer, the commands are the same, but they have to be run there, and the MCP address in step 8 changes. This page covers only the case where the agent and Glosswork run on the same computer. If they need other people to reach it over a network, tell them that needs HTTPS and a reverse proxy, which this page does not cover, and stop.

Commands below are for macOS or Linux. On Windows, use PowerShell, use the one-line form where one is given, and type `curl.exe` wherever a command says `curl`.

## 4. Check Docker

Run:

```bash
docker version --format '{{.Server.Version}}'
```

- A version number prints: continue.
- `command not found`, or an error about connecting to the Docker daemon: **tell your human** Docker is not installed or not running. Point them to https://docs.docker.com/get-started/get-docker/ (Docker Desktop on macOS and Windows). Wait until they say it is running, then run the command again.

Check that no Glosswork container exists already:

```bash
docker ps -a --filter name=^glosswork$ --format '{{.Names}} {{.Status}}'
docker volume ls --filter name=^glosswork-data$ --format '{{.Name}}'
```

If either prints anything, **stop and ask your human** what it is. It may hold their data. Never remove an existing container or volume.

Check that port 8000 is free:

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/
```

`000` means the port is free. Any other number means something is already using it: pick another port, such as 8010, check it the same way, and use that number everywhere this page says `8000`. Change both numbers in the `-p` option and the one in `GW_BASE_URL`, but not the `:8000` on the container side of `-p`.

From here on, this page calls three values your **install values**: the address `http://127.0.0.1:8000` (with your port if you changed it), the container name `glosswork`, and the volume name `glosswork-data`. If your human asked for different names, use theirs wherever this page says `glosswork` for the container or `glosswork-data` for the volume. Step 8 carries these values across a restart.

## 5. Choose the first administrator

**Ask your human:**

1. "What email address should your Glosswork administrator account use?"
2. "Choose a password of at least 12 characters, or I can generate one for you." To generate one, run `openssl rand -base64 18`.

If you generate the password, show it to your human once, before you start Glosswork, so they can save it. Tell your human to save the email and password in their password manager now. They use them to sign in to the web UI. Do not write the password into any file.

## 6. Start Glosswork

Replace `you@example.com` and `CHOSEN-PASSWORD` with the answers from step 5, then run:

```bash
docker volume create glosswork-data
docker run -d --name glosswork --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -v glosswork-data:/data \
  -e GW_BASE_URL=http://127.0.0.1:8000 \
  -e GW_COOKIE_SECURE=false \
  -e GW_BOOTSTRAP_ADMIN_EMAIL=you@example.com \
  -e GW_BOOTSTRAP_ADMIN_PASSWORD='CHOSEN-PASSWORD' \
  docker.io/glosswork/glosswork:latest
```

The same `docker run` on one line, for Windows PowerShell:

```powershell
docker run -d --name glosswork --restart unless-stopped -p 127.0.0.1:8000:8000 -v glosswork-data:/data -e GW_BASE_URL=http://127.0.0.1:8000 -e GW_COOKIE_SECURE=false -e GW_BOOTSTRAP_ADMIN_EMAIL=you@example.com -e GW_BOOTSTRAP_ADMIN_PASSWORD='CHOSEN-PASSWORD' docker.io/glosswork/glosswork:latest
```

What each setting does:

| Setting | Why |
| --- | --- |
| `-p 127.0.0.1:8000:8000` | Reachable from this computer only. |
| `-v glosswork-data:/data` | Everything Glosswork stores lives in this Docker volume. Removing the volume deletes the workspace. |
| `GW_BASE_URL` | The address agents use. Glosswork accepts MCP requests only for this exact host and port, so use `127.0.0.1`, not `localhost`, everywhere below. |
| `GW_COOKIE_SECURE=false` | Lets the browser sign-in work over plain `http://` on this computer. |
| `GW_BOOTSTRAP_ADMIN_EMAIL`, `GW_BOOTSTRAP_ADMIN_PASSWORD` | Create the first administrator on the first start. Later starts leave the account alone. |

The image is about 500 MB, so the first pull takes a minute or two. Wait until Glosswork is ready:

```bash
curl -fsS --retry 30 --retry-connrefused --retry-all-errors --retry-delay 2 http://127.0.0.1:8000/readyz
```

It prints a response and exits 0 when ready. While Glosswork starts, it may also print `curl: (52) Empty reply from server` one or more times. That is normal: it keeps retrying, and it has worked when it exits 0. If it exits non-zero, run `docker logs glosswork`. Every log line is JSON, and a configuration error names the variable at fault. Show the error to your human.

## 7. Get an access token

Agents authenticate with a personal access token with `admin` scope, which you need to create object types. Who creates it depends on your harness.

**Claude Code, Claude Desktop and VS Code: your human creates it, in the web page.** The token then goes from their clipboard into the installer's prompt in step 8 and never passes through this chat, your shell output, or a command line. Do not mint one yourself for these three. Do this when step 8 tells you to, not before. Tell your human:

1. Open `http://127.0.0.1:8000` (your install address) and sign in with the email and password from step 5.
2. Open Setup. Under Personal access tokens, in Mint a new token, enter the name `claude-code` (or `claude-desktop`, or `vscode`), choose the scope `admin`, and choose Mint token.
3. Choose Copy to clipboard. The token is shown once. Do not paste it into this chat. Paste it only where step 8 asks for it.

If your human pasted the token into this chat by mistake, revoke it (below) and have them mint another.

**Every other harness: mint it yourself.** Capture it in the variable `TOKEN` and check that it works:

```bash
TOKEN=$(docker exec glosswork python -m glosswork.admin mint-token --name gemini-cli --scope admin --quiet)
curl -sS -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"install-check","version":"0"}}}'
```

- Replace `gemini-cli` with the name of your harness.
- Keep `--quiet`. With it, the command prints only the token, so `$(...)` captures it whole. Without it, the command prints a token id, a prefix that also starts with `gw_pat_`, and a note before the token, and a capture picks up the wrong line.
- The token starts with `gw_pat_` and is 39 characters long. It is shown once and cannot be recovered, only replaced by minting another. Do not print it, repeat it in chat, or save it anywhere except the configuration in step 8.

A response containing `"instructions"` means the token works. An `error` whose message says the request carried no credential, or that the token is unknown, means the header is wrong. A response of `Invalid Host header` means the address does not match `GW_BASE_URL` exactly.

**Mint once, and register in the same command.** Many agent shells start a fresh shell for every command, so `TOKEN` is gone by the next command. If yours does, do not run the lines above on their own. Run the mint, the check, and your step 8 registration as one command, joined with `&&` so registration runs only when the check passes. Step 8 shows this for Gemini CLI.

If your human is running the commands for you (step 3), they run the `mint-token` line without `TOKEN=$(` and `)`, and paste the printed token into the configuration file in step 8, not into this chat.

**If a token is lost, mangled, printed into chat, or left over from a failed attempt, revoke it.** It stays valid until someone does. Tell your human which token it was by its name. There are two ways:

- **In the web UI:** your human signs in at the address from your install values, opens Setup, finds the token by name in the Personal access tokens card, and chooses Revoke, then Confirm revoke.
- **From the shell,** using a token that works (if you have none, mint a fresh one as above, in the same command). List the tokens, which shows each one's `id`, `name`, `token_prefix`, `scope`, and `revoked_at`, but never the secret. Then revoke the one you mean by its `id`:

  ```bash
  curl -sS http://127.0.0.1:8000/api/v1/access-tokens -H "Authorization: Bearer $TOKEN"
  curl -sS -X DELETE http://127.0.0.1:8000/api/v1/access-tokens/TOKEN-ID -H "Authorization: Bearer $TOKEN"
  ```

  The response shows `revoked_at` set. From then on, the revoked token gets an error saying it was revoked.

`glosswork.admin` has no command to revoke a single token. Its `revoke` command removes a person's access to an object type, not a token. Its `set-password` revokes every token and signed-in session the account holds, so use it only as a last resort.

## 8. Connect your harness

The server facts, for any harness:

- **Address:** `http://127.0.0.1:8000/mcp` (MCP over streamable HTTP; requests are POST only)
- **Header:** `Authorization: Bearer gw_pat_...`
- **Optional header:** `X-Agent-Label: <a short name for you>`. It tags your writes in the audit history. It is a label, not a permission.

Claude Code and Claude Desktop connect through the Glosswork connection kit, at https://github.com/glosswork/glosswork-connect. The kit asks your human for the address and the token in its own prompt, so nobody edits a configuration file and the token stays out of this chat. Every other harness uses a snippet under "Any other MCP client".

### Claude Code

You install the plugin. Your human gives it the address and the token.

1. Add the kit's marketplace and install the plugin. Neither command needs a token:

   ```bash
   claude plugin marketplace add glosswork/glosswork-connect
   claude plugin install glosswork@glosswork --scope user
   ```

   Each prints `Successfully` and exits 0. The install then says two required settings are not set. That is expected. Your human sets them next.

2. **Tell your human** to do the following in a Claude Code session, and to do it themselves, because the token must not pass through this chat:

   - Run `/plugin configure glosswork@glosswork`.
   - Enter the workspace address `http://127.0.0.1:8000/mcp` (your install address, ending in `/mcp`, spelled exactly as in your install values).
   - Mint the token as step 7 describes, name `claude-code`, scope `admin`, and paste it into the "Access token" field. While the field has focus, Claude Code shows the last six characters of what was pasted. That is normal.

3. The plugin loads in a new session. Give your human the message in "After registering" below, then have them start a new Claude Code session and run `/mcp`. The server `plugin:glosswork:glosswork` should show as connected.

The plugin stores the token in Claude Code's secure storage (the macOS Keychain, or a credentials file in Claude Code's configuration directory when the Keychain refuses it), keeps only the address in `settings.json`, and sends `X-Agent-Label: claude-code` on every call. `--scope user` makes Glosswork available in every project on this computer, which means every project can reach an admin token to this workspace.

To undo it, run `claude plugin uninstall glosswork@glosswork`. Then revoke the token by its name `claude-code` in Setup (step 7).

### Claude Desktop

Claude Desktop's custom connectors connect from Anthropic's cloud, so they cannot reach a Glosswork running on this computer. The kit's Claude Desktop extension can. It is a small file your human installs, and it asks for the address and the token. You cannot run commands from Claude Desktop, so your human does every step, and you give them each one.

1. **Tell your human** to build the extension. It needs `git`, Node.js with `npm`, `bash`, and network access:

   ```bash
   git clone https://github.com/glosswork/glosswork-connect
   bash glosswork-connect/mcpb/build.sh
   ```

   It prints `bundle:` and the path of `glosswork.mcpb`. The kit measured this build on macOS only. On Windows, run it in Git Bash.

2. **Tell your human** to open Claude Desktop, go to Settings, then Extensions, then Advanced settings, choose Install Extension, and pick that `glosswork.mcpb` file.

3. Claude Desktop may warn that the extension is unsigned or from an unknown developer. That is expected: the kit does not sign it yet. Your human continues.

4. Claude Desktop asks for two values, and nothing else. **Tell your human** to enter the address `http://127.0.0.1:8000/mcp` (your install address, ending in `/mcp`), and to mint the token as step 7 describes, name `claude-desktop`, scope `admin`, and paste it into the token field. The token goes into the operating system's secure storage, and the extension passes it to its proxy through an environment variable, so it does not show in the process list.

5. Have your human quit Claude Desktop completely and reopen it, then start a new chat. Give them the message in "After registering" below first.

Spell the address exactly as your install values do. A workspace answers only for its own `host:port`, so `localhost` where the workspace says `127.0.0.1` fails with `Invalid Host header` and status 421, which looks nothing like a token problem. Do not change the address to a network address such as `http://192.168.1.20:8000/mcp`: on a plain `http://` address that is not on this computer, the token crosses the network in clear text, and this page covers only one computer.

### Any other MCP client

These harnesses have no kit installer yet. Except for VS Code, each of these snippets holds the token in plain text in a file or a command, so **tell your human** which file it is in, and that it must not be committed to a repository or shared. Mint the token yourself, as step 7 describes, using the harness name in `--name`. Commands use `$TOKEN` from step 7, in the same command that minted it. In the files, replace `gw_pat_REPLACE_ME` with the token.

#### Cursor

Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in the project:

```json
{
  "mcpServers": {
    "glosswork": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}
```

Cursor also accepts `"Bearer ${env:GLOSSWORK_TOKEN}"` if your human prefers to keep the token in an environment variable.

#### VS Code

VS Code prompts for the token when it starts the server, so the token is never written into the file and never passes through this chat. Your human mints it the way step 7 describes for Claude Code, with the name `vscode` and scope `admin`. Do not mint it yourself.

Add to `.vscode/mcp.json` in the project. To make Glosswork available in every project instead, have your human run **MCP: Open User Configuration** from the Command Palette and put the same content there:

```json
{
  "servers": {
    "glosswork": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:glosswork-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "glosswork-token",
      "description": "Glosswork access token",
      "password": true
    }
  ]
}
```

The top-level key is `servers`, not `mcpServers`. Have your human run **MCP: List Servers**, start `glosswork`, choose to trust it when VS Code asks, and paste the token into the prompt. VS Code stores what they paste for later starts.

#### Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.glosswork]
url = "http://127.0.0.1:8000/mcp"
http_headers = { "Authorization" = "Bearer gw_pat_REPLACE_ME" }
```

Or, to keep the token in an environment variable that is set wherever Codex starts, run `codex mcp add glosswork --url http://127.0.0.1:8000/mcp --bearer-token-env-var GLOSSWORK_TOKEN`. Start a new Codex session afterwards.

#### Windsurf

Windsurf is now called Devin Desktop. Its documentation puts the file at `~/.config/devin/mcp_config.json` (or `$XDG_CONFIG_HOME/devin/mcp_config.json`; on Windows `%APPDATA%\devin\mcp_config.json`) and says these MCP settings apply to the legacy Cascade agent. An older install keeps the file at `~/.codeium/windsurf/mcp_config.json`. Use whichever of the two already exists on this computer, and if neither does, use the first. Your human can also open it from the `...` menu of the Cascade panel, using the Open MCP config file icon. Add:

```json
{
  "mcpServers": {
    "glosswork": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}
```

Then restart Windsurf, or use the toggle next to `glosswork` in the MCPs section of the Cascade panel's `...` menu.

#### Gemini CLI

Mint, check, and register in one command:

```bash
TOKEN=$(docker exec glosswork python -m glosswork.admin mint-token --name gemini-cli --scope admin --quiet) &&
curl -sS -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"install-check","version":"0"}}}' \
  | grep -q '"instructions"' &&
gemini mcp add --transport http \
  --header "Authorization: Bearer $TOKEN" \
  glosswork http://127.0.0.1:8000/mcp
```

It exits 0 when the token works and Glosswork is registered. If it exits non-zero, nothing was registered, but a token may have been minted: revoke `gemini-cli` (step 7) before you try again.

With no `--scope`, Gemini CLI uses **project** scope, its default. It has no separate local scope. Project scope writes `.gemini/settings.json` in this directory, with the token in plain text, and Glosswork is available only when Gemini CLI starts here. Tell your human not to commit that file. In a folder your human has not trusted, Gemini CLI does not load `.gemini/settings.json` and does not connect to any MCP server. `gemini mcp list` shows when this is the cause: it lists `glosswork` as Disabled and warns that the folder is untrusted. Gemini CLI asks your human whether to trust a folder the first time it starts there. If they chose not to, have them type `/permissions trust` inside Gemini CLI, choose to trust the folder, and start a new session. Use project scope unless your human asks for something else. `--scope user` writes `~/.gemini/settings.json` instead, which makes the admin token available in every directory. To undo, run `gemini mcp remove glosswork --scope <the scope you used>`.

To edit a file instead, use `.gemini/settings.json` in this directory, or `~/.gemini/settings.json` for every directory. Note the key is `httpUrl`, not `url`:

```json
{
  "mcpServers": {
    "glosswork": {
      "httpUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}
```

Start a new Gemini CLI session afterwards.

#### A client not listed


Most clients accept this shape. Some name the address key `url`, `serverUrl`, or `httpUrl`, and some need `"type": "http"` or `"streamable-http"`, so check the client's own documentation:

```json
{
  "mcpServers": {
    "glosswork": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}
```

### After registering

Most harnesses load MCP servers only when a session starts. A new session remembers nothing from this one, so the message your human gives it must carry your install values. If your harness needs a restart, **tell your human** before it happens, and give them this message with your real values filled in, to paste into the new session:

> Continue the Glosswork install at step 9 of PAGE-ADDRESS. Glosswork is at http://127.0.0.1:PORT, in the container CONTAINER-NAME, with its data in the volume VOLUME-NAME.

Replace `PAGE-ADDRESS` with this page's address, and `PORT`, `CONTAINER-NAME`, and `VOLUME-NAME` with your install values from step 4. Give the actual values even if they are the defaults (`8000`, `glosswork`, `glosswork-data`).

**If you are the new session:** use the address, container, and volume from that message wherever steps 9 and 10 name them. They override the defaults on this page.

When the Glosswork tools are available to you, you will see tools such as `describe_capabilities`, `list_object_types`, and `create_object_type`. If they do not appear, check that the address is exactly your install address followed by `/mcp`, such as `http://127.0.0.1:8000/mcp`, and the header is exactly `Authorization: Bearer gw_pat_...`.

## 9. Ask your human what they want to keep track of

This is the point of everything above.

1. Call `describe_capabilities`. It is Glosswork's manual: field types, the operators each one allows, key rules, and limits.
2. **Ask your human:** "What do you want to keep track of?"
3. From their answer, design and create the object type with `create_object_type`: fields with real types, select options with descriptions, and relations where two things are genuinely different things. Write every description for the agent that reads it next, not for a human skimming a form.
4. Show your human what you built, descriptions included, and offer to enter their first few records.

Things to tell your human along the way:

- **Changing it later is normal.** Adding types, fields, and options takes effect immediately. Deleting a field or type, or changing a field's type, becomes a proposal they approve in the web UI, so you cannot delete their data without them.
- **The web UI is optional.** They can see the same records at your install address (`http://127.0.0.1:8000` unless you changed the port) by signing in with the email and password from step 5. Do not suggest they change the password after connecting: a password change revokes every access token, so it would disconnect you and every other agent, and each one would need a new token.

## 10. Keep it safe

- Everything is in the Docker volume from your install values (`glosswork-data` unless renamed). Removing that volume deletes the workspace. `docker stop` and `docker start` with your container name (`glosswork` unless renamed) keep it.
- **Tell your human** to set up nightly backups before they put anything important in.