Skip to main content

Status and troubleshooting

Kenaz, a Kameas AI product.

Check your setup​

CommandWhat it shows
kenaz statusSign-in, organization and plan, device name, credential store, enrollment, whether the relay is running, which telemetry classes are on, what is queued or held, setup state for Claude Code and Codex, and memory. --json prints it as JSON (schema_version 1).
kenaz doctorA checklist of the environment, state directory, credential store, relay and its port, sign-in, memory, clock and setup, each marked ok, warn or info.
kenaz setup doctorWhat setup configured in Claude Code and Codex, including the plugin registration.
kenaz versionThe version and build flavor. Official builds say official; a build you compiled from the public source says unofficial and can't connect to Kameas Fleet. kenaz version --json adds the source commits.
kenaz approvalsWrite requests waiting for approval, and whether an authenticator is set up.
kenaz memory sync statusWhether memory sync is on and what is queued.

In Claude Code, /kenaz:status asks Claude Code to summarize the same information.

Most commands take --env prod|stage|dev for the Kameas Fleet environment (default prod).

The relay starts on demand, when a Claude Code or Codex session starts or when you run kenaz login or kenaz setup, and stops on its own when it's idle. relay: not running (starts on demand with your next session) in kenaz status is normal between sessions.

Common problems​

"Kenaz for Claude Code and Codex is in early access. Contact sales@kameas.ai to join."​

Kameas Fleet refused this device because your organization isn't in the early-access program (error code fleet_plugin_early_access_required). kenaz login and kenaz setup print this message, and kenaz status shows enrollment: early_access_required.

  • If your organization hasn't joined, contact us.
  • If it has joined, an owner or admin may still need to accept the Early Access Addendum on the Agent harnesses page in Kameas Fleet.

Then run kenaz login again. Until then, kenaz status says: "Nothing is being collected or held on this device until your organization joins early access."

approval_unavailable​

A write that needs your approval couldn't get one, so nothing was written. Check, in order:

  1. No authenticator is set up. Run kenaz approvals enroll and set up a security key or your device's unlock.
  2. No OS keychain. If kenaz status shows credential store: files (no OS keychain), approvals are always unavailable on this machine. Use a machine or account with a working OS keychain (on Linux, the Secret Service).
  3. Unofficial build. If kenaz version doesn't say official, install an official build from the download page.

identity_mismatch​

The request was not sent: the account you're signed in with isn't the one it was prepared or queued for. This happens after you sign out or switch accounts between preparing a request and sending it. Nothing is sent to the other account. When you sign in as a different account, usage data from the previous account that hadn't been sent yet is deleted from this device, never sent. Sign in with the original account (kenaz login) if you still want it, or ask your agent to prepare the request again.

On the approval page, the same problem reads "This request belongs to a different signed-in account." During authenticator setup, the browser sign-in must use the same account as kenaz login.

"Kenaz approvals: this page was not opened."​

You opened an approval link from a web page, chat or email. The approval page only opens when you go to it directly. Copy the link from your terminal, or run kenaz approvals to print it, and paste it into your browser's address bar.

The page runs at http://localhost:<port>/approvals/. A link to 127.0.0.1 is redirected there; any other host is refused.

"This request expired. Ask your agent to prepare it again."​

Requests expire 5 minutes after your agent prepares them. Ask your agent to prepare it again, and approve it within 5 minutes.

kenaz init can't edit your shell profile​

kenaz init can't edit /Users/you/.zshrc (the file is not writable). To put kenaz on PATH, add this to it yourself:

kenaz init changed nothing and printed the line to add. This happens when the profile:

  • is read-only ("the file is not writable");
  • isn't a regular file ("the file is not a regular file");
  • has a # >>> kenaz PATH >>> line without the matching # <<< kenaz PATH <<< line. Fix the file by hand.

Either add the printed line to the profile yourself, or make the file writable and run kenaz init again. Then open a new terminal.

kenaz init can't edit /Users/you/.zshrc (the file is a symbolic link to a file that does not exist). ...

Your profile is a symbolic link, for example from a dotfiles manager, and the file it points to is missing. kenaz init edits a linked profile where the link points, but it won't create the missing file. Restore the file the link points to (or remove the broken link), then run kenaz init again; or add the printed line yourself.

kenaz init doesn't edit your shell​

kenaz init edits profiles for zsh, bash and fish. For any other shell it prints the directory to add to your PATH yourself.

Setup says the plugin is installed but turned off​

warning: the Kenaz plugin (kenaz@kenaz) is installed in Claude Code but turned off, so it will not run. ...

You installed the plugin and then turned it off. Setup leaves that choice alone: it doesn't turn the plugin back on, and kenaz setup --undo doesn't uninstall it. To turn it on:

  • Claude Code: claude plugin enable kenaz@kenaz.
  • Codex: set enabled = true under [plugins."kenaz@kenaz"] in ~/.codex/config.toml, or turn it on in Codex's /plugins.

Then restart the tool.

Setup says a "kenaz" marketplace is already there​

You added a kenaz marketplace from somewhere other than GitHub's kameas-ai/kenaz-plugin, for example a local folder. Remove it (claude plugin marketplace remove kenaz or codex plugin marketplace remove kenaz) and run setup again. The kenaz marketplace from GitHub is used as it is, so it doesn't cause this. See Claude Code and Codex.

The one-line installer stops​

  • "sha256 mismatch for …; refusing" or "manifest and checksums.txt disagree …; refusing": the download didn't match the release. Nothing was installed. Try again.
  • "cosign could not verify checksums.txt …; refusing": the signature check failed. Nothing was installed.
  • "--require-signature: cosign is not installed": install cosign, or run the installer without --require-signature.
  • "~/.local/bin/kenaz already links to …" or "… exists and is not a symlink": another kenaz is already there, and the installer never replaces it. Remove it, or pass --bin-dir to link somewhere else.

OS keychain unavailable; try again or run kenaz logout to reset​

kenaz recorded the OS keychain as its credential store, but can't reach it now (for example, the keychain is locked). Unlock it and try again. kenaz logout resets the choice, and the next kenaz login chooses again.

Verification stops on a noexec temporary directory​

scripts/verify-release.sh (Install → Check where a binary came from) runs a copy of the binary from $TMPDIR. If $TMPDIR is mounted noexec, it stops with "its temporary directory is probably on a noexec filesystem". Set TMPDIR to a directory where programs can run and try again:

mkdir -p "$HOME/tmp"
TMPDIR="$HOME/tmp" ./kenaz-plugin/scripts/verify-release.sh --checksums checksums.txt \
  --name kenaz_0.4.1_linux_amd64 ~/.kenaz/install/current/bin/kenaz v0.4.1

install.sh refuses to run (manual install)​

  • "bundle verification failed": a file in the extracted folder differs from SHA256SUMS. Download the archive again and verify it.
  • "bundle directory … does not match bundle.json": run install.sh from the folder the archive extracted to, without renaming it.
  • "version … is already installed with different contents": an installed version is never overwritten. Download that version again and verify it.
  • "another install.sh … is running": wait for it to finish. If none is running, see Roll back for removing a stale lock.

Nothing shows up in Kameas Fleet​

  1. kenaz status: are you signed in, and is at least one class on? If not, run kenaz optin.
  2. kenaz setup doctor: is Claude Code or Codex configured? If not, run kenaz init (or kenaz setup claude or kenaz setup codex), then restart the tool.
  3. kenaz doctor: is the relay's port the one in your settings? With managed settings pinned to port 4318, a machine where that port is taken reports the mismatch here.
  4. kenaz status also shows when uploads are held because your organization paused them or is in lockdown. Your agent isn't blocked while uploads are held.

Claude and Claude Code are trademarks of Anthropic, PBC. OpenAI and Codex are trademarks of OpenAI. Kenaz and Kameas are trademarks of Kameas AI, Inc. Kenaz for Claude Code and Codex is an independent product of Kameas AI, Inc. and is not affiliated with, endorsed or sponsored by Anthropic or OpenAI.