OpenAI-compatible

Use Hermes Agent with IteraCompute

Connect a terminal agent to IteraCompute.

Connect in three steps

1. Create an API key

Create or sign in to your IteraCompute account, then create a key in the Console.

2. Configure the base URL

Configure a named custom provider with chat_completions. The Python AIAgent and CLI configurations are separate profiles.

3. Select the model

Use the exact API Model ID for your chosen model. Check its context and capabilities before enabling agent or vision features.

Choose your model

DeepSeek V4.1 Flash 1017 is the paid reference model. You can replace it with a published conversation model allowed by your key. Recheck model permissions, prices, context and tool support after switching; the examples follow your selection, while the retained test results remain tied to Qwen.

Prepare an isolated environment

Use an isolated Hermes Agent v0.23.0 checkout and HERMES_HOME. Export ITERACOMPUTE_API_KEY in the launching terminal.

Bash / macOS / Linux / WSL
git clone --branch v0.23.0 --depth 1 \
  https://github.com/NousResearch/hermes-agent.git hermes-agent-v0.23.0
cd hermes-agent-v0.23.0
test "$(git rev-parse HEAD)" = \
  "2bd378ed1b8d6bf2192cb26e0a55ff3091e6bd19"
export HERMES_HOME="$PWD/.hermes-iteracompute-cli"
export HERMES_RUNTIME_DIR="$HERMES_HOME/tools"
umask 077
mkdir -p "$HERMES_HOME"
source ./activate
hermes --version
hermes pm doctor
Bash · key in the current terminal
umask 077
read -rsp 'IteraCompute API key: ' ITERACOMPUTE_API_KEY
printf '\n'
export ITERACOMPUTE_API_KEY

Hermes CLI may add reasoning_effort=medium for an unknown custom model. Confirm the actual request against the selected model parameters. reasoning_config={} below is a Python constructor option, not a YAML setting or proof that CLI reasoning is disabled.

Example configuration

Keep API keys in your server environment or tool credential store. Replace the example key field with your own key where applicable.

CLI · $HERMES_HOME/config.yaml
providers:
  iteracompute:
    api: https://api.iteracompute.com/v1
    key_env: ITERACOMPUTE_API_KEY
    transport: chat_completions
    default_model: deepseek/deepseek-v4.1-flash-1017
    context_length: 1048576
    discover_models: false
    extra_body:
      max_tokens: 512
model:
  provider: custom:iteracompute
  default: deepseek/deepseek-v4.1-flash-1017
  context_length: 1048576
  streaming: false
agent:
  max_turns: 3
  api_max_retries: 0
  auto_recovery_cycles: 0
fallback_providers: []
toolsets: [todo]
tools:
  tool_search:
    enabled: off
approvals:
  mode: manual
compression:
  enabled: false
auxiliary:
  title_generation:
    enabled: false
    model_upgrade_enabled: false

Save this configuration only in the isolated profile created above. These Chat Completions examples start with 512 output tokens and no fallback. Context metadata is not an account entitlement; OpenClaw uses a smaller input budget. The Qwen selection uses 128K account context. Reasoning controls vary by model: the Python and OpenClaw examples add reasoning: false only for Qwen; do not transfer that option to other models.

Check the direct API first

Python · direct text check
python3 - <<'PY'
import json
import os
import urllib.error
import urllib.request
payload = {
    'model': 'deepseek/deepseek-v4.1-flash-1017',
    'messages': [{'role': 'user', 'content': 'Reply with exactly: ITERACOMPUTE_API_OK'}],
    'max_tokens': 512,
    **{},
}
request = urllib.request.Request(
    'https://api.iteracompute.com/v1/chat/completions',
    data=json.dumps(payload).encode('utf-8'),
    headers={'Authorization': 'Bearer ' + os.environ['ITERACOMPUTE_API_KEY'],
             'Content-Type': 'application/json'}, method='POST',
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f'HTTP {exc.code}; inspect redacted details privately') from None
except (urllib.error.URLError, TimeoutError):
    raise SystemExit('Network or timeout failure; no automatic retry') from None
choice = result['choices'][0]
if ((choice.get('message', {}).get('content') or '').strip() != 'ITERACOMPUTE_API_OK'
        or choice.get('finish_reason') != 'stop'):
    raise SystemExit('FAIL: expected final marker and stop reason not returned')
print('Direct API text passed; test the agent separately')
PY

This sends one real request when you run it. Confirm the exact visible marker and finish_reason=stop; an empty HTTP 200 response is incomplete. Paid model calls consume API balance. Do not automatically retry an unknown outcome.

Check the agent text path

Bash · text check
hermes chat --oneshot --ignore-rules --toolsets todo --max-turns 2 \
  --format stream-json \
  -q 'Do not call tools. Reply with exactly: HERMES_ITERACOMPUTE_OK' \
  > hermes-text.private.jsonl 2> hermes-text.private.stderr

Run the direct API check below first, then require a non-empty final marker, the intended provider/model and a clean exit from the agent. Configuration validation and a provider probe do not prove an agent or tool workflow.

Verify one tool round trip

The CLI profile above is a documentation reference. For the Python route, create a different HERMES_HOME inside the activated checkout, save the following config.yaml there, and save the Python script as iteracompute_agent_smoke.py. Do not combine the two profiles.

Bash · separate Python profile
export HERMES_HOME="$PWD/.hermes-iteracompute-python"
mkdir -p "$HERMES_HOME"
Python profile · config.yaml
model:
  provider: custom
  default: deepseek/deepseek-v4.1-flash-1017
  base_url: https://api.iteracompute.com/v1
  streaming: false
providers:
  custom:
    request_timeout_seconds: 240
    stale_timeout_seconds: 240
tools:
  tool_search:
    enabled: off
agent:
  api_max_retries: 0
  auto_recovery_cycles: 0
fallback_providers: []
compression:
  enabled: false
auxiliary:
  title_generation:
    enabled: false
    model_upgrade_enabled: false
iteracompute_agent_smoke.py
import os
from run_agent import AIAgent

agent = AIAgent(
    provider="custom",
    api_mode="chat_completions",
    base_url="https://api.iteracompute.com/v1",
    api_key=os.environ["ITERACOMPUTE_API_KEY"],
    model="deepseek/deepseek-v4.1-flash-1017",
    enabled_toolsets=["todo"],
    max_iterations=3,
    max_tokens=512,
    run_budget_seconds=600,
    reasoning_config={},
    request_overrides={"extra_body": {}},
    skip_context_files=True,
    skip_memory=True,
    skip_background_review=True,
    load_soul_identity=False,
    save_trajectories=False,
    quiet_mode=True,
    fallback_model={},
)
try:
    result = agent.run_conversation(
        "Call todo_list exactly once to write one item with id smoke-1, "
        "content API smoke test, and status completed. Then read the tool result "
        "and reply with exactly HERMES_ITERACOMPUTE_TOOL_OK. Do not use other tools."
    )
    if not (result.get("completed") is True and
            (result.get("final_response") or "").strip() == "HERMES_ITERACOMPUTE_TOOL_OK"):
        raise SystemExit("FAIL: inspect redacted details privately")
    print("Final marker passed; verify actual todo_list events separately")
finally:
    agent.close()
Bash · run Python agent
python iteracompute_agent_smoke.py

Success criterion: inspect a real todo_list call, its completed smoke-1 item, the returned tool result and the final HERMES_ITERACOMPUTE_TOOL_OK reply. The script checks the final marker only; tool events need separate inspection. Three iterations and zero configured retries are not a strict HTTP-request or spending cap.

Version and verification

Tested version
Hermes Agent v0.23.0
Result
Non-streaming Python tool calls passed.

Credentials, tools and data

The model API runs remotely; no local GPU or public Gateway port is needed. The agent still needs local CPU, memory and permissions. Keep keys in the launching process environment, keep raw logs private, and enable only the tools needed for your test. External tools and services have their own setup and costs.

Test the connection

cURL · Chat Completions
# Bash / zsh / WSL; set ITERACOMPUTE_API_KEY in your environment first.
curl --fail-with-body https://api.iteracompute.com/v1/chat/completions \
  -H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"max_tokens":512}'

Check that choices[0].message.content contains visible text; HTTP 200 alone is insufficient. Reasoning may consume the output budget. For free Auto, use the first free call example to disable thinking, then send a prompt inside your tool.

Selected model capabilities

Capabilities describe the IteraCompute API. Feature availability in your workflow also depends on the tool and its settings; reasoning controls vary by model.

  • Chat CompletionsSupported
  • Tool callingSupported
  • ReasoningSupported
  • Image inputSupported
  • StreamingSupported

Troubleshooting

401 / 403 / 404

Check the launching process key, model permission and paid balance. Keep /v1 once in the base URL. Send the raw Model ID to the API; the iteracompute/ prefix belongs only to OpenClaw routing.

400 / Empty reply / 429

Check model-specific reasoning parameters, output budget and account limits. Honor Retry-After. Do not stack reasoning dialects, infer success from HTTP 200 or switch to another paid model automatically.

Tool missing / Wrong profile

Hermes: disable tool_search for the todo test and keep Python and CLI profiles separate. OpenClaw: replace deny-all with read-only for the tool test; do not use --isolated or --auth-env-only with this custom config.

Hermes Agent configuration reference →

Start building with Hermes Agent.

Connect your key, choose a model and send your first request.