Data and Lifecycle

Portside keeps metadata and database data in two separate places, and every lifecycle action maps to exactly one thing it touches. This page is the full contract.

Where data lives

What	Where	Survives app removal?
Instance metadata (engine, version, port, state)	SQLite at %LOCALAPPDATA%\portside\portside.db	Yes, stored outside the repo
Actual database data	Docker volume per instance, named portside-{id}-data	Yes, until you drop the volume
Container lifecycle	Docker, managed by Portside	N/A

All state lives outside the repository; a fresh clone carries no data, no .env files, and no dumps. node_modules/, dist/, and src-tauri/target/ are the only build outputs, and they are git-ignored.

Lifecycle actions

Action	Container	Data volume	Portside metadata	Recovery?
Inactivate (stop)	Stopped	Kept	Keeps state	Resume restarts the same container
Remove	Dropped	Kept	Kept	Data can be reattached if metadata survives
Wipe	Dropped	Dropped	Dropped	None - confirms first

Inactivate

Inactivate stops the container but keeps the data volume. Use it to free RAM or pause an agent's database mid-experiment. Resuming restarts the same container against the same volume, so nothing is lost.

Remove

Remove drops the container but keeps the data volume. Use it to reclaim the container while holding on to the data - for example after an agent finished work you want to inspect with a standalone client. Remove is reversible in the sense that the volume persists on disk; the container can be re-created against that volume.

Wipe

Wipe drops both the container and the data volume. This is the "the experiment is over" action for the agentic workflow: the agent got its sandbox, the sandbox goes away. Portside asks for confirmation first, and there is no restore afterward.

The agent loop, end to end

flowchart LR
    A["Create instance\n(engine, version, port, password)"] --> B["Copy connect string\ninto agent env"]
    B --> C["Agent prototypes\nfreely in isolation"]
    C --> D{"Done?"}
    D -- "keep researching" --> C
    D -- "wipe" --> E["Wipe instance\nvolume dropped"]
    D -- "pause" --> F["Inactivate\nvolume kept"]

Passwords and recreation

Passwords are applied when the container is first created and cannot be changed afterward. To rotate a password: create a replacement instance with the new password, migrate (or dump and restore) data if needed, then wipe the old instance. Because instances are cheap and disposable by design, rotation is usually cheaper than fighting a doctored server.

Version upgrades and version pinning

Versions are pinned at creation (they are Docker tags). "Upgrading" an engine means creating a new instance at the newer version and migrating data across with a dump; the old instance's volume stays intact until you wipe it. Two versions running side by side makes this a copy-paste exercise rather than a production upgrade.

Cleanup hygiene

Long-lived agent sessions create volumes fast. If disk usage creeps:

• Wipe instances whose agents are done - the volume is what uses the space.
• Inactivated instances still hold their volumes; wipe rather than accumulate if the data no longer matters.
• Stale volumes survive in Docker even after the Portside metadata DB is reset; prune them with Docker's own volume tooling if you have ever deleted portside.db by hand.