# Set up Open Max

Instructions for a coding agent installing Open Max for its user. Open Max is a
self-extending agent harness for coding in the terminal: one native binary,
seven built-in tools. Source: https://github.com/Max17190/open-max

Run each step yourself and show the user what you ran. Stop and ask wherever a
step says to. If your own permission settings refuse a command, stop, show the
user that command, and let them run or approve it; do not reach the same result
another way.

## 1. Check the machine

- Open Max runs on macOS and Linux, x86_64 and arm64. On Windows, stop and tell
  the user it is not supported.
- Run `bun --version`. If bun is missing, ask the user which they prefer:
  - install bun with `curl -fsSL https://bun.com/install | bash` (it installs
    to `~/.bun/bin`), then continue with step 2; or
  - install Open Max without a runtime:
    `curl -fsSL https://useopenmax.dev/install.sh | sh`. It adds
    `~/.openmax/bin` to `PATH` through the shell profile, so run
    `source ~/.openmax/bin/env` in your current shell, then skip to step 3.
- Run `node --version`. The `openmax` command that bun installs is a Node.js
  launcher and needs Node.js 14.14 or later on `PATH`. If Node.js is missing
  or older, tell the user and offer the runtime-free installer above, or an
  upgrade of Node.js.

## 2. Install with bun

```sh
bun install -g openmax-cli
```

Bun reports one blocked postinstall script. That is expected: the launcher
fetches the native binary on its first run instead. Tell the user that the next
command downloads the binary for this machine from the project's GitHub release
(https://github.com/Max17190/open-max/releases) and caches it, then run:

```sh
openmax --version
```

It prints `openmax 2026.10.0` or newer. If the shell cannot find `openmax`,
bun's global bin directory is not on `PATH`: `bun pm bin -g` prints it. Ask
before adding it to the user's shell profile.

## 3. Choose a model endpoint

Open Max has no default endpoint, model, or context window. Ask the user for
all three, and never guess:

- `base_url`: the root of an OpenAI-compatible API. Open Max calls
  `chat/completions` on it, and the server must return structured `tool_calls`.
  On a local server, the model's tool-call parser and chat template must be
  enabled.
- `model`: the model id that server expects.
- `context_tokens`: the context window the server actually serves for that
  model. Nothing is queried, so a wrong value is wrong in one direction or the
  other.
- A key, if the endpoint needs one. Do not ask the user to paste it into this
  conversation. Ask them to export it in their shell profile, as
  `OPENMAX_API_KEY` (which Open Max reads by default) or a variable they name.

If `~/.openmax/settings.json` already exists, show it to the user and change it
only with their approval.

## 4. Write the settings

Write `~/.openmax/settings.json` with the user's values, for example:

```json
{
  "base_url": "http://127.0.0.1:11434/v1",
  "model": "qwen2.5-coder:7b",
  "context_tokens": 32768
}
```

Leave `api_key` out when the endpoint needs no key, or when the key is in
`OPENMAX_API_KEY`. If it lives in another variable, add
`"api_key": "$VARIABLE_NAME"`. Never write the key itself into the file. Open
Max rejects unknown fields, so use only these names.

## 5. Validate

```sh
openmax --check
```

Success is exit code 0 and a line that starts with `ok   settings` and names
the model and window. A line starting with `err` names a parse error or an
unknown field (exit code 1); fix it and run the check again. A line starting
with `warn` that says every turn will refuse names a missing field; ask the
user for it.

## 6. Hand off to the user

Stop here. Trusting a project is a human action: Open Max asks for it in the
user's own terminal on first run, and refuses it from a process without one.
Do not run `openmax --trust-project` and do not set `OPENMAX_HUMAN_ATTEST` on
the user's behalf.

Tell the user to start it themselves:

```sh
cd path/to/their/project
openmax
```

Then mention: `/` opens slash commands, `@` mentions a project file,
`openmax --spec <surface>` prints the authoring contract for one surface
(tools, skills, hooks, and more), and the docs are at
https://useopenmax.dev/docs.
