Troubleshooting

Quick reference

Issue	Solution
`command not found: symbiotic`	Make sure the install location is in your PATH and restart your terminal: the npm global bin directory (`npm config get prefix`, then `bin/`) for npm installs, or `~/.symbiotic/bin` for the install script
Authentication fails	Verify your token is valid in the portal and hasn’t expired
Permission denied	Run `chmod +x ~/.symbiotic/bin/symbiotic` (install script), or see Installation issues for npm installs
`Configuration is invalid at ...`	A config file contains an unknown key or a wrong value type. The message lists the file and the offending key; see Configuration issues
`Config file at ... is not valid JSON(C)`	Fix the syntax error at the reported line and column
Can’t go to the next line	Use one of these keybindings: `shift+return`, `ctrl+return`, `alt+return`, or `ctrl+j`

Logs

Symbiotic Code writes log files to:

macOS/Linux: ~/.local/share/symbiotic/log/
Windows: %USERPROFILE%\.local\share\symbiotic\log

Log files are named with a timestamp (e.g., 2026-01-09T123456.log) and only the most recent 10 are kept. To get more detail, raise the log level or print logs directly to your terminal:

symbiotic --log-level DEBUG          # DEBUG, INFO (default), WARN, ERROR
symbiotic run "hello" --print-logs   # print logs to stderr instead of a file

Storage

Symbiotic Code uses these directories (on Windows, under %USERPROFILE%):

Directory	Content
`~/.config/symbiotic/`	Global config (`symbiotic.json`, `tui.json`, `AGENTS.md`, agents, commands, plugins…)
`~/.local/share/symbiotic/`	Data: `auth.json` (credentials), `mcp-auth.json`, `symbiotic.db` (sessions), `log/`, `snapshot/`, `bin/` (downloaded tools and language servers)
`~/.cache/symbiotic/`	Cache: model catalog, installed npm packages for plugins
`~/.local/state/symbiotic/`	TUI state: recent models, prompt history, key-value settings (such as the current security mode)

Run symbiotic debug paths to print the exact paths on your machine. These follow XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME, and XDG_STATE_HOME if set.

auth.json contains your API keys and tokens. Don’t share it or include it in bug reports.

Configuration issues

See the final config: symbiotic debug config prints the fully merged configuration for the current directory, so you can check which value actually wins. See Configuration file for precedence.
Unknown key errors: the config schema is strict. Typos or keys from other tools cause Configuration is invalid. theme and keybinds belong in tui.json, not symbiotic.json.
bad file reference: a {file:...} substitution points to a file that doesn’t exist. Relative paths are resolved from the directory of the config file.
Settings not applied in a project: a project symbiotic.json, a .symbiotic/symbiotic.json, SYMBIOTIC_CONFIG_CONTENT, or a managed config may override your global value.
Isolate project config: start with SYMBIOTIC_DISABLE_PROJECT_CONFIG=1 symbiotic to ignore all project-level config and rule files.
Check agents and skills: symbiotic debug agent <name> shows an agent’s resolved configuration, and symbiotic debug skill lists the skills that were discovered.

Plugins causing crashes or hangs

If Symbiotic Code crashes on startup or behaves strangely after adding plugins:

Start once with SYMBIOTIC_PURE=1 symbiotic to skip external plugins listed in plugin.
If that fixes it, remove entries from plugin in your config, or temporarily move plugin files out of ~/.config/symbiotic/plugins/ and .symbiotic/plugins/, then re-enable them one at a time.
If a plugin install is stuck, quit Symbiotic Code and delete ~/.cache/symbiotic/ so it is rebuilt on the next start.

Installation issues

Windows

If you have trouble installing Symbiotic Code on PowerShell, try launching the install command with Git Bash, which you can download here. If the issue is related to PowerShell execution policy, run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

On Windows, shell commands run in Git Bash when it is found next to your git installation, otherwise in cmd.exe. If Git Bash is installed in a non-standard location, set SYMBIOTIC_GIT_BASH_PATH to the full path of bash.exe.

Permission denied (macOS/Linux)

If you get a permission error when installing globally:

# Option 1: Use sudo
sudo npm install -g @symbioticsec/code

# Option 2: Configure npm to use a user directory
mkdir ~/.npm-global
npm config set prefix "~/.npm-global"
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Automatic updates

Symbiotic Code checks for updates when the TUI starts and upgrades itself using the same method it was installed with (npm, pnpm, yarn, bun, or the install script). If automatic updates fail (for example because the global npm directory is not writable), update manually with npm install -g @symbioticsec/code, or disable updates with "autoupdate": false in ~/.config/symbiotic/symbiotic.json or SYMBIOTIC_DISABLE_AUTOUPDATE=1.

Platform-specific issues

Copy/paste not working on Linux

Linux users need one of the following clipboard utilities installed for copy/paste to work. X11 systems:

apt install -y xclip
# or
apt install -y xsel

Wayland systems:

apt install -y wl-clipboard

Headless environments:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

Symbiotic Code will detect if you’re using Wayland and prefer wl-clipboard, otherwise it will try xclip then xsel.

Using Symbiotic Code in a Docker container

Download the script and Dockerfile here
Unzip the file
Launch Docker Desktop
Make the script executable:

chmod +x run-symbiotic.sh

Run the script:

./run-symbiotic.sh

You are now inside the container and can run the symbiotic command to launch the coding agent.

Network and connectivity

If you’re behind a corporate firewall or proxy, you may need to allowlist the following domains for Symbiotic Code to connect to the API:

api.symbioticsec.ai:443
llm-proxy.symbioticsec.ai:443
app.symbioticsec.ai:443 (browser sign-in)

Symbiotic Code also fetches the model catalog from models.dev. If it is blocked, set SYMBIOTIC_DISABLE_MODELS_FETCH=1. Language servers are downloaded on demand from GitHub and npm; set SYMBIOTIC_DISABLE_LSP_DOWNLOAD=1 to turn this off. Proxy configuration: Symbiotic Code honors the standard HTTPS_PROXY / HTTP_PROXY environment variables. To install through a corporate proxy, also configure npm:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

npm registry blocked: If the npm registry is inaccessible:

Check proxy settings: npm config get proxy
Verify your firewall allows access to registry.npmjs.org:443
Contact IT to whitelist the npm registry

Health check script

Run the following command to verify that your system is ready for Symbiotic Code:

curl -fsSL https://raw.githubusercontent.com/SymbioticSec/mintlify-docs/refs/heads/main/assets/symbiotic-health-check.js | node

The script checks:

Node.js — Ensures Node.js is installed (v14+ recommended)
npm — Verifies npm is available
Global install permissions — Tests ability to install global npm packages
Execution policy (Windows only) — Checks PowerShell execution policy
Proxy configuration — Displays current proxy settings
npm registry access — Tests connectivity to registry.npmjs.org:443
Required endpoints — Tests connectivity to:
- api.symbioticsec.ai:443
- llm-proxy.symbioticsec.ai:443

Once all checks pass, install with:

npm install -g @symbioticsec/code

If issues persist, save the health check output and contact support:

curl -fsSL https://raw.githubusercontent.com/SymbioticSec/mintlify-docs/refs/heads/main/assets/symbiotic-health-check.js -o symbiotic-health-check.js
node symbiotic-health-check.js > healthcheck-results.txt 2>&1

Need help?

Contact us using the dedicated Slack channel or email us at support@symbioticsec.ai with your health check results, the latest log file from ~/.local/share/symbiotic/log/, your OS version, and network environment.

Basics

Customize

Security

Configuration

Quick reference

Logs

Storage

Configuration issues

Plugins causing crashes or hangs

Installation issues

Windows

Permission denied (macOS/Linux)

Automatic updates

Platform-specific issues

Copy/paste not working on Linux

Using Symbiotic Code in a Docker container

Network and connectivity

Health check script

​Quick reference

​Logs

​Storage

​Configuration issues

​Plugins causing crashes or hangs

​Installation issues

​Windows

​Permission denied (macOS/Linux)

​Automatic updates

​Platform-specific issues

​Copy/paste not working on Linux

​Using Symbiotic Code in a Docker container

​Network and connectivity

​Health check script

Quick reference

Logs

Storage

Configuration issues

Plugins causing crashes or hangs

Installation issues

Windows

Permission denied (macOS/Linux)

Automatic updates

Platform-specific issues

Copy/paste not working on Linux

Using Symbiotic Code in a Docker container

Network and connectivity

Health check script