mirror of
https://github.com/hanzoai/dev.git
synced 2026-10-25 03:32:32 +00:00
zeekay
901a81abe9
The docs read as OpenAI's Codex CLI: a getting-started page titled for it, `codex --enable skills` and `code sandbox macos` for commands that do not exist, defaults given as gpt-5.1-codex-max/openai when they are zen5-coder/hanzo, a Homebrew page describing a formula we do not publish. Removed three tui-stream-chunking notes and the execpolicy page: they document modules and a subcommand that live only in the vendored upstream copy. There is no execpolicy subcommand and no .codexpolicy loader in code-rs; the page told users to run something the binary does not have. Rewrote tui-alternate-screen against the source. It described an auto/always/never enum and a --no-alt-screen flag; the shipped behavior is a tui.alternate_screen bool with Ctrl+T, which replays the transcript into scrollback on the way out — a better answer to Zellij than the one written down. Genuine openai-provider documentation stays.
100 lines
3.1 KiB
Markdown
100 lines
3.1 KiB
Markdown
# Authentication
|
|
|
|
## Signing in
|
|
|
|
Dev talks to the Hanzo gateway (`api.hanzo.ai/v1`) by default. Sign in once and
|
|
the machine is linked to your account:
|
|
|
|
```shell
|
|
hanzo auth login
|
|
```
|
|
|
|
That fills in `HANZO_USER_KEY`. You can also set it yourself from a key minted at
|
|
https://hanzo.ai/settings/keys. A service that runs Dev unattended sets
|
|
`HANZO_API_KEY` or `HANZO_MACHINE_TOKEN` instead.
|
|
|
|
## Using the `openai` provider
|
|
|
|
Everything below applies only when you point `model_provider` at `openai` — see
|
|
[Configuration](./config.md#model_providers).
|
|
|
|
Authenticate with an API key:
|
|
|
|
```shell
|
|
export OPENAI_API_KEY="your-api-key-here"
|
|
```
|
|
|
|
Alternatively, read from a file:
|
|
|
|
```shell
|
|
dev login --with-api-key < my_key.txt
|
|
```
|
|
|
|
The key must, at minimum, have write access to the Responses API. The legacy
|
|
`--api-key` flag exits with an error pointing at `--with-api-key`, so the key
|
|
never appears in shell history or process listings.
|
|
|
|
To switch from an API key to a ChatGPT plan, delete `~/.code/auth.json` (and the
|
|
legacy `~/.codex/auth.json` if it exists; on Windows both live under
|
|
`C:\Users\USERNAME\`) and run `dev login` again.
|
|
|
|
### Forcing a specific auth method
|
|
|
|
When both are available, choose which one wins:
|
|
|
|
```toml
|
|
# ~/.code/config.toml (a legacy ~/.codex/config.toml is also read)
|
|
preferred_auth_method = "apikey" # or "chatgpt" (default)
|
|
```
|
|
|
|
Or ad-hoc: `dev --config preferred_auth_method="apikey"`.
|
|
|
|
With `"apikey"` and a key available, the login screen is skipped. With
|
|
`"chatgpt"`, ChatGPT auth wins if present and the API key is the fallback;
|
|
some account types require API-key mode regardless. `/status` in the TUI reports
|
|
which one the session is using, and the chat footer shows an “Auth: API key”
|
|
badge when a key is in play.
|
|
|
|
### Project `.env` safety
|
|
|
|
Dev does not read `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` from a project's
|
|
local `.env` — many repos keep a key there for unrelated tooling, which would
|
|
silently spend against the key instead of your plan. There is no opt-in.
|
|
|
|
`~/.code/.env` (or `~/.codex/.env`) is loaded first and may hold a global
|
|
`OPENAI_API_KEY`, and a shell-exported one is honored.
|
|
|
|
## Connecting on a "headless" machine
|
|
|
|
`dev login` runs a server on `localhost:1455`. In a Docker container or over
|
|
`ssh`, your local browser cannot reach it, so use one of these.
|
|
|
|
### Copy credentials from a machine that has a browser
|
|
|
|
Complete `dev login` locally, then copy the resulting `$CODE_HOME/auth.json`
|
|
(defaults to `~/.code/auth.json`) across — it is not tied to a host. Into a
|
|
container:
|
|
|
|
```shell
|
|
# substitute MY_CONTAINER with the name or id of your Docker container:
|
|
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
|
|
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.code"
|
|
docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.code/auth.json"
|
|
```
|
|
|
|
Or onto a remote host:
|
|
|
|
```shell
|
|
ssh user@remote 'mkdir -p ~/.code && cat > ~/.code/auth.json' < ~/.code/auth.json
|
|
```
|
|
|
|
### Forward the login port
|
|
|
|
```bash
|
|
# From your local machine
|
|
ssh -L 1455:localhost:1455 <user>@<remote-host>
|
|
```
|
|
|
|
Then run `dev login` in that SSH session and open the printed
|
|
`http://localhost:1455/...` URL locally. The traffic is tunneled to the remote.
|