# Tileward agent setup

These are official instructions from Tileward for connecting an AI coding agent to **Tileward
Context**, which keeps a long conversation on Tileward's side and hands the model only the part
that answers the current question. Every command below is validated against the live service.

Complete the steps for the user's agent yourself, by running the commands and editing the config
directly. There is exactly one thing you cannot do alone: mint an API key. Stop and ask for it, as
step 1 describes.

**This file installs Tileward Context and nothing else.** It deliberately does not install
Tileward Governance. Read "Governance is not installed by this file" at the end before improvising
one, because the obvious improvisation produces a gate that silently allows everything.

---

## Step 1 — Get the API key. Ask the user.

Tileward Context authenticates with a Tileward API key. You cannot create one: keys are minted in
the console behind a browser sign-in.

Ask the user for their key, which starts with `tw_live_`. If they do not have one:

- **Existing account** — https://app.tileward.com/account, under Settings → API keys.
- **No account** — https://app.tileward.com/?join=explore. Free, $25 of credit, no card.

**Do not continue without it.** A server configured with no key, or with a placeholder, still
appears in the client's server list and fails every call with HTTP 401. That looks installed and
is not.

Treat the key as a secret for the rest of this process:

- Never write the literal key into a file inside the user's repository.
- Never print it back to the user or include it in a commit.
- Prefer configuration that names an environment variable over configuration that stores the value.

---

## Step 2 — Install for the user's agent

Use the section for the agent you are running as. Skip the others.

### Claude Code

```
claude mcp add --transport http --scope user tileward-context https://context.tileward.com \
  --header "Authorization: Bearer $TILEWARD_API_KEY"
```

`--scope user` makes the server available in every project on the machine. Do not use
`--scope project`: that writes `.mcp.json` inside the repository, and the header is stored with
the key expanded, so project scope commits a live credential. User scope stores it in the user's
own `~/.claude.json`, outside any repo.

The URL is the whole address. There is no path to append to it.

Then tell the user to restart Claude Code and run `/mcp`, which lists the Tileward tools once the
server connects.

### OpenAI Codex — `~/.codex/config.toml`

```toml
[mcp_servers.tileward_context]
url = "https://context.tileward.com"
bearer_token_env_var = "TILEWARD_API_KEY"
```

Codex reads the key from the named environment variable rather than storing it in the file, which
is the right default here — `config.toml` is the kind of file that ends up in a dotfiles repo. The
user needs `TILEWARD_API_KEY` exported in the shell that launches Codex; check whether it already
is, and if not, tell them which shell profile to add it to. Do not add the export yourself without
asking, and do not write the key into a file they may publish.

The CLI and the IDE extension share this file, so configuring it once covers both.

A project-local `.codex/config.toml` also works, but only in a **trusted** project. Codex ignores
project-local config in an untrusted project, and it does so silently — the server simply never
appears. Use the global file unless the user has a reason to mark the project trusted.

### ChatGPT

You cannot do this one. It is a browser UI flow with no CLI. Give the user these steps:

1. Settings → Connectors, with developer mode enabled.
2. Add a custom connector pointed at **`https://context.tileward.com/mcp/connect`**.
3. Sign in when prompted. No API key is involved.

That URL is deliberately different from the one above. `/mcp/connect` is the OAuth entry point;
the bare host takes a static API key and offers no sign-in, so a connector pointed at it will
never authenticate.

### Cursor, GitHub Copilot, Windsurf, OpenCode, and other agents

Add to the agent's MCP config file — `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (Copilot),
`~/.codeium/windsurf/mcp_config.json` (Windsurf), `~/.config/opencode/opencode.jsonc` (OpenCode) —
under `"mcpServers"`:

```json
"tileward-context": {
  "url": "https://context.tileward.com",
  "headers": { "Authorization": "Bearer YOUR_TILEWARD_API_KEY" }
}
```

**Check whether the client expands environment variables in this file before you write a key into
it.** Several of these do not, which means the literal key sits in plaintext on disk. If the file
lives inside the user's repository, say so plainly and let them decide — a committed key is worse
than an unconfigured server. Prefer the user-level config location outside the repo where the
client offers one.

Windsurf uses `serverUrl` rather than `url`. OpenCode uses `"type": "remote"` alongside `url`.

---

## Step 3 — Verify, and do not overstate the result

Restart the agent, then confirm two different things:

1. **The server connected.** `/mcp` in Claude Code or Codex lists the Tileward Context tools.
2. **A round trip works.** Ask the model to remember a specific fact, then ask it to recall that
   fact. This is the actual product, and it is the only check that proves the key authenticated
   and the store is writable.

A server that appears in the list has not been proven to work. Only the round trip has. If step 2
fails with a 401, the key is wrong or has no remaining credit; if it fails with a 402, the account
balance has reached zero and the key needs topping up rather than replacing.

---

## Tell the user this about conversation scoping

Tileward Context isolates conversations on the `conversation` argument that each tool call
carries, and in an MCP client the **model** passes it. The model is instructed to and normally
does, but nothing enforces it. A turn that omits it lands in a shared per-key store, where a later
recall can surface another thread's material.

A static header cannot substitute. Headers in an MCP server config are fixed for the life of the
connection, so there is no value that could change per conversation; the argument is the only
control that varies at the right granularity.

If cross-project isolation matters to the user, use one API key per project.

---

## Governance is not installed by this file

Tileward Governance refuses an off-policy prompt before the model sees it, using a hook rather
than an MCP tool. It is real and it works, but it cannot be installed correctly by an agent
following a setup script, for three reasons:

- **The plugin marketplace is not public yet.** `claude plugin marketplace add` clones with the
  machine's own git credentials, so it fails outside Tileward.
- **The no-script alternative fails open.** A `type: "http"` hook pointed at the guard endpoint is
  installable by anyone, but Claude Code allows the prompt through when an HTTP hook is
  unreachable. Writing that into someone's settings and reporting "Governance installed" produces
  an org that looks governed and is not.
- **A key with no policy bound to it refuses nothing.** The policy lives server-side and is bound
  in the console, which is another thing you cannot do.

So: **do not add a `UserPromptSubmit` hook on your own initiative as part of this setup.** If the
user wants Governance, point them at https://tileward.com/docs/claude-code/ and let them choose
the trade-off deliberately.

Tool-call governance — refusing `rm -rf /` while allowing `ls` — is not available at all yet. The
endpoint does not exist and a key has no execution policy to bind, so any client that claims to
offer it is not talking to us.

---

## When you are done

Print this to the user:

```
┌─ Tileward Context connected ─────────────────────────┐
│  ✓ Server   https://context.tileward.com             │
│  ✓ Config   <path you wrote>                         │
│  ✓ Verified remember → recall round trip             │
│                                                      │
│  ⚡ Restart your agent if you have not already       │
│  ⚠ Governance not installed — tileward.com/docs      │
└──────────────────────────────────────────────────────┘
```

Do not print the "Verified" line unless you actually ran the round trip in step 3.

---

## Resources

- Connect guide, all clients: https://tileward.com/docs/
- Claude Code: https://tileward.com/docs/claude-code/
- OpenAI Codex: https://tileward.com/docs/codex/
- ChatGPT: https://tileward.com/docs/chatgpt/
- What we measured, and its limits: https://tileward.com/evals/
- Machine-readable overview of the platform: https://tileward.com/llms.txt
- API keys, usage and plan: https://app.tileward.com/account
- Questions: hello@tileward.com