Setup

Elastic Projects is an alpha web app plus a local SQLite replica. You can run it on a laptop today. A public elasticprojects host and durable cloud replica are not wired yet.

Requirements

Node.js 22 or newer
npm
About 200 MB for dependencies and a local elasticprojects.db

Optional for live Spaces:

An account on a spaces-capable PDS (bsky.network/account invite, or your own pack)
Docker if you run an Organization PDS locally

Local app

git clone <your-origin-url>
cd elasticprojects
npm install
cp .env.example .env   # optional; defaults work for local dev
npm run dev

Open http://127.0.0.1:43147.

The logged-out homepage uses a WebGPU cloud wallpaper when the browser supports it. Otherwise you get a still sky gradient.

Local preview (no PDS)

On the homepage, choose Open local preview. That seeds demo organizations and projects in SQLite:

Handle	Org	Example projects
`labs.elasticprojects.test`	Elastic Labs	`foundations`, `kitchen`, `elastic`
`design.elasticprojects.test`	Elastic Design (division)	`brand`
`loaf.elasticprojects.test`	Loaf Media (acquired)	`studio`

Demo people: you.elasticprojects.test, maya.elasticprojects.test, daniel.elasticprojects.test.

Pull and push in the UI work entirely against elasticprojects.db. No network calls.

Environment variables

Variable	Default	Purpose
`UI_PUBLIC_URL`	`http://127.0.0.1:43147`	Public origin for OAuth client metadata
`PLC_URL`	`https://plc.directory`	DID directory
`BSKY_URL`	`https://public.api.bsky.app`	Handle search and profiles
`DATABASE_PATH`	`elasticprojects.db`	SQLite replica, blob store, OAuth sessions
`ELASTICPROJECTS_PORT`	`43147`	Dev server port (see `package.json` scripts)
`VERCEL_PROJECT_PRODUCTION_URL`	unset	Used for `UI_PUBLIC_URL` on Vercel when that var is empty
`DATABASE_URL`	unset	Reserved for Neon Postgres. Not wired yet.

Copy .env.example to .env only when you need to override defaults.

`ep` CLI (local replica)

The CLI reads and writes the same SQLite file as the web UI.

npm run ep demo seed
npm run ep -- pull labs/elastic --dir ./product-tree
npm run ep -- push labs/elastic --dir ./product-tree -m "Update notes"
npm run ep -- status labs/elastic

Variable	Default	Purpose
`DATABASE_PATH`	`elasticprojects.db`	Same replica as the app
`EP_VIEWER_DID`	demo user `you.elasticprojects.test`	Checkout writer for pull/push

Project refs: elastic, labs/foundations, did:plc:…/elastic, or a full at://… project URI.

Do not ep pull into the repository root. The product workspace includes a README.md that would overwrite this repo’s README. Always use a subdirectory such as ./product-tree.

Live Spaces pull/push from the CLI is not implemented yet. Use the web UI after OAuth sign-in.

Organization PDS (self-host)

A personal PDS assumes you own what you write. An ODS is the institutional identity that owns project files.

In the app, open Organizations (/orgs):

Mint an organizational DID (preview mode uses local fake DIDs)
Choose hosting:
- Host here — provisions through HOSTED_ODS_PROVIDER (preview marks the index; fly creates a Fly Machine). See hosted-ods.md
- Local pack — download Docker Compose for ghcr.io/bluesky-social/atproto:pds-spaces-alpha
- External PDS — point at a PDS URL you already run
Complete the readiness checklist (first project, steward, org/CHARTER.md, structure)

Local pack requirements: about 2 vCPU, 4 GiB RAM, 20 GiB disk.

Live Spaces

Sign in with a handle on a spaces-capable PDS (Sign in with Spaces on the homepage)
Create or open a project under Projects
Use Pull and Push in the project workspace

Live mode calls Space XRPC (listRepos, listRecords, putRecord) through a space credential. The local SQLite replica still holds your checkout.

Live project create currently uses the signed-in person’s DID as space authority, not the organization ODS. Org-owned live spaces need a real ODS that can mint spaces.

Deploy to Vercel

Not deployed from this repo by default. You link your own Vercel project.

npx vercel link
npx vercel integration add neon    # when Postgres wiring lands
npx vercel env add UI_PUBLIC_URL production
npx vercel --prod

Set UI_PUBLIC_URL to the production URL after the first deploy. OAuth metadata is served from that origin.

Important:

Git ships the Next.js host. Vercel builds from git, not from an Elastic Projects pull.
SQLite does not persist on serverless. Until DATABASE_URL (Neon) is wired, a Vercel deploy is a UI preview that forgets sessions and checkouts on cold starts.
ep pull in a build step needs a durable remote replica or API tokens. Neither exists yet.

This repository is on Cursor Origin today, not GitHub. Link Vercel with the CLI or mirror to GitHub first.

Product workspace vs git

Elastic Labs has a project labs/elastic (product workspace) with charter, notes, and design files. It is not the git remote for this repository.

Dogfood loop today:

npm run ep demo seed
npm run ep -- pull labs/elastic --dir ./product-tree
Edit files under ./product-tree
npm run ep -- push labs/elastic --dir ./product-tree -m "…"
Open /projects in the browser and pull the same project to verify

Git continues to ship the application source.

Checks before you rely on it

npm run check    # lint, typecheck, unit tests

See limits.md for alpha boundaries and known gaps.