Preview Environments

A preview is a live, per-ticket environment you can boot on demand: Spedy clones your project's repository, restores a database snapshot, and starts the application (e.g. Shopware or Magento). You see the running shop in an iframe next to the ticket — and it's where the AI coding agent makes its changes.

How it works

When you open a ticket and start its preview, Spedy boots a container stack that:

1. clones the project's preview repo,
2. restores a database snapshot, and
3. starts the application.

Each ticket has exactly one preview. The preview URL is unique to your organization and only reachable with a valid Spedy session — see Security & isolation.

Bringing your own stack? If your repo ships its own docker-compose.yml instead of using a Shopware/Magento template, see Preview Config (BYOC) for the .spedy/preview.yml file that tells Spedy which service and port to route.

Prerequisites

Before a project can boot previews, your organization needs an active GitHub integration under Settings → Integrations. Without it, the repository section shows a hint instead of the repo picker.

Set up a project

Open Project → Settings → Preview.

Connect a repository

In the Repository section:

1. Click Connect repo and pick a GitHub repository from the dropdown (the list comes from your organization's GitHub integration).
2. Confirm the base branch (pre-filled from the repo).
3. Click Connect.

The freshly connected repo is automatically marked as the preview repo (green badge). A board can have several repositories (e.g. for the runner or CI) — but exactly one is the preview repo. Use Use for preview to move the marker to a different repo.

The preview container clones this repo on every boot. Branches and commits made by the AI agent are pushed here.

Upload a database snapshot

Without a snapshot, a fresh preview boots with the empty demo database. For realistic data, use the Database snapshots section:

1. Give it a name (e.g. prod-baseline).
2. Choose a .sql or .sql.gz dump (up to 4 GB).
3. Click Upload.
4. On the entry, click Set as default → it gets a green Project default badge.

The project default is restored into every preview of the project. You can override it per ticket — see Override the database per ticket.

Use the preview in a ticket

Click the preview icon in the ticket header (or open …/tickets/<id>/preview directly). The first time, it shows "Preview is off" — click Start preview. The first boot takes ~30–60 s (container start + repo clone + snapshot restore); after that it's seconds.

Once it's up, the left half shows the shop in an iframe, the right half the ticket panel and agent:

Idle timeout

While the preview tab is open, a heartbeat keeps the container alive. After ~15 minutes of inactivity it stops automatically — just start it again next time.

Override the database per ticket

To boot a specific ticket against a different dump (for example, to reproduce a customer-specific bug), open the ticket → Properties tab → Preview DB field.

Resolution order at boot (highest priority first):

1. Per-ticket override (this field)
2. .spedy/snapshots/<branch>.sql.gz in the repo
3. Project default (see above)
4. .spedy/snapshots/default.sql.gz in the repo
5. Template seed (empty demo database)

The selection takes effect on the next container boot — a running preview keeps its database until it restarts.

Security & isolation

• Organization isolation. Each preview gets an org-unique slug, so two organizations never collide — even with the same board prefix. Every request to a preview is checked against the caller's organization.
• Session-gated. The preview URL is only reachable with a valid Spedy session and only for your own organization.
• Private repos. Cloning private repositories uses your organization's connected GitHub credentials.

Troubleshooting