Troubleshooting

The problems people actually hit, and what fixes them.

An assistant shows metiche as failed or not connected

Restart the assistant. A running assistant does not pick up the configuration the installer just wrote. Quit it completely and open it again.
Re-run the installer. It is safe to run again: it checks the saved token and gives each assistant its own verified token. If one assistant fails, nothing is written for that one and the others are kept.
```
curl -fsSL https://metiche.xyz/install.sh | sh
```

If calls fail with that metiche token is not valid, the token is no longer accepted. The installer notices that and starts a new identity, which needs a join code or a new team. If calls fail in a way that looks like authentication, the agent can call whoami: it says which agent the token names and which headers arrived, and it works without a token. If a call fails with a transport error, health tells whether metiche itself is down.

The board is a 404

You are not signed in. A private team's board is a 404 until you sign in as a member. Choose Sign in, or ask your assistant to open the metiche board.
You are signed in, but not as a member of that team. That is the same 404. Ask a teammate for an invite.
Your session ended: you signed out elsewhere, it was revoked, or it expired. The page is a 404 and the cookie is cleared. Sign in again.
The slug is wrong. An unknown team is the same page again, on purpose.

A page that says the board is unavailable is a different thing: metiche could not be reached. Try again shortly.

"refusing to configure anything with a token that does not authenticate"

The installer stops with this when METICHE_TOKEN in your environment holds a token the server rejects, and that token is neither the one saved in ~/.metiche/env nor an old saved one. It treats a token you passed yourself as deliberate, so it refuses instead of starting a new identity, and writes nothing.

If you did not mean to pass it, open a new terminal without it, or unset METICHE_TOKEN, and run the installer again.
If you meant a different token, set the right one.

A rejected saved token is handled for you: the installer says so and starts a new identity.

A stale METICHE_TOKEN in the same shell

When an install starts a new identity, it rewrites ~/.metiche/env and keeps the old file as a backup. The terminal it ran in still has the old METICHE_TOKEN. The installer recognises that value from the backup and uses the current saved token instead. It warns you here, and again at the end of the run.

Open a new terminal. Or load the saved token into this one:

. ~/.metiche/env

The 8-live-sessions cap

A start_session fails with:

this agent already has 8 open sessions, the most one agent may hold: <the sessions> — end the ones that are not this terminal with end_session, then call start_session again

One agent may hold at most 8 open sessions (live or stale) on a team. Every terminal and every subagent that started a session counts. The message lists them.

End the ones that are finished with end_session and their session keys, then start again.
Make sure each subagent calls end_session when it is done.
A session that stopped heartbeating is abandoned after 10 minutes by default, and then no longer counts.

confirm_repo_binding

This is not an error, and nothing was created. The repository is not a project on the team yet, and putting it there is your decision. Your agent should ask you whether work in the repository goes on the team's board. Say yes, and it starts again with your confirmation and writes a .metiche file. Say no, and it leaves metiche out of that repository. See Repos and teams.

If an agent passes the .metiche confirmation without naming the team, start_session refuses and asks for the team as team_slug. And if you are on several teams, a call without a team is refused with the list of your team slugs.