importarr/AGENTS.md

Importarr Agent Instructions

Importarr is owned as a Linux-ops-managed service repository. Treat this checkout as the source of truth for application code, deployment files, and local service installs.

Repository Source Of Truth

• Work from /srv/opencode-workspace/importarr for Importarr code and deploy changes.
• Do not edit host-local legacy scripts as the normal workflow:
  • /usr/local/sbin/importarr-status.py
  • /usr/local/sbin/manual-media-import.py
• If an emergency hotfix is made outside the repo, backport it here immediately and reinstall from the repo.

Seamless Feature Workflow

When asked to implement an Importarr feature, fix, UI change, deployment change, or operational behavior change:

1. Inspect git status --short --branch before editing.
2. Implement the smallest correct repo change.
3. Run the narrowest useful verification, normally:

   .venv/bin/pytest -q
   

   If shell deploy scripts changed, also run:

   sh -n deploy/systemd-install.sh && sh -n deploy/repo-upgrade.sh
   

4. Inspect git diff and ensure no secrets, raw .env, tokens, databases, or private material are included.
5. Commit and push completed Importarr changes by default unless the user explicitly asks not to publish or verification is blocked.
6. Install/restart from the repository so the running local service matches the repo:

   make upgrade-local
   

7. Verify the live service:

   make verify-live
   

8. If the live install fails, inspect systemctl status importarr.service and journalctl -u importarr.service; fix the repo, commit/push the fix, reinstall, and verify again.

Install Model

• The service virtualenv lives at /opt/importarr/venv.
• The systemd unit runs /opt/importarr/venv/bin/importarr as the importarr system user.
• The package is installed from the repository into the venv using normal wheel/package install, not editable install.
• Do not use editable install for the system service: the unprivileged importarr user may not be able to read /srv/opencode-workspace/importarr, causing ModuleNotFoundError at startup.
• /opt/importarr/repo-upgrade.sh is the pull-and-reinstall helper for machines that should follow pushed main.

Local Commands

make test
make install-systemd
make upgrade-local
make repo-upgrade
make verify-live

make repo-upgrade is for pulling already-pushed changes with git pull --ff-only. It refuses to run with uncommitted repo changes.

Runtime Defaults On This Host

• Local URL: http://127.0.0.1:8095/
• Health: http://127.0.0.1:8095/health
• Status: http://127.0.0.1:8095/api/status
• Systemd service: importarr.service
• Env file: /etc/importarr/importarr.env
• SQLite state: /var/lib/importarr/importarr.db

Secret Handling

• Prefer *_FILE settings for secrets, for example:
  • IMPORTARR_SAB_API_KEY_FILE
  • IMPORTARR_AUTH_TOKEN_FILE
  • IMPORTARR_RADARR_API_KEY_FILE
  • IMPORTARR_SONARR_API_KEY_FILE
• Never commit real env files, API keys, tokens, private keys, service databases, or backup data.
• Template files may list variable names with placeholder values or commented examples only.

Linux Ops Follow-Through

For changes that materially alter the live service setup, ports, routes, monitoring, backup coverage, or host ownership, also follow the linux-ops documentation/systems-overview update rules. Do not mix unrelated pre-existing uncommitted changes from linux-ops-docs or systems-overview into Importarr commits.