zo-datasets-explorer

A private Zo Space data explorer powered by Datasette. Browse and query your SQLite and DuckDB datasets from an embedded iframe viewer — with owner-only authentication baked in.

Packaged as a .zopack.md file for one-command deployment to any Zo Space.

---

What it does

• Lists your registered SQLite and DuckDB datasets from a configurable directory list
• Launches a Datasette viewer on demand (converts DuckDB → SQLite on the fly)
• Proxies all Datasette traffic through a Zo Space API route with owner auth
• Embeds the viewer in an iframe inside a clean dark-themed React page

Routes included

Path	Type	Visibility	Description
/datasets	page	private	Dataset list + embedded Datasette viewer
/api/datasets/list	api	public	Returns configured datasets as JSON
/api/datasets/start	api	public (auth-gated)	Starts Datasette on port 8003 for the requested dataset
/api/datasets/proxy/*	api	public (auth-gated)	Proxies all Datasette requests; strips CSP/X-Frame headers

API routes are always publicly reachable at the network level in Zo Space, but /api/datasets/start and /api/datasets/proxy/* both enforce owner-only authentication via X-Zo-User header and Zo session cookies.

Requirements

• A Zo Computer account with a Zo Space
• Datasette installed on your Zo server: pip install datasette
• (Optional) duckdb Python package for DuckDB support: pip install duckdb
• Datasets organized in directories containing a datapackage.json

Deploy

Give this .zopack.md file to your Zo and say:

"Deploy this zopack"

Zo will parse the file and deploy all 4 routes to your Zo Space automatically using the import process from the zopack skill.

Configuration

After deploying, edit two routes to register your datasets:

/api/datasets/list — add your dataset directories to DATASET_CANDIDATES:

const DATASET_CANDIDATES = [
  { id: "my-db", dir: "/home/workspace/Data/my-db", type: "SQLite" },
  { id: "analytics", dir: "/home/workspace/Data/analytics", type: "DuckDB" },
];

/api/datasets/start — add the same entries to KNOWN_DATASETS:

const KNOWN_DATASETS = {
  "my-db": { dir: "/home/workspace/Data/my-db", type: "SQLite" },
  "analytics": { dir: "/home/workspace/Data/analytics", type: "DuckDB" },
};

Each dataset directory should contain a datapackage.json (standard Frictionless Data format) and a .db, .sqlite, or .duckdb file.

Authentication model

The {{HANDLE}} placeholder in the route code is replaced with your Zo handle during import. Auth passes if any of these are present:

• X-Zo-User header matches your handle
• Request carries a Zo session cookie (zo_session or auth_token)
• Referer / Origin / X-Forwarded-Host headers come from *.zo.computer or *.zo.space

Tech stack

• Zo Space — Bun + Hono API routes, React page routes, Tailwind CSS 4
• Datasette — SQLite browser and query UI
• lucide-react — icons (pre-installed in Zo Space)

---

Built with Zo Computer · Packaged with zopack