The First Run

Heph needs one thing before it can do anything: a model to talk to. It finds one in your environment, and the first time it runs it writes down what it found so you can see and change it.

Credentials

Set one of these before you start:

An Anthropic API key, for the Anthropic API directly:

export ANTHROPIC_API_KEY=sk-ant-...

AWS credentials, for Claude on Amazon Bedrock. Anything the AWS SDK's default credential chain accepts works: AWS_ACCESS_KEY_ID and friends, an AWS_PROFILE, an SSO session, aws-vault exec, a container or web identity role. Heph also needs a region: AWS_REGION or AWS_DEFAULT_REGION, or a region on the profile.

aws-vault exec --ecs-server work -- heph

If both are set, the API key wins, because it is set for this one purpose and AWS credentials serve everything on AWS.

A session outlives a set of temporary credentials, so prefer a form that renews itself: --ecs-server above, an SSO profile, or a credential_process profile. Plain aws-vault exec work -- heph exports fixed credentials that stop working when they expire, and heph tells you when that happens. Bedrock Credentials sets up each of the three, step by step.

What the first run does

Run heph in a project directory. Before the screen appears you will see one line:

no config file; wrote /home/you/.config/heph/config.toml from the environment.
Edit it to change providers or models.

Heph looked for a config file, found none, found a provider in your environment, and wrote its decision to the user config file. The file names the provider it chose and lists, as comments, the model tiers it will use:

[providers.bedrock]
# region = "us-east-1"   # default: AWS_REGION, then the profile's
# profile = "work"       # default: the chain aws-vault exec feeds

# Tiers say which model does which work, and a profile is a set of tiers. With
# one provider, its catalog defaults are the default profile, today the three
# below. To change one, uncomment it: a [profiles.default] tier changes only
# the fields it writes, and the rest keep the defaults. `heph profiles` shows
# what is in force.

# [profiles.default.tiers.frontier]
# models = ["bedrock/us.anthropic.claude-opus-5"]

# [profiles.default.tiers.workhorse]
# models = ["bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"]

# [profiles.default.tiers.fast]
# models = ["bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"]

The file is written once and never rewritten. It is yours to edit; the Configuration chapters cover every key. You can also leave it alone: with the tiers commented out, heph keeps using the defaults the comments show.

If you set up credentials after a config file already exists, nothing is written; heph uses the file. And if no credentials are found and there is no file, heph stops at once and says what it looked for:

Error: config: no provider is configured and none was found in the environment:
set ANTHROPIC_API_KEY for Anthropic, or AWS credentials (AWS_PROFILE or
AWS_ACCESS_KEY_ID) for Bedrock, or write [providers] in
~/.config/heph/config.toml

Check the wire

heph wire-check sends one small request through the whole stack, a tool call and thinking included, stores the reply, reads it back, and confirms nothing changed on the way. It is the quickest way to know that credentials, region, and model are all right before you spend a real turn:

$ heph wire-check
wire check passed
  provider     bedrock
  model        us.anthropic.claude-opus-5
  blocks       thinking, text, tool_use
  ...
  stop_reason  ToolUse
  cost         $0.0037
  ttft         1401 ms
  duration     2072 ms

--role quick checks the fast tier instead of the coding tier.

See what models there are

heph models lists every provider heph can talk to and every model in its catalog, with rates in dollars per million tokens and the context window:

$ heph models
anthropic (Messages, anthropic)
  claude-opus-5                  in 5.00  out 25.00  cache w 6.25  r 0.500  ctx 1000000
  claude-sonnet-4-6              in 3.00  out 15.00  cache w 3.75  r 0.300  ctx  200000
  claude-haiku-4-5-20251001      in 1.00  out  5.00  cache w 1.25  r 0.100  ctx  200000
bedrock (Bedrock, bedrock)
  us.anthropic.claude-opus-5     ...

These are the names you use in tiers and with --tier and --model. --all includes providers whose protocol heph does not speak yet, for completeness.