Troubleshooting

Common problems and what to do about them.

Installing and launching

macOS says the app cannot be verified

Expected, and recoverable. The app is ad-hoc signed but not notarised — that needs a paid Apple Developer certificate — so macOS blocks the first launch. Open System Settings → Privacy & Security, find the line about Agento, and click Open Anyway.

If that line is not there:

xattr -dr com.apple.quarantine /Applications/Agento.app

Only the first launch needs this. Updates the app installs itself are not quarantined, so they never ask again.

macOS says the app is damaged and should be moved to the Bin

This is a different message, and it means the download predates the release that added ad-hoc signing. Those builds were not signed at all, and on Apple Silicon the linker’s own bare signature sealed nothing — Gatekeeper reads an invalid seal as “damaged”, which deliberately offers no Open Anyway.

Download the current release and install it over the old copy. If you would rather keep the copy you have:

xattr -dr com.apple.quarantine /Applications/Agento.app

Either way it is once; the app then updates itself normally.

Windows SmartScreen blocks the installer

Click More info, then Run anyway. The installer is not code signed, so SmartScreen has no publisher to recognize.

The AppImage will not start

Most often a missing FUSE library. Either install it:

sudo apt install libfuse2      # Debian, Ubuntu

or run without it:

./Agento_1.0.0_amd64.AppImage --appimage-extract-and-run

Also check the file is executable: chmod +x Agento_*.AppImage.

The .deb or .rpm will not install

Your package manager could not find GTK 3 or WebKitGTK 4.1. That usually means the distribution release is older than WebKitGTK 4.1. Use the AppImage instead.

The window opens blank or white

Your system’s webview is too old or missing.

Linux: install libwebkit2gtk-4.1-0.
Windows: install the WebView2 runtime. The installer normally handles this.

Restart the app after installing.

Launching Agento does nothing

It is probably already running. Agento allows one copy at a time, and a second launch focuses the existing window instead of opening a new one. Check your dock, taskbar or window list.

The Claude Code CLI

“Agento could not find the Claude Code CLI”

Agents run by launching claude. Agento resolves which binary that is once per launch, in this order — the first hit wins:

AGENTO_CLAUDE_EXECUTABLE, if it is set.
Settings → Claude → Claude Code CLI → Executable, if you have filled it in.
Your login shell — Agento runs $SHELL -lic 'command -v claude'.
Every directory on the PATH the app itself was launched with.
The known install locations: ~/.local/bin, ~/.claude/local, /opt/homebrew/bin, /usr/local/bin, ~/.nvm/versions/node/*/bin, fnm’s and asdf’s directories, ~/Library/pnpm, ~/.yarn/bin, ~/.bun/bin, ~/.volta/bin, ~/.npm-global/bin, ~/bin, and AppData/Roaming/npm on Windows.

A candidate found by 3, 4 or 5 has to answer --version like Claude Code, so an unrelated program of the same name on your PATH is skipped rather than run for every chat.

Step 3 exists because a GUI application does not inherit your shell’s PATH. An app launched from Finder, the Dock or Spotlight on macOS gets launchd’s /usr/bin:/bin:/usr/sbin:/sbin and nothing your .zshrc ever exported; a .desktop launch on Linux is only a little better. It is also the only step that can see an install made with claude migrate-installer, which puts the binary in ~/.claude/local and wires it up as a shell alias — so there is no binary on any PATH at all.

First check it works in a terminal:

claude --version

If that works and Agento still says it cannot find it, open Settings → Claude and paste the path into Executable. which claude gives you the path; if it prints an alias rather than a path, use the path from the alias. Restart Agento afterwards — resolution happens at launch.

The same pane shows what Agento did find and which of the five steps found it, which is what to read when the CLI it picked is not the one you expected.

AGENTO_CLAUDE_EXECUTABLE=/full/path/to/claude still works and still wins over everything, including the setting — but note that on macOS an app launched from the Dock cannot see a variable you exported in a shell, so the Settings field is usually the one you want.

Chats fail with an authentication error

Agento does not manage Claude authentication. Sign in with the CLI:

claude

Complete the sign-in there, then retry in Agento.

Chats

A chat is stuck mid-stream

Click Stop. If the composer is still blocked afterwards, reload the transcript from the toolbar.

If it keeps happening, check the log for the run. A claude subprocess that crashed ends the stream with nothing to say why, and the log is where the reason lands.

An agent will not use a tool

Tools are an allowlist. Open the agent and confirm the tool is ticked. For integration tools, also confirm that integration’s service is enabled and that its credentials are still valid.

The agent cannot see my files

Check the chat’s working directory. An agent only reaches the folder the chat was started in.

The agent keeps asking permission

Asking is the default in a chat, because you are there to answer. Each chat carries its own permission mode, so to stop the prompts for a conversation you trust, start it with Permissions → Never ask.

The setting is chosen when the chat is created and the inspector shows what a chat is running under. Existing chats keep whatever they were created with; chats created before this setting existed fall back to the agent’s mode, and to asking if the agent has no preference.

Unattended runs, meaning scheduled tasks, never prompt, because nothing could answer.

If a tool is denied without any prompt at all, it is not on the agent’s tool list. Add it there — the allowlist is enforced whatever the permission mode says.

History and analytics

The sessions list is empty

If it says “Scanning” with a count, the first index is still running. Wait for it.

If it says there are no sessions, Agento found no Claude Code history where it looked. Check Settings → Claude → Indexed directories covers the directory your transcripts are in. The default is ~/.claude.

Sessions from a second Claude account are missing

Add that account’s configuration directory in Settings → Claude → Indexed directories. Both accounts then appear in every total.

A project is missing from every chart

Check Settings → Data → Hidden projects. Unhiding is immediate and costs nothing.

Costs look wrong

Cost is computed from the price catalog in Settings → Pricing, at the price in effect when each message was sent.

A model with no entry contributes no cost, and the totals say how many tokens were unpriced.
If a price in the catalog is wrong, use Correct a rate, not “add a rate”. Correcting rewrites history; adding only affects messages after that date.

Either way, sessions re-price in the background afterwards. It can take a few minutes on a large history.

Durations look too short

They are meant to. Duration means active time, not the span from first to last message. A session resumed a week later would otherwise report a week. Adjust the threshold in Settings → Data → Idle gap threshold.

A scan seems to run for no reason

Some changes invalidate every stored figure and force a full re-read: a price edit, and a change to the idle gap threshold. That is expected, it runs in the background, and the app stays usable.

Scheduled tasks

A task never runs

Check, in order:

The task is Enabled.
The inspector shows a Next run in the future.
Stop after has not been reached and Stop at has not passed.
Agento is actually running. A desktop app that is closed fires nothing.

Every task fires twice

Two Agento processes are sharing one data directory. Agento normally prevents a second copy from starting, so this means one of them was pointed at the same directory deliberately with AGENTO_DATA_DIR. Close one, or give it its own directory.

A run failed with a timeout

The run took longer than the task’s Timeout. Raise it, or make the prompt narrower.

Integrations

Credentials stopped working after an edit

Re-enter them. Agento asks for credentials again when you edit an integration that has stored ones, because saving the form without them would wipe the working credential.

An OAuth window did not come back

Close the browser window and try Connect again. If your browser blocked the redirect to a local address, allow it and retry.

Tools from an integration are not offered to an agent

Three things have to line up: the integration is connected, the service is enabled inside it, and the tool is ticked on the agent.

“…tools were hosted but the Claude CLI did not offer them to the model”

Agento started the server and registered its tools, and the Claude Code CLI then gave the model none of them. The chat shows this as a notice on the turn; a scheduled task records it on the run’s row in Job History, which still reads success because the run itself completed. Everything else in the app reports the server as connected, which is why this message exists at all.

The tools are genuinely unavailable to the model for that turn, so it will say the tool does not exist. Nothing on the Agento side can be reconfigured to fix it — it is the CLI that dropped the list — but two things narrow it down:

The app log names the server and the missing tools, on a line beginning mcp tools not offered to the model. See Reading the logs.
The reason is in the CLI’s own debug log, which Agento never sees. Run one turn by hand with --debug-file and grep it:
Terminal window
```
claude -p --debug-file /tmp/cli.debug "hello"
grep -i mcp /tmp/cli.debug
```
A line like tools/list failed (Invalid result for tools/list: …) names the field the CLI rejected. Upgrading the Claude Code CLI, or updating Agento, is usually the fix — this is what a version skew between the two looks like.

WhatsApp is listed but unusable

Agento does not support WhatsApp. An integration created by an older version is still listed and its data is safe, but it cannot be edited or used.

These cover long polling, the inbound half, where a message to the bot runs an agent. Setting it up is in the user guide. The badge under Integrations → Telegram → Inbound uses the same five states as Slack’s, described below, and ERROR keeps retrying in the same way.

Telegram says something else is polling this bot token

The badge reads RECONNECTING or ERROR, and the reason under it starts with Something else is polling this bot token.

Telegram lets one program poll a bot at a time, and refuses the other with a 409 Conflict. The usual cause is a second Agento using the same bot token: an installed Agento and a development build (npm run app) both running, or Agento on two machines. Another program built on the same bot does it too.

Close the other program, or turn Long polling off in one of the two.
Or give each its own bot. @BotFather creates one in a minute.

The worker reconnects by itself once the other poller stops. Nothing needs restarting.

Telegram says a webhook is set for this bot

The reason starts with A webhook is set for this bot somewhere else. Agento removes a bot’s webhook when long polling starts, so this means something set one again afterwards, usually another program or a script calling setWebhook.

Turn Long polling off and on again. Agento removes the webhook and starts polling. If it comes back, find what is setting it and stop that.

Long polling says Connected but a message does nothing

The integration has no enabled trigger rule, or none whose prefix, keywords and chat ids match the message.
The chat is not in the rule’s Chat IDs. A rule answers only the chats it lists, and a message from any other chat is ignored without a reply.
The rule is off because it lists no chat ids. Its row says so; edit it and add at least one.
The message has no text. Photos, stickers and joins are received and ignored.
The bot is in a group with privacy mode on, so Telegram only gives it commands and replies. @BotFather → /setprivacy changes that.

The log lines worth knowing: telegram poll worker started / stopped, telegram poll: … attempt=N status=… for each failed attempt with its reason, and trigger rule matched … for a message that ran.

Slack

These cover Socket Mode — the inbound half, where a mention in a channel runs an agent. Setting it up is in the user guide.

What the Socket Mode badge is telling you

The badge under Integrations → Slack → Inbound is the connection’s own report, written by the worker that holds it. It renders in capitals, and there are five states:

Badge	Meaning
`NOT RUNNING`	Socket Mode is off, or no worker has run since the app started. Also what you see when Socket Mode is on and the app-level or bot token has since gone missing — Agento starts no worker for a connection that could not reply.
`CONNECTING`	The worker has started and is opening its first connection.
`CONNECTED`	The socket is open and Slack’s events are arriving.
`RECONNECTING`	The connection ended and the worker is waiting to try again — either because Slack asked it to (routine, several times a day) or because an attempt failed and it has not failed five times in a row yet. Hover the badge for the reason, when there is one — a reconnect Slack asked for has none.
`ERROR`	Five consecutive attempts failed. The worker is still retrying — this is a report, not a stop — so fixing the cause reconnects it without restarting Agento. The reason is under the badge in red, and on the badge as a tooltip.

RECONNECTING on its own is not a fault. The waits double from one second to a minute, and a connection that stayed up for a minute resets the count, so a healthy integration that Slack cycles never reaches ERROR.

“apps.connections.open refused the app token: invalid_auth”

The app-level token is wrong, revoked, or from a different app. Create a new one under Basic Information → App-Level Tokens with the connections:write scope, paste it into App token, and save — saving restarts the worker with it straight away, so the badge goes back to CONNECTING rather than waiting out the current backoff. Agento never clears a stored token on a refusal, so the old one is still there until you replace it.

Three things that look like this and are not:

apps.connections.open refused the app token: not_allowed_token_type — you pasted the bot token (xoxb-) into App token. It needs the xapp- one.
apps.connections.open answered 401 Unauthorized, not JSON — something between Agento and Slack answered instead of Slack, usually a proxy or a captive portal. Slack’s own refusals are always JSON, so this is never Slack.
opening the socket mode connection — the token was accepted and the websocket itself would not open (the line ends either : <reason> or timed out). Agento’s websocket does not use your system proxy settings, unlike every other call it makes, so a network that requires a proxy fails here and nowhere else.

Socket Mode says Connected but a mention does nothing

Every one of these is silent by design. Of the eleven, two say nothing in the log at all, seven are at debug level — so raise the level before you go looking — one is at info and one is at error. Two of the seven have a second, database cause that logs at warn or error just above them, and each says so below. Work down the list:

The app is not in the channel. Slack never sent the event at all — nothing appears in the log. /invite @Agento in that channel.
No trigger rule matches the channel. Log: slack mention ignored, no rule for the channel. Add a rule on the integration, or clear the channel list on an existing one — unless failed to load slack trigger rules is logged just above it at warn, in which case the rules could not be read at all and the rule is not the problem.
A rule names this channel and is disabled. Same log line. A rule that names a channel explicitly wins over a blank-list rule even when it is switched off, so disabling it silences that one channel rather than falling back. Turn it on, or take the channel out of its list.
The rule does not list the person who mentioned the app. Log: slack mention ignored, the rule does not list the sender. A Slack rule answers only its Allowed users, and a rule saved before that list existed has none, so after updating it answers nobody and its row reads No allowed users, not responding. Edit the rule and add the person’s Slack member id. When the rule starts a task, each of these is counted on that task.
The rule’s task is at its run limits. Log, at info: slack mention ignored, the rule's task is at its run limits, with reason=Dropped or reason=RateLimited. A task runs one message-started run at a time, keeps five more waiting and starts ten in any hour, unless its limits were changed. A mention past the queue is dropped and one past the hour’s count is rate-limited; each is counted on the task and gets no reply. Wait for the running one to finish or for the hour to move on.
The thread was not started by Agento. Log: slack mention ignored, a thread Agento did not start. Only a mention that starts a new thread can start a chat; inside an existing thread Agento answers only if it started it. Mention the app at the top level of the channel instead.
The message came from a bot. Log: slack socket: ignoring an app_mention from a bot. Agento ignores anything posted by another app or with a message subtype. There is no way to turn this off.
Nothing was said to the bot. Log: slack mention ignored, nothing said to the bot. The mention was the whole message; add the actual question after it.
Slack redelivered an event already handled. Log: already processed, and the reply is in the thread from the first delivery. The same line has a second cause: the claim that records the event failed, and claim_event answers “already handled” rather than risk running the agent twice against a database it could not write. Then there is no reply anywhere, and failed to claim slack event … is logged just above it at error.
The integration is in OAuth mode. Nothing is logged, because Slack sends nothing: Agento’s OAuth install does not request app_mentions:read, so the socket opens, the badge goes green and no mention is ever delivered. Socket Mode needs the Bot token mode and an app installed from the guide’s manifest.
The thread map could not be read on a mention inside an existing thread. Log: reading the slack thread map, and this one is at error, not debug — the only line in this list that is. A mention that starts a thread gets the error sentence instead; one inside a thread is dropped silently, because Agento cannot tell whether the thread was its own.

The rule form says “Couldn’t list members”

The Allowed users list on a Slack rule is read from Slack each time the rule section opens. When that fails the form shows the reason and falls back to a field of comma-separated member ids, so the rule can still be saved.

the Slack app needs users:read … (missing_scope). The app was installed without the users:read scope, which the guide’s Socket Mode manifest did not list before this picker existed. In the Slack app’s settings open OAuth & Permissions, add users:read under Bot Token Scopes, reinstall the app to the workspace, then choose Retry.
the Slack token was rejected. The bot token is wrong or revoked. Replace it under Bot token.
slack rate limited. Slack allows about 20 member-list calls a minute. Wait a minute and choose Retry.
the Slack integration is disabled or is not connected. The list is read with the integration’s own token, so the integration has to be on and connected first.

Until the list loads, add people by member id: open the person’s Slack profile, choose More, then Copy member ID.

The reply is “Sorry, something went wrong.”

That one sentence covers every failure of the run itself, so the log is the only place the reason exists.

One of the four is logged after the mention was matched, and three are logged instead of it. So look for a slack mention matched line first: if there is one, take its chat_id and grep for

agent execution failed for slack chat_id=… — the run failed or timed out. Timeouts are indistinguishable from failures in Slack; the rule’s Timeout is what bounds them.

and if there is not, the mention failed before it got that far and there is no chat id to grep for. One of these three is the reason:

slack inbound cannot identify itself — Slack refused auth.test, so the bot token is wrong or revoked. Replace it under Bot token.
failed to create chat session for a slack mention — the database write failed.
reading the slack thread map — the database could not be read.

A reply of “No response generated.” is different: the run succeeded and produced no text.

The answer arrives cut off

A reply longer than 4000 characters is posted as several messages, and posting stops at the first chunk Slack refuses — leaving a truncated answer with nothing marking it as truncated. The log has failed to send slack reply chunk N channel=… with Slack’s reason. The chat in Agento holds the whole answer.

Log lines to grep

These are all in the app log (Reading the logs):

grep -i slack Agento.log

Narrower patterns miss lines they look like they would catch — agent execution failed for slack chat_id=… and failed to send slack reply chunk … both put something other than the subsystem name after the word.

The ones worth knowing by name:

slack socket worker started / slack socket worker stopped — the switch.
slack socket mode worker hosted — the worker was started for this row.
slack inbound is enabled but no app token is stored / not starting the slack socket worker, no usable bot token — why it was not.
slack socket: … attempt=N status=… — one line per failed connection attempt, with Slack’s reason.
slack socket: … slack asked for a reconnect — the routine cycle.
slack mention matched … kind=start or kind=resume — a mention that ran, and whether it started a chat or continued one.
slack mention ignored, … — a mention that did not, and why.
failed to load slack trigger rules / failed to claim slack event … — a mention dropped because the database could not be read or written, not because of anything you configured.

Every slack mention ignored line is emitted at debug, as is the bot-message drop and the redelivery line; everything else listed above is info or louder. If the log shows a CONNECTED socket and nothing else at all, the level is what you are missing.

One thing to know before sharing a log: at debug level Agento records the text of a Slack mention, on the line slack mention prompt. It is the only place a message body is written to the log.

LLM Gateway

Overview says “Port unavailable”

Something else already holds that port. Change it in LLM Gateway → Gateway Settings → Port and save; the listener rebinds immediately.

The Settings form now checks the port as you type and offers a free one — “Port 8880 is already in use by another process. Port 8881 is free.” — so this state is usually avoidable. It is still only a check, not a reservation: something can take the port between the check and the bind, and this status is the authority on what actually happened.

The usual culprit is a second Agento. A development build and an installed one read different databases but share the machine’s ports, so both can be configured for 8880 and only the first to start gets it. The status carries the exact reason, and the same line is in the log:

binding the llm gateway on 127.0.0.1:8880: Address already in use (os error 98)

“Enable the gateway” is greyed out and will not turn on

The gateway has nothing to route to. Both Enable the gateway and Start with the app stay shut until there is at least one provider and at least one model alias — without both, the listener would bind a port that fails to route every model name a client sends, which is the mismatch below with nothing to mismatch against.

The message beside the switches says which of the two is missing and links to it. Add it, come back, and the switches are live; nothing needs restarting.

Two things it is not. It never turns a gateway off: an install that was already enabled keeps its switch usable in the off direction, so deleting your last alias does not lock you out of stopping the listener. And it never blocks Save — a retention or port edit still saves while the switches are shut.

If it instead says “could not check whether the gateway has anything to route”, the providers or aliases read failed rather than coming back empty. The switches are held for the same reason, and the message carries the underlying error.

“Check these credentials” says the key is refused, or the provider is unreachable

LLM Gateway → Providers → Check these credentials asks the provider to list its models, which authenticates the same credential a real request would. What it answers means:

Key refused (401/403) — the key is wrong, revoked, or out of credit. Some providers report an exhausted plan as 403 rather than 429, so a key that worked yesterday can land here. Re-issue it and use Replace key.
Unreachable — nothing answered at the Base URL, or it answered 404. That is the base URL rather than the key: a 404 means the address is not this provider’s API root. Leave it empty to use the provider’s own endpoint, except on GLM, which requires one.
Unexpected — the provider answered something else, and the status is shown beside the verdict. A 5xx is usually theirs rather than yours.

The check never sends your key anywhere but the provider, and no answer, log line or error message carries it back. That is also why changing Type on a provider that already has a key refuses with “the stored key belongs to a different provider type” rather than checking: the stored key is that vendor’s, and the new type decides which vendor it would be sent to. Enter the key for the type you have selected.

It can be wrong in one direction, and Save anyway is the answer. A base that serves completions but no model list — a proxy, something self-hosted, some OpenAI-compatible vendors — cannot produce a green verdict however correct the key is. Save anyway is beside Save for exactly that, and nothing is ever blocked behind a check.

Editing a provider asks for the API key I no longer have

It no longer does. A provider with a key stored shows ••••••••••• stored and saves without one — the save simply sends no api_key field, and the server keeps what it has. Replace key is what puts the input back on screen.

On a build predating that change the form did require a re-typed key on every save. There is no way to recover the stored one — it is write-only by design — so either update, or issue a new key at the provider and paste that in.

The model box on Models offers no list

LLM Gateway → Models fills a target’s model box from that provider’s own catalog, and shows a note under the row when it could not. It never blocks the save — type the id and carry on. The note says which of these it was:

No API key — the provider row has none stored, so there is nobody to ask. Set it in LLM Gateway → Providers.
The provider answered 401 / 403 — the key is wrong, revoked, or not entitled to the list endpoint. The same key is what serving a request would use, so this is worth fixing whatever the model box does.
The provider could not be reached — a wrong base URL, no network, a proxy, or an upstream that is simply slow; the fetch gives up after ten seconds.
The answer was not a model list — the base URL points at something that is not that provider’s API. Check it against Providers.
No models returned — the account is authenticated but the catalog is empty, which usually means a project or region with nothing enabled on it.

The list is fetched when you open the Models view, not when you save, so a slow provider never delays a save. It is not cached between visits: fix a key in Providers and come back to this view to see the list.

The gateway answers 401

The token is absent, malformed, expired, revoked, or was signed by a key this install no longer uses — regenerating the signing key does that to every token at once. Mint a new one from LLM Gateway → Overview and paste it into the tool again.

Check the tool is actually sending it: the gateway accepts either Authorization: Bearer <token> or x-api-key: <token>, and an Authorization header that is present but not a Bearer is ignored in favour of x-api-key.

The gateway answers 403

You used a read or write token. Those reach the Agento API and are refused here on purpose. Mint one with the llm scope — Overview’s Create gateway token button does exactly that — and use it instead.

A bigger Agento token is not the fix. The scopes are disjoint rather than ranked, so write does not include llm.

The Agento API answers 403 for a token that works on the gateway

The same rule the other way round. An llm token reaches the gateway and nothing under /api; there is no Agento API route that accepts one. Use a read or write token for the API.

The tool connects but every request fails with a model error

The name your tool sends as model has to be an alias you defined, exactly. There is no prefix parsing and no fuzzy matching, so an unconfigured name is a 404:

model alias 'claude-opus-5' is not configured on this gateway

For Claude Code this is the default first experience, because it asks for its own default model unless told otherwise and stops with “There’s an issue with the selected model”. Either export ANTHROPIC_MODEL=<your alias>, or name an alias after the model Claude Code asks for.

Claude Code cannot reach it at all

Check the base URL has no /v1. Claude Code and the Anthropic SDK append /v1/messages themselves, so ANTHROPIC_BASE_URL ends at /anthropic:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8880/anthropic   # right
export ANTHROPIC_BASE_URL=http://127.0.0.1:8880/anthropic/v1 # 404 on every call

The OpenAI-shaped base URL is the opposite and does end in /v1.

Nothing appears in Usage

A row is written per request the gateway served, so a request refused before it got that far — a bad token, a 404 on the base URL — records nothing on purpose. Confirm the listener is up and the request is arriving:

curl http://127.0.0.1:8880/healthz
curl http://127.0.0.1:8880/v1/models -H "Authorization: Bearer <your gateway token>"

/healthz needs no credential. /v1/models lists your aliases; if the alias you expect is missing or disabled, that is why traffic is not reaching it.

Usage shows requests but no cost

Cost is computed from the price catalog, which ships filled in for Anthropic, Moonshot, Z.ai and Alibaba models — so OpenAI and Gemini traffic has no rate. Anything unpriced is recorded as such rather than as free, which is why the total is labelled a floor. Add rates under Settings → Pricing for the models you actually use.

The gateway’s log lines

The same Agento.log as everything else — see Reading the logs. Gateway lines are prefixed llm gateway or gateway:

llm gateway listening on http://127.0.0.1:8880
gateway completion streaming alias=fast provider=my-openai model_id=gpt-4o-mini
gateway usage pruned rows=1204 older_than_days=90

Updates

The app says an update is available but there is no install button

You installed from a .deb or .rpm. Those are notify only, because your package manager owns the installed files. Download the new package and install it the way you installed the first one, or switch to the AppImage for in-app updates.

Can I go back to an older version?

Not below 0.1.1. That release added a database column, and Agento refuses to write to a database newer than itself rather than corrupting it — so an older build would appear to fail on every action.

Your data is not damaged by this. If you need an older build, restore the ~/.agento backup you took before upgrading.

The update download fails

Check your network and try again from About → Check for updates. Updates are downloaded from GitHub, so a proxy or a firewall that blocks it will stop them.

If it keeps failing, download the release manually and install over the top. Your data is untouched by a reinstall.

I do not want update checks

Settings → General → Updates → Never check.

Reading the logs

Platform	Path
Linux	`~/.local/share/com.shaharialab.agento/logs/Agento.log`
macOS	`~/Library/Logs/com.shaharialab.agento/Agento.log`
Windows	`%LOCALAPPDATA%\com.shaharialab.agento\logs\Agento.log`

The live file plus three dated archives are kept, roughly 20 MB in total.

The log records one line per API request, plus what each write did. It does not record message bodies, prompts, credentials or search terms — with one exception, at debug level only: the text of a Slack mention, on the line slack mention prompt (see Slack). It does record agent slugs and file paths, so treat it as mildly sensitive when sharing.

Still stuck

Open an issue at github.com/shaharia-lab/agento/issues with:

Your platform and how you installed (dmg, exe, AppImage, deb, rpm).
The Agento version from About.
claude --version.
What you did and what happened.
The relevant lines from the log.