Granspace

Projects

granspace.json

granspace.json is a small file a project carries to describe itself to Granspace. When you add (or clone) a project that has one, Granspace reads it and applies it automatically — so a shared repo configures itself the same way for everyone, with no manual setup. It’s plain JSON, safe to commit, and never contains secret values.

Full example

Every field is optional — include only what your project needs.

{
  "version": 1,
  "stage": "in_development",
  "purpose": "wants_to_publish",
  "tags": ["web", "api"],
  "webUrl": "http://localhost:5173",
  "startCommand": "npm run dev",
  "install": ["npm install", "npm run build"],
  "autoStart": false,
  "env": {
    "DATABASE_URL": "postgres://localhost:5432/app",
    "API_KEY": null
  }
}

Fields

Field Type What it does
version number Config format version. Currently 1. Written by Granspace on export; you can omit it.
stage string The project’s lifecycle stage. One of planning, in_development, launched, paused, archived.
purpose string What the project is for. One of personal_use, local_only, wants_to_publish, public.
tags string[] Free-form tags, shown as chips on the card and usable as a dashboard filter.
webUrl string | null A URL to open for the project (e.g. its local dev server or live site). null clears it.
startCommand string | null The command Granspace runs when you press Start. null clears it.
install string[] Setup commands, run in order, non-interactively. See Installing dependencies.
autoStart boolean Start the project automatically after a successful install.
env object Environment variables to seed (see below).

The file is strict: only the fields above are accepted. An unknown field makes the file invalid, and Granspace reports which key was rejected rather than applying a partial config.

stage values

planning · in_development · launched · paused · archived

purpose values

personal_use · local_only · wants_to_publish · public

env

A map of variable name → value. A value of null declares the key without a value — use it for a variable the project needs but whose value each person must fill in (typically a secret):

"env": {
  "DATABASE_URL": "postgres://localhost:5432/app",
  "API_KEY": null
}

When Granspace writes a granspace.json for you, it lists every env key the project uses, but only writes a value when the variable is not secret and you chose to publish it — otherwise the key maps to null. That way the file documents what the project needs without ever leaking a confidential value. See Environment & secrets.

Secrets are never written to granspace.json, so the file is always safe to commit.

How Granspace uses it

Saving, applying, testing

From Details → granspace.json in the app: