Troubleshooting

Recover from Oyster startup problems, missing terminal dependencies, model connection failures and hosted funding errors without deleting your work.

Choose the section for the place you are using: the local Oyster trial, the Shiitake terminal, or hosted Fungi. They have different sign-in and funding requirements.

Oyster says port 8787 is in use

Leave the other server running and choose another port. From the directory containing your trial project:

npx @fungi.computer/oyster try my-oyster --port 8788

Use the address printed by this run. A browser tab pointing at port 8787 will still reach the other server.

Use the one-time link printed by the running trial. If it has already been used, open /login at that trial’s address and paste the owner key from my-oyster/.oyster-owner into the sign-in form. Keep the key private.

If you passed --no-open, keeping the browser closed is expected.

Trial startup stopped before the desktop was ready

Read the last phase and recovery command in the terminal. Check that Node is version 24 or newer and Git is installed. If startup has not finished after five minutes, press Ctrl-C in that terminal and keep the diagnostic path it printed.

Keep the project directory. After fixing the reported cause, restart from its parent directory:

npx @fungi.computer/oyster try my-oyster

From inside my-oyster, use npx @fungi.computer/oyster try instead. Do not delete the directory or stop unrelated services to retry. A desktop build warning still needs attention; it is not a successful setup.

Hello opens, but another App is not ready

The trial opens Hello first while Grove, Prints, Inkcap, Trellis, Bonsai and Shed prepare in the background. Check the desktop’s progress and the terminal for a failed phase. Follow that phase’s recovery command if it fails.

If you edited Hello and it no longer opens, keep its main.js script and commit your changes before restarting. Oyster builds committed source. Follow the Hello edit recipe.

Files are visible, but a command will not run

The trial can keep file access available when its Computer runtime fails to start. Look for the Computer warning in the trial terminal, fix that reported runtime problem, then restart the same project. Seeing files alone does not prove the shell is ready.

In Grove, also check which Computer is attached to the Agent. An Agent created with No Computer can converse but has no Computer for file or shell work.

An Agent cannot answer, or Prints cannot generate an image

An installed App does not supply model access. Connect a model for Grove and check the provider’s error if a request is refused. A saved credential does not prove that the provider accepts it or that its account has credit.

Prints image generation requires a deployed Oyster with Workers AI configured; the local trial alone does not provide that service. See deploying Oyster.

The terminal cannot find `fungi`

Spore installs that command. If you have not installed it, follow Install Shiitake. Otherwise, check that npm’s global executable directory is on your PATH, open a new terminal and run:

fungi --version

If the launcher reports missing native dependencies, reinstall with optional dependencies enabled:

npm install -g @fungi.computer/spore --include=optional

On Apple Silicon, use arm64 Node rather than x64 Node under Rosetta. Windows and Alpine Linux are unsupported; see the full platform requirements.

`fungi doctor` passes, but the model still fails

Doctor checks the supported platform, saved Fungi sign-in, model configuration and HTTP connectivity. It does not send a model prompt or check Team credit. Inside the conversation, use /model to check the selected provider and model. Signing in does not change the Session’s model automatically.

Your provider key or subscription uses that provider’s billing. Fungi hosted models use the selected Team’s billing. Follow terminal sign-in for the account you intend to use.

An App asks for access, or an Agent is denied a tool

Read which resource and operation the request names before approving it. Check that the App or Agent is working with the intended Team, Agent and Computer. Do not grant broader access just to make an unrelated error disappear. The permissions guide explains the boundaries and approval flow.

Hosted Fungi asks for credit or only shows the waitlist

Hosted signup is not open yet. An invite does not bypass the current waitlist; use Oyster locally or the terminal meanwhile.

Once hosted access is available, creating an account or adding your own model key does not fund hosted Agents and Computers. Open Your Teams → Billing for the Team you are using and check its available credit or Pro plan. Read Billing and credit for what each covers.

Before asking for help

Keep the installed version, operating system, exact command, failing step and error text. For the Oyster trial, keep its diagnostic path and project folder. Remove owner keys, provider tokens, sign-in links and private project content from anything you share. Check Fungi status for hosted service health; a local startup failure may have a different cause.