Build your first workspace

By the end of this tutorial you will have inspected the workspace your instance ships with, written your own core.workspace.v1 document, installed it, updated it, and archived it. A workspace is a single JSON file and installing one is a single command — there is no build step.

Allow ~10 minutes.

Prerequisites

• spl serve running locally — see the Quickstart if not yet.
• Identity initialized via spl init — see First run.
• spl version reports 0.47 or newer.

1. Look at the workspace you already have

Every instance boots with a Tasks workspace installed. List what yours serves:

spl workspace list

SLUG    TITLE   LIFECYCLE   HASH
tasks   Tasks   published   3f9a1c…

Print its full body:

spl workspace show tasks

You will see a core.workspace.v1 record: a meta block, a capabilities block, a regions map, and a lifecycle field. This is the entire workspace — there is nothing else to it. Read the Workspaces concept for what each part does.

2. Write your own

Create my-workspace.json:

{
  "kind": "core.workspace.v1",
  "schema_version": "2.0.0",
  "meta": {
    "slug": "my-workspace",
    "title": "My Workspace",
    "icon": "layout-dashboard",
    "rail": true,
    "shell": "workspace",
    "capabilities": {
      "emit": [],
      "navigate": "none"
    }
  },
  "regions": {
    "header": { "srp": "0.7", "root": {} },
    "body":   { "srp": "0.7", "root": {} }
  },
  "lifecycle": "draft"
}

This is a complete, valid workspace. The regions are empty for now — each region's root is where the actual UI goes. Filling a region with tables, forms, and text is the job of a projection document, covered in Projections and Authoring a workspace. For this tutorial we are walking the workspace envelope itself.

Note capabilities: an empty emit and navigate: "none" make this a read-only surface. A workspace can only do what its capabilities block declares — and that block is part of the hashed record, so it cannot change without changing the workspace's identity.

3. Install it

spl workspace install ./my-workspace.json

✓ Installed workspace "my-workspace" (draft)
  record: 8c2d4e…

install checked the document shape, then emitted it as a record onto your instance's workspace catalog. If the file were malformed — a missing meta.slug, a region that is not a { srp, root } pair — the install would be refused and nothing would be emitted.

Confirm it landed:

spl workspace list

Your workspace does not show up. It is a draft, and list shows only published workspaces. Drafts are installed but not advertised — the right state while you iterate.

4. Publish it

Edit my-workspace.json and change lifecycle to "published", then re-emit it under the same slug:

spl workspace update my-workspace ./my-workspace.json

Now spl workspace list shows it. update appended a new record — records are immutable, so the draft version is still addressable; the catalog simply resolves the latest record per slug.

5. Archive it

When a workspace has served its purpose:

spl workspace archive my-workspace

This re-emits the workspace with lifecycle: "archived". It drops out of spl workspace list, but every version remains addressable forever — archive is a soft delete, not an erase. To bring it back, update it with lifecycle set to published again.

What you did

You inspected the starter workspace, wrote a core.workspace.v1 document, and moved it through its whole lifecycle — draft, published, archived — entirely with records and entirely at runtime. No rebuild, no plugin, no restart.

Next steps

• Authoring a workspace — fill the regions with real UI.
• Projections — the document format the regions are written in.
• Installing & managing workspaces — the full command surface.
• Workspaces — the concept in depth.