When a login expires

An agent that is signed out does nothing, on a box that looks healthy. How Watch tells you a login has expired, and the steps to sign in again on the box.

On this page

What it costs you #

An agent's login to its vendor does not last for ever. When it lapses, every session in that environment stops, and nothing about the box says so: it is up, it is reporting, and no work is being done. Left alone it stays that way until you next look.

Watch tells you instead, and the fix is five minutes on the box.

How you hear #

What Watch sees What you get
A session stops, and the agent says it is signed out The session shows as Login expired, and one urgent alert
The agent server stops while the box stays up The environment shows as Down, and one urgent alert that names an expired login as a common cause
The box reports when the login will expire One alert a day ahead

The first is the certain one. The alert is titled "The login for client-a on agentbox has expired", and its body is the fix in a line:

Login expired
A session on client-a stopped because its agent is no longer signed in. On the box, as the agent user, run claude and sign in again. Steps: https://nucarium.dev/watch/expired-login

You get one alert for each session that stops this way, and none for a session that reports the same thing twice.

How Watch knows #

When a turn ends in an error, the agent gives its hook a short fixed word for the kind of error. nucleated sends that word and nothing else about the error. Watch reads authentication_failed as a login that has expired, and shows the session as login expired, not as failed.

That word is all Watch has. It never sees the error's message, the account, or anything about the login itself.

A stopped agent server is a guess, and Watch says so. An agent server that exits sends nothing: the heartbeats simply stop saying it is alive. Watch cannot tell an expired login from a crash or a vendor outage. So the "environment down" alert, and the environment's page, say that an expired login is a common cause and link here. If signing in again does not bring it back, Troubleshooting has the other causes.

A day ahead #

Where a box can read when its agent's login will expire, it sends that time with each heartbeat: a time and nothing else. Watch then alerts you once, a day before, with the title "The login for client-a on agentbox expires soon", and the environment's page shows when the login expires. A login that is renewed gets a new time, and a new warning when that one comes due.

Claude Code gives a box no way to read that time. On a Claude Code box nucleated sends none, so this warning does not fire: you hear when the login has expired, not before.

Sign in again #

Log in to the box as the agents' user:

Workstation
ssh agentbox-agent

Start Claude Code:

Boxas agent
claude

For any login but the box's first, start it with that login's folder, the one its environment's config_dir names in the daemon's config:

Boxas agent
CLAUDE_CONFIG_DIR=/home/agent/.claude-second claude

It prints a sign-in link. Open it on your workstation and sign in with the account that environment works for. Then leave with /exit.

Now look at the environment's agent server:

Boxas agent
systemctl --user status agent-server@client-a.service --no-pager

If it says active (running), leave it alone. If it does not, start it:

Boxas agent
systemctl --user restart agent-server@client-a.service

What happens next #

Watch does not see you sign in. Each row changes when the thing it describes next reports:

  • The sessions. Send each stopped session a prompt from your vendor's app. It goes back to Working, and you get one "moved on" for it.
  • The environment. If its agent server had stopped, the next heartbeat says it is alive again, and you get one "environment recovered".

A session that still shows login expired after you have signed in has not been sent anything yet.