# Install and first run

Codey is one static binary with nothing to install alongside it, so there are
three ways to get it and they differ only in what you need to have already.

**A release.** The [releases page](https://github.com/johannSo/codey/releases)
has an archive for Linux and macOS, each on amd64 and arm64, with
`checksums.txt` beside them. Unpack the one for your machine and put `codey`
somewhere on your `PATH`. The archive names carry no
version, so the latest one is always at the same address:

```bash
# linux or darwin, amd64 or arm64
curl -L https://github.com/johannSo/codey/releases/latest/download/codey_linux_amd64.tar.gz | tar xz codey
```

**With Go.** If you have Go installed, this builds the latest release and puts
it in `$(go env GOPATH)/bin`:

```bash
go install github.com/johannSo/codey/cmd/codey@latest
```

`@latest` can be any tag, and `codey --version` reports the one you asked for.
The Go it needs is the one `go.mod` names; an older `go` command fetches that
toolchain by itself unless `GOTOOLCHAIN` says not to.

**From source.** For working on Codey, or running a commit that is not
released yet:

```bash
git clone https://github.com/johannSo/codey
cd codey
go build -o codey ./cmd/codey
```

A build from a checkout reports the version the source was last released as,
not the commit; `git log` is the better answer to "which one is this". The
examples in these docs run it as `./codey`, from the directory it was built
in. Installed on your `PATH` it is just `codey`.

## macOS

Release binaries are not signed or notarized. A download through a
browser is quarantined and Gatekeeper refuses to open it; `xattr -d
com.apple.quarantine codey` lifts that. The `curl` above does not quarantine
what it fetches, and neither does `go install`.

## Quick start

```bash
./codey -C /path/to/a/throwaway/clone          # full-screen TUI
./codey -C /path/to/repo -p "why does TestFoo fail?"   # one prompt
```

Codey needs a credential, and the ordinary one is an Anthropic API key, which
you create at
[console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys):

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

Started with nothing at all, Codey stops and says how to get one rather than
failing on the first request.

A different endpoint — a gateway, a proxy, a local server speaking the Messages
API:

```bash
./codey -base-url http://127.0.0.1:4000 -api-key ... -C .
# or ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
```

Flags beat the saved config, which beats the built-in defaults; the config is
what [the setup wizard](setup.md) writes on a first run. `-auth-token` sends
`Authorization: Bearer`, which is what OAuth tokens and most gateways want;
`-api-key` sends `x-api-key`. A non-default endpoint announces itself on
stderr, because your prompt and every file the agent reads go wherever that URL
points.

On your own machine, if you are logged into Claude Code, Codey can borrow the
OAuth credential Claude Code keeps in `~/.claude/.credentials.json` instead of
needing a key. It does this only when asked: `-claude-code-auth` for one run, or
`"claude_code_auth": "on"` in [the config](setup.md) — which the setup wizard and
`/settings` both offer — for every run. Be aware of what that is: the
credential is issued to Claude Code, and using it from another client is
outside Anthropic's terms for it, which API keys and gateway tokens do not
carry. That is why it is off until you turn it on, and why it is not something
to set up on a machine other people use.

Even when asked for, it is the last resort. It is tried only when no flag and
no environment variable supplied a credential, and only against Anthropic's own
endpoint — a credential found on disk is not one you chose to send, so it is
never forwarded to a `-base-url` you pointed Codey at. `-no-claude-code-auth`
refuses it for one run, whatever `-claude-code-auth` and the config say.

Earlier builds borrowed the login silently whenever nothing else was set. If
you relied on that, the first start after upgrading asks once, on the terminal,
whether to keep doing so, and saves the answer as `claude_code_auth` — yes or
no, so it is not asked again. A `-p` run, a pipe, and `codey models` have
nobody to ask, so they just report that there is no credential and how to get
one.

On macOS Claude Code keeps this in the Keychain rather than a file, so there is
nothing to borrow there. An expired access token is refreshed automatically; the
credentials file is left alone unless the server rotates the refresh token, in
which case the replacement is written back — leaving the dead one there is what
would break your Claude Code login.