Skip to content
Cowork Studio Docs

workspace.json reference

What a workspace remembers: how the window starts, what is switched off, where pushes go, how routines are deployed. It never says what the workspace has (apps, routines and file routes come from each app's cowork.json), and it never travels with a pushed or exported app. Every key is optional and a missing file is normal; a value of the wrong type is ignored, never an error.

$schema

Section titled “$schema”

string

name

Section titled “name”

string

The workspace's display name in the projects list. Defaults to the folder's name.

startup

Section titled “startup”

object

How the window looks when this workspace opens.

  • startup.home · string (pattern ^[a-z0-9][a-z0-9-]{0,62}$) — The app the window opens on, by app name. Defaults to the app named "home", if the workspace has one.
  • startup.left · boolean — false starts with the side bar closed, true with it open. Absent keeps whatever the window last had.
  • startup.right · boolean — false starts with the secondary side bar closed, true with it open. Absent keeps whatever the window last had.

disabled

Section titled “disabled”

object

Things switched off without deleting them. A checked-in list can only ever turn things off.

  • disabled.routines · string[] — Routine ids that refuse to run and are skipped by schedules. They still show in lists.
  • disabled.apps · string[] — App folders (e.g. ".cowork/apps/gmail") or single app files, relative to the workspace. A switched-off app stays on disk but has no activity-bar icon, is never the home app, and its file routes fall through to the default editor.

rail

Section titled “rail”

object

The activity bar's layout: folders that group app icons. Cowork writes it when the user drags icons into a folder; an agent may write it to group apps (a member is an app's view id, workbench.view.cowork.app.<name>).

  • rail.folders · object[] — Folders that group activity-bar icons (at most 12), made by dragging one icon onto another.
    • rail.folders[].id · string required (pattern ^[a-z0-9][a-z0-9-]{0,31}$) — The folder's id.
    • rail.folders[].title · string required (maxLength 40) — The folder's name.
    • rail.folders[].color · string (pattern ^#[0-9a-fA-F]{6}$) — Tile color, e.g. "#F0386B".
    • rail.folders[].members · string[] required (minItems 1, maxItems 24) — The activity-bar ids of the icons inside (at most 24).

wallpaper

Section titled “wallpaper”

string

An image shown behind the workspace, as a path relative to the workspace root (png, jpg, webp, gif, avif or svg, up to 20 MB). The Manage Workspace picker copies the image to .cowork/data/wallpaper.<ext>, which travels with a published workspace.

publishTo

Section titled “publishTo”

string (pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$)

The team server slug that cowork push publishes to when the app has no home store and no --to is given. cowork push --to <slug> --remember sets it.

openWith

Section titled “openWith”

{ [key: string]: string }

Which app opens a file type when two apps claim the same glob: glob -> app name. Without an entry the first switched-on app (in folder order) wins.

notifications

Section titled “notifications”

object

Notification preferences for this workspace.

  • notifications.muted · string[] — App folders (e.g. ".cowork/apps/gmail") whose desktop notifications are dropped and whose badge leaves the activity-bar count.

deployments

Section titled “deployments”

{ [key: string]: object }

Where each routine runs outside the IDE: routine id -> deployment. It records intent only (target, schedule, secret names), never secret values; cowork deploy add writes it. A webhook, schedule or notifications trigger never starts by itself from a checked-in or imported file: arming it needs the owner's consent on their machine.

  • deployments.target · "cloudflare-worker" | "aws-lambda" | "gcloud-function" | "container" required — Where the routine is built to run.
  • deployments.mode · "local" | "deployed" — "local" runs invocations on this machine, "deployed" on the target. Default "local".
  • deployments.name · string (pattern ^[a-z][a-z0-9-]{0,53}$) — The cloud resource's name. Default "cowork-<routine id>".
  • deployments.webhook · boolean — Expose an HTTP webhook that runs the routine.
  • deployments.schedule · string — A 5-field cron expression (minute granularity) that runs the routine.
  • deployments.notifications · string[] — Run the routine on this machine with each notification these apps raise, by app name (as in its cowork.json), or "*" for every app's. Its args are the notification ({app, appTitle, title, body, tag, urgent, at}). A notification raised by a run that one started starts nothing.
  • deployments.secrets · string[] — Names of the secrets pushed to the target's secret store at deploy time. Names only; values stay in the secrets store.
  • deployments.vars · { [key: string]: string } — Plain (non-secret) environment variables baked into the deployed routine: name -> value.
  • deployments.hookToken · boolean — Require a token header on webhook calls. The token is generated and kept as a secret.
  • deployments.corsOrigin · string — The CORS origin webhook responses allow: "" or an origin like "https://example.com". Default "".
  • deployments.region · string — Cloud region (aws-lambda and gcloud-function).
  • deployments.roleArn · string — An existing execution role (aws-lambda). Cowork never creates IAM roles.
  • deployments.port · integer — The port the container listens on (container).
  • deployments.registry · string — The image registry to push to (container).
  • deployments.db · string (pattern ^[a-z][a-z0-9-]{0,53}$) — The D1 database name the routine's ctx.db uses (cloudflare-worker). Created at deploy time when missing; several routines may share one.

agents

Section titled “agents”

object

How the workspace's agent map finds instruction files, skills, subagents and commands. Each key replaces the built-in list; a key that is not well-formed is ignored.

  • agents.instructions · string[] — Instruction file names, e.g. ["CLAUDE.md", "AGENTS.md"].
  • agents.skill · string — The file name that makes a folder a skill, e.g. "SKILL.md".
  • agents.homes · string[] — Agent home folders, e.g. [".claude"].
  • agents.agents · string[] — Folders holding subagent docs.
  • agents.commands · string[] — Folders holding slash-command docs.
  • agents.skip · string[] — Folder names never read.
  • agents.stepWords · string[] — Words that make a heading a step ("step 3") or a process.
  • agents.notStepWords · string[] — Words that make a heading never hold steps.
  • agents.columns · object — Header names recognized in stage tables.
    • agents.columns.label · string[] — Header names of the column holding a stage's label.
    • agents.columns.id · string[] — Header names of the column holding a stage's id.
    • agents.columns.skills · string[] — Header names of the column listing a stage's skills.
    • agents.columns.detail · string[] — Header names of the column holding a stage's description.
  • agents.groupBy · string[] — Skill metadata keys, in order, whose value says who a skill is for; the map groups skills by it.
  • agents.routines · string[] — Commands that run a routine followed by its id, e.g. ["cowork routine run"]; each one found in a doc adds a routine node.

projects

Section titled “projects”

object[]

Folders of this workspace listed as projects, pinned by hand or from "Add to Projects".

  • projects[].name · string — The project's display name.
  • projects[].path · string — Folder relative to this workspace's root. Defaults to the name. A path outside the workspace is dropped.

scan

Section titled “scan”

object

How the projects list discovers sub-folders that are Cowork workspaces themselves.

  • scan.enabled · boolean — false turns discovery off. Default true.
  • scan.depth · integer (minimum 1, maximum 2) — How many folder levels to look into. Default 2, at most 2.
  • scan.include · string[] — Globs; when set, only matching folders are kept.
  • scan.exclude · string[] — Globs of folders to drop. Wins over include.

notebook

Section titled “notebook”

object

Settings for the Notebook editor.

  • notebook.trackChanges · object — Marks what changed in a document since a git revision.
    • notebook.trackChanges.enabled · boolean — Turn change tracking on. Default false.
    • notebook.trackChanges.defaultDisplay · "off" | "git" | "ai" | "user" | "all" — Whose changes are marked when a document opens. Default "off".
    • notebook.trackChanges.git · object
      • notebook.trackChanges.git.baseRef · string — The git revision changes are measured against. Default "HEAD".
    • notebook.trackChanges.reviewExternalWrites · "never" | "when-dirty" | "always" — When edits made outside the editor show up as marks. Default "when-dirty".