Assistant failures
Mecha runs on the machine, so most failures here are the machine not being ready or the link being spent. Each entry names the cause and the fix.
This machine's assistant is not ready yet
Section titled “This machine's assistant is not ready yet”Cause. Mecha answers on the machine, and the machine is not answering for it yet. It is stopped, it is still starting, or Mecha is not up on it. The refusal carries one more fact that the console reads: whether asking again can succeed without anything changing. It cannot while the machine is stopped.
Fix. Start the machine and open Mecha again from its page:
deployport machinery start <machine-id>Verify. The machine reads Online in the console’s Machines list, and the Assistant control opens Mecha.
Could not reach the assistant on this machine
Section titled “Could not reach the assistant on this machine”Cause. The console reached the machine’s assistant address and nothing answered with a conversation. A stopped machine answers with a page instead, which is why this sentence is the console’s own rather than Mecha’s.
Fix. Check the machine is running, then open Mecha again:
deployport machinery start <machine-id>Verify. The conversation renders in the tab, and the machine’s Chat tab shows its latest conversation.
That link no longer opens this machine's assistant
Section titled “That link no longer opens this machine's assistant”Cause. The address carries a single-use code, which works once within three minutes, and the session it opens lasts 12 hours. A bookmarked address, a link opened twice, and a session whose permission was withdrawn since it opened all answer this one sentence.
Fix. Open Mecha from the machine’s page in the console again. The console mints a new address for each open, so a fresh address always works.
Verify. Mecha opens with the machine’s conversations, which are stored on the machine’s disk and survive a stop.
A teammate opens Mecha and is refused
Section titled “A teammate opens Mecha and is refused”Cause. Reaching Mecha runs commands as root on the machine, so it needs the action machinery:BeginAssistantSession over machinery:Machine(<machine-id>). A policy that lets somebody reach the machine over ssh does not grant it, and a policy scoped over every machine grants it on every machine. The refusal reads access denied, the same as any other denied action.
Fix. Attach a policy that allows that action over the machines they need:
deployport iam users policies attach --username <username> --policy <policy-name>Write a policy builds the file, and Identity policy JSON reference has the grammar.
Verify. They open Mecha from the machine’s page, and deployport iam identity-policy show <policy-name> prints the statement that allows the action.
Sign in as a user to open this machine's assistant
Section titled “Sign in as a user to open this machine's assistant”Cause. A session records the principal that opened it, and Machinery asks about that principal by name on every request the edge makes, so a withdrawn permission ends an open session rather than only the next one. Only a user can be asked about by name, so a session opened with a role’s temporary credentials or a service account’s is refused.
Fix. Open Mecha from the console, signed in as your user.
Verify. The Assistant control opens Mecha, and the machine’s Chat tab shows the conversation it starts.
Still stuck
Section titled “Still stuck”Ask us at Contact and include:
- the machine id, from
deployport machinery list - the address you opened, and whether it was from the console or a bookmark
- the time it happened, with your time zone