GuidesHosting choices

OpenCode's opencode.db is huge and filling the disk

OpenCode 2 never shrinks opencode.db after deleting data, so it reaches many GB. How to check it, the fix's status, and the manual VACUUM users report.

November 20, 2026The Everpod team
The short answer

OpenCode 2 never gives back the space its database frees when old data is deleted, so ~/.local/share/opencode/opencode.db stays at the largest size it has ever reached, and users report files of many gigabytes, up to 17,203 MiB, that are mostly empty pages. It is a known, open bug, and as of 2.3.2 (November 18, 2026) no release fixes it and OpenCode has no command to shrink the file. What users report working is SQLite’s own VACUUM, run by hand with the service stopped and a backup made first: one file went from 17,203 MiB to 780 MiB with nothing lost. That is a user’s route, not an OpenCode instruction.

Why the file is so large

OpenCode 2 keeps sessions, messages and credentials in one SQLite file. When it deletes data, SQLite marks the pages free and reuses them later, but it only makes the file smaller if the database was created with auto-vacuum on, and the tracking issue states that OpenCode’s new databases “use auto_vacuum=NONE”. OpenCode’s database setup at the 2.3.2 tag sets no vacuum mode at all. So the file grows to its peak and stays there. In the reports, the empty part is most of it:

The 2.2.7 report also logged 474 of these in twelve minutes:

SQLiteError: disk I/O error
Copied

The thread did not establish that the size caused them. A disk that has actually filled is easier to tell from 2.3.1 on, whose release notes say “Storage problems name the cause (for example ‘Storage is full’ or ‘Storage is read-only’)”. On version 1 the usual cause of a huge file is different: an event table that grows without limit, 9 GB of an 11 GB file in one report.

See how big it is, and how much is empty

The file is at ~/.local/share/opencode/opencode.db unless OPENCODE_DB points elsewhere, per OpenCode’s troubleshooting page, with its -wal and -shm files beside it. Its size, and the disk’s, need no database tool:

ls -lh ~/.local/share/opencode/opencode.db*
df -h ~/.local/share/opencode
Copied

The same page says “Do not delete or edit service files or the database while troubleshooting” and to “make a backup before inspecting persistent data with external tools.” So stop the service, check that nothing else has the file open (an open terminal session, the desktop app, a --standalone run or an opencode serve under systemd all can, and any OpenCode command starts the service again), and copy all three files somewhere with room for them:

opencode service stop
fuser -v ~/.local/share/opencode/opencode.db*    # should list no process
mkdir -p /mnt/spare/opencode-backup
cp -p ~/.local/share/opencode/opencode.db* /mnt/spare/opencode-backup/
Copied

On a disk that is already full, the copy has to go to another disk or another machine, and room is not to be made by deleting OpenCode’s files. Then read how much of the file is free pages (on Ubuntu, sudo apt install sqlite3 first):

sqlite3 -readonly ~/.local/share/opencode/opencode.db \
  "PRAGMA page_size; PRAGMA page_count; PRAGMA freelist_count; PRAGMA auto_vacuum;"
Copied

freelist_count times page_size is the empty space in bytes, and an auto_vacuum of 0 means the file will never shrink on its own. If the free pages are a small share and the file is still large, it is your history itself, and compacting will not help much.

Whether a fix has shipped

Not as of November 20, 2026. The issue is open, and OpenCode’s triage bot files it as “a feature request, and maintainers will consider it.” Two pull requests that would have turned on incremental auto-vacuum were closed unmerged by the project’s stale-PR cleanup, and the remaining one, #58730, is open. As written it would change only new databases: it leaves existing ones as they are and notes that changing one “needs VACUUM, which cannot run while other processes share the file.” So even after a fix ships, a file that has already grown stays large until it is compacted once. Before acting, check the release notes and the issue for anything newer than 2.3.2.

The VACUUM users report

OpenCode documents no way to compact its database, and its troubleshooting page warns against editing it, so what follows is what users did and reported, not an OpenCode instruction. The replies on the 2.2.7 report that point to it are from OpenCode’s triage bot, not a maintainer, and repeat the conditions: “back up opencode.db first and run it with the service stopped.” With the backup made and nothing holding the file:

sqlite3 ~/.local/share/opencode/opencode.db "VACUUM; PRAGMA quick_check;"
ls -lh ~/.local/share/opencode/opencode.db*
opencode service start
Copied

quick_check should print ok. If it does not, or OpenCode misbehaves afterwards, stop the service and copy the three backed-up files back.

A VACUUM in place can need, in SQLite’s words, “as much as twice the size of the original database file” in free disk space, which a full disk does not have. So on a full disk, make room first by clearing files that are not OpenCode’s. Some users instead wrote a compacted copy to another disk with SQLite’s VACUUM INTO, which leaves the original untouched; putting such a copy in place of the live database is a replacement of OpenCode’s files that neither OpenCode nor the reports describe step by step, so the in-place route above is the one to prefer.

Afterwards the file is small again, but OpenCode still never reclaims space, so it grows back towards its old size with use. On a server that runs OpenCode unattended on a timer, watch the disk rather than wait for errors, and repeat the compaction when the free pages are large again, until a release says otherwise. The background service guide covers stopping and starting the service, and keeping it from starting while you work.

Run OpenCode on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.