Studio

Spiral Studio is where you and your team look at the data your application produces. You browse the Projects in your Organizations, open a Table, and inspect its rows without writing code.

Studio runs in two places:

Download the desktop appCopy Anchor Link

1. Open Local engine settings in the web app.
2. Under Desktop app, select the download button.
3. Choose macOS (Apple silicon) or Linux (x86_64) from the menu.

The button suggests the platform of the browser you are using, but you can download either build from any browser.

Sign inCopy Anchor Link

Select Sign in in the desktop app. Studio opens your browser, where you can continue with Google, GitHub, or email. After you finish, Studio continues automatically. Return to the app; you can close the browser tab.

If your version opens a device activation page, update Studio before signing in. Studio no longer supports device-code sign-in.

While waiting, select Open browser again to start a fresh sign-in request, or Cancel sign-in to stop. If the request expires, select Sign in again. Studio keeps its session in your operating system's credential store, separately from the CLI.

Manage workload identitiesCopy Anchor Link

Open Workloads in the Project sidebar to create an identity for a CI job, pipeline, or service. Add an OIDC trust policy from a provider template or your own issuer and claims, or paste or drop a public JWK or SSH .pub file for a job that keeps its own private key. The list contains workloads defined in this Project. Grant a role separately in each Project the workload needs to access; new workloads start without credentials or permissions.

The tab is available in both the web and desktop apps. It manages live definitions and credentials across all branches, independently of the selected commit. Open a workload to configure it, then use All workloads to return to the list. Credentials lists its trust policies and public keys. In Project access, choose a target Project to inspect, grant, or revoke this workload's roles there. Managing access requires permission in the target Project. See Create a workload for roles, credential setup, and revocation.

Manage ApplicationsCopy Anchor Link

Open Applications in the Project sidebar to register an Application or edit its redirect URIs. These registrations belong to the selected Project and use its stack. See Register an Application.

Open Organization from the account menu, then Installed applications, to manage the Applications installed for your Organization. Connected applications in the account menu lists the Applications you personally authorized. See Install an Application and Connected applications.

Look at Tables and LocationsCopy Anchor Link

Open a Table to page through its rows, filter them, and inspect a row in full. Studio reads the rows straight from storage through ScanDAL, with your own sign-in, so you see exactly the version that the selected branch or commit names. Image columns show as images. Open a Location to see the files its last refresh listed, as a table or as a gallery.

The desktop app runs ScanDAL inside the app, so it reads Tables on your own disk and caches what it reads. The web app reads through hosted ScanDAL, or through your own machine once you connect it.

Connect the web app to your machineCopy Anchor Link

Run spiral connect to serve Table reads and SQL on your machine for the web app. The web app reads Tables on your own disk and caches reads on your machine. When the command stops, Table reads can use hosted ScanDAL again; SQL stops until you reconnect.

uvx --refresh --from 'spiral-cli[sql]' spiral connect --web-ui-url https://studio.spiraldb.com/

The command opens a pairing link in your browser. The link hands the web app the address and a secret for this run of the command, and the web app sends that secret with every local request. The command answers only on this machine and allows the paired web app's origin. Your browser may also ask permission for the page to connect to this machine.

Query Tables with SQLCopy Anchor Link

The desktop app and the web app paired with Connect have a SQL editor. Queries run on your machine through DataFusion over the Tables at the selected branch or commit, so you query exact versions. Name a Table by its path, quoted when it contains a dot or slash. Spiral's own statements, such as creating or refreshing a resource, are not SQL here: use the matching action in Studio. SQL accepts one read query; writes and DDL are unsupported.

In the web app, open the pairing link from spiral connect before running a query. Connect uses your web sign-in to authorize Project and Table access. SQL runs only on the paired machine; if it disconnects, reconnect and rerun the query. Spiral does not provide hosted SQL execution.

The SQL endpoint uses your API bearer token and accepts managed storage. Local-file Tables remain available through the paired ScanDAL Table browser. Studio bounds the editor's preview by adding a SQL limit; the SQL API itself streams the complete submitted query result.

By default, Connect runs up to ten SQL queries at once across current and legacy Tables, each with an 840-second deadline, 256 MiB for DataFusion operators and a 1 GiB result limit. Set these environment variables before starting Connect to change the limits:

SPIRAL_CONNECT_SQL_CONCURRENCY also sets the number of concurrent scans for requests with legacyTables, so ten independent Table scans can run together without changing the default.

For requests with legacyTables, the earliest storage credential expiry can shorten the query deadline, with a one-second safety margin. Table scans enforce separate request limits; native reader memory is additional to the DataFusion allowance, so it is not a limit on total process memory. Queries fail when their limits are exceeded and do not spill to disk. Cancel a running query to stop reading its result.

Create and change resourcesCopy Anchor Link

Select Create resource in the resource list to add a Table, Location, or Connection to the selected branch. Studio publishes the change only if the branch still points at the snapshot you opened, so you never overwrite a change you have not seen.

• Table. Choose an Arrow IPC file (.arrow or .feather). Its rows become the Table's first version. A Table's schema comes from what is written to it, so Studio does not edit it afterwards.
• Location. Enter the root URI and, for a private bucket, the Connection that reads it.
• Connection. Choose the provider, then the credential. Spiral never returns the secret.

Rename or drop a resource from its menu. Dropping a Location also drops the file list Spiral keeps for it.

Run Tasks on this machineCopy Anchor Link

In the desktop app, actions that submit a Task can run it on your own machine instead of on a Worker: Refresh on a Location or a Vector Index, and Maintain and Flush WAL on a keyed table. Open the action's options menu and choose Run on this machine, then run the action. Submit Task, which hands the Task to a Worker, stays the default.

Studio submits the Task claimed by you, so no Worker Pool takes it, and runs it inside the app as your signed-in account, as spiral-host worker run does. Each Attempt runs in its own process, so cancelling the Task stops it. The action shows the Task's progress and its result, and the Task appears in Tasks like any other. Keep Studio open until the Task ends: if you quit, no Worker takes the Task over, and it fails with not_claimed after five minutes unclaimed. The web app submits Tasks to Workers only.

Open keyed tablesCopy Anchor Link

Keyed tables appear beside catalog Resources in the resource list. A filled table icon identifies each keyed table. Open Data to inspect up to 200 rows, apply filters, and expand a row. Schema shows the column types. These reads use live data: changing the selected branch does not select an older version of a keyed table. Select Refresh to read its latest state.

Studio reads keyed tables through ScanDAL in the desktop and web apps. The web app uses hosted ScanDAL, or your machine when paired with Connect. Tables stored on a local disk require desktop Studio or Connect. Refresh resolves a new live read snapshot. Inline images can appear in previews. Loading images or video from URI references in keyed tables is not yet supported. A preview that exceeds its time or size limit fails with an error; narrow the filters before retrying. If a preview cannot connect to the table's storage, Studio identifies the storage connection failure. Select Retry; if it keeps failing, ask your administrator to check connectivity from hosted ScanDAL or your connected machine to the storage provider. Expand Error details on a failed preview or schema read to inspect the full message, available causes, and service error ID. Include that ID when reporting a problem so an administrator can find the matching server logs.

1. Open a Project.
2. Select a keyed table from the resource list.
3. Select Data, Schema, Tasks, or Details.

Run maintenanceCopy Anchor Link

• Select Maintain to save pending writes, compact data files, and apply deletions so later reads can skip deletion records already included in the data.
• Select Flush WAL to save pending writes without compaction.
• Select Set up automation to run either action on an interval.

The options menu selects Worker capacity, or, in the desktop app, running on this machine. Each submitted Task includes a link back to its keyed table.

While compaction runs, the Task shows the column group name, its position in the current pass, and the Split, Size-based, or Overlaps step. The percentage measures operations in that batch. Reaching 100% does not mean a commit was saved: splitting and the following merge share a transaction. Committing column group shows publication in progress; the last confirmed compaction commit includes its group and timestamp. These details require a Worker that reports them.

Deletion application runs after compaction, including when compaction stops at its pass limit or makes no further progress. It supports column groups that use the table's keys; groups that add keys, such as list elements, are skipped. Each group saves its applied-deletion boundary before the next group starts. The Task shows the current group and its position in the deletion pass. Within that group, it shows fragments checked, rewritten or removed, and left unchanged. These counts describe work, not remaining time. Publication and saving the checkpoint have separate status labels; finishing the fragment check alone does not mean the Task is complete. Older clients and reads of older versions continue to work.

Inspect Tasks and automationsCopy Anchor Link

1. Select Tasks to inspect the history for this keyed table.
2. Use the status, type, or search filters to find a Task.
3. Select Automations to inspect schedules for this table.
4. Select Create automation to choose maintenance or a flush action.

Keyed tables support interval schedules. Their writes do not produce the Project journal events that start event hooks.

AvailabilityCopy Anchor Link

Creating or revising a Vector Index or an Enrichment, and previews of a Location's files are planned; until then, the gallery lists the files' names and sizes.

AppearanceCopy Anchor Link

Studio uses the Spiral Design System across its web and desktop interfaces. Neutral surfaces frame the data, and Blue identifies focus and selection. Headings and controls use Acid Grotesk. Body text uses Inter, and code uses Geist Mono. Resource icons keep their colors across lists, dialogs, and detail views. Sidebar menu icons use the text color. A shared type scale separates headings, controls, body text, captions, and chart labels.

The General section in Settings offers Light, Dark, and System appearance options. System follows the appearance preference of your device. Studio respects the reduced-motion preference of your device.

GuidesCopy Anchor Link

• Windows and Organizations: switch Organizations in the web app or open desktop windows with separate Organizations and Projects.
• Updates: control when the desktop app downloads and installs a new release.

Studio has its own sign-in, separate from the CLI. To give an AI assistant access to your Projects instead, see the MCP server.