Troubleshooting

Installation fails with "command not found"

After installation, running nokey shows "command not found".

Solution:

The installation directory is not in your PATH. Add it manually:

AI assistant still accessing protected files

Your AI coding assistant seems to bypass nokey protection.

Solution:

1. Verify nokey is running: nokey status
2. Check if the file pattern is protected: nokey config show
3. Ensure your AI assistant is configured to work with nokey
4. Restart your AI assistant after installing nokey

Permission denied errors

Getting "permission denied" when running nokey commands.

Solution:

The nokey binary may not have execute permissions. Fix with:

Audit logs not appearing

Running nokey logs shows no entries.

Solution:

1. Check if audit logging is enabled: nokey config show
2. Verify log file location has write permissions
3. Ensure AI has actually attempted to access files
4. Check for errors: nokey status --verbose

High CPU or memory usage

nokey is consuming excessive system resources.

Solution:

• Check audit log size: large logs can slow down operations
• Reduce retention period in config: retention_days
• Add more patterns to ignored_patterns to reduce monitoring overhead

Configuration changes not taking effect

Updated configuration but nokey still uses old settings.

Solution:

1. Validate your config file: nokey config validate
2. Check for YAML syntax errors
3. Ensure you're editing the correct config file (project vs global)
4. Restart nokey after configuration changes

Does nokey work with all AI coding assistants?

nokey is designed to work with most AI coding assistants including Claude Code, Cursor, GitHub Copilot, and others. However, some assistants may require additional configuration. Check the Configuration Guide for specific setups.

Will nokey slow down my AI assistant?

nokey is designed to have minimal performance impact. File access checks are extremely fast, typically adding less than 1ms per request. You shouldn't notice any slowdown in normal usage.

Can I use nokey in a team/enterprise setting?

Yes! nokey is perfect for teams. Commit your .nokey.yaml configuration to version control so all team members use the same protection policies.

For enterprise deployments, you can also set up centralized audit log collection and monitoring.

What happens if I temporarily need to allow AI access?

Use the nokey allow command to temporarily grant access:

Is nokey open source?

Yes! nokey is fully open source under the MIT license. You can audit the code, contribute improvements, or fork it for your own needs on GitHub.

Can I disable nokey temporarily?

Yes, set the environment variable:

Or unset it to re-enable: unset NOKEY_DISABLE

How do I update nokey?

Run the installation command again - it will download and install the latest version:

How do I uninstall nokey?

Remove the binary and configuration:

On Windows: Remove-Item -Recurse $env:LOCALAPPDATA\nokey