# Connection & bootstrap troubleshooting

Load this when a connect (bootstrap) run or an `awesomate_*` call is failing.
Wrong-account / profile / pin problems → `references/multi-account.md`.
No `awesomate_*` tools registered in the session at all →
`references/rest-fallback.md`.

## How the bootstrap runs

`scripts/bootstrap.mjs` is what the hub's Connect-Claude-Code prompt executes,
via `npx -y --package=@awesomate/hosting-mcp awesomate-hosting-bootstrap`.
Always the `--package=` form — a bare `-p` breaks the claude CLI's argv
pre-scan if the command is ever wrapped in `claude mcp add`. It redeems the
hub setup code for a scoped access token, stores it locally (chmod 600),
installs this skill into `~/.claude/skills`, registers the MCP server, and
(Support Plus+, best-effort) generates an SSH keypair and registers the public
key. If the SSH step fails (e.g. hosting not fully provisioned), the token +
skill + MCP are still set up.

## Reading the connect result

The bootstrap prints a final `AWESOMATE CONNECT: SUCCESS account=<slug>` (or
`PARTIAL … issues=…` / `FAILED reason=…`) sentinel — when a connect ran as a
`!` bang command, check for that line instead of assuming success from
silence. `PARTIAL` means the token/pin are stored but a step (listed in
`issues=`) needs the printed manual fix.

`FAILED reason=profile-belongs-to-someone-else` means this computer is already
connected to the same account as a different person (an owner and a team member
sharing a computer). Nothing was saved. Ask the person at the computer which key
should stay; re-run with `--replace` only on their clear yes, never on your own.
Otherwise they connect from their own user account on the computer. The key made
by the refused run is unused: they can remove it in the hub at Settings,
Account, Your Claude Code.

## Sandboxed / ephemeral environments (cloud agent containers)

- **Egress proxy**: if `HTTPS_PROXY`/`HTTP_PROXY` is set, the environment
  forces traffic through a proxy that Node's built-in fetch ignores — requests
  bypass it and the gateway answers 403, which looks like a bad code/token but
  is a transport failure. The bootstrap and MCP server handle this themselves
  (undici env-proxy agent); if an older version is in play, prefix commands
  with `NODE_USE_ENV_PROXY=1`. Diagnostic: `curl` works but `node -e "fetch(…)"`
  403s → proxy bypass, not credentials.
- **Interrupted connect?** Setup codes are re-runnable for their whole
  10-minute life (each run mints a fresh token). After that, copy a fresh
  Connect command from the hub and run it; never put a token on a command
  line, where it lands in the chat and the shell history. Never tell the user
  their code is spent unless the API literally said so.
- **`ENOTEMPTY` from npx**: a half-written npx cache, not an Awesomate
  problem. Clear it with `rm -rf ~/.npm/_npx`, then run the same command
  again. The bootstrap can't catch this itself: npx fails before it starts.
- **Nothing persists**: `~/.awesomate`, the skill copy, and the MCP
  registration all vanish with the container. Treat a container connect as a
  diagnosis/test, and tell the user a real workstation is needed for a lasting
  install.
- **No ssh client**: containers usually lack `ssh-keygen`/`ssh`, so deploy and
  shell are unavailable — reads and management calls still work. The bootstrap
  skips SSH with a note rather than failing.
- Never probe connectivity with a POST to `/redeem` — it's state-changing. Use
  `GET {apiBase}/api/hosting-access/context` (401 without a token still proves
  reachability).

## When you're stuck: generate a support report

If a connect or tool failure survives the documented fixes (wrong account,
proxy, resume, restart, legacy registrations), don't keep guessing — hand
Awesomate a diagnostic they can act on:

1. Run `node ~/.claude/skills/awesomate-hosting/scripts/support-report.mjs
   --note "<one line: what the user was doing and what happened>"`.
   It writes a **fully redacted** report to
   `~/.awesomate/support-report-<timestamp>.md` — tokens reduced to
   prefix+last4, no key material, proxy credentials stripped. It includes
   versions, profiles/pin/registration state, live connectivity probes, and
   the last bootstrap log automatically.
2. Show the user the file path and the headline findings (the ACTIVE line,
   any ⚠ LEGACY registration flags, and the probe results).
3. **Ask the user before submitting.** With their OK, re-run with `--submit`
   — it POSTs the report to Awesomate and returns a reference like
   `ASR-XXXXXXXX`. Tell the user to quote that reference to
   support@awesomate.ai or their Awesomate contact; the report is already
   attached to it server-side. Submission works even when the token is
   broken (that's usually why you're here).
4. If `--submit` fails too (fully offline), the user emails the file itself —
   it's safe to send as-is.

Never edit the report to add raw tokens, codes, or keys, and never submit
without the user's explicit go-ahead.