Runbook: Restart & Rebuild

Rebuild packages and restart services so the platform picks up your latest changes. Component nodes are definition-backed: they re-synthesize from rx/ at boot; there is no generation step, ever.

When To Use

Marketplace installs and Studio publishes: live immediately, no restart (database-driven)
Platform image updates: unoverse deploy (server) / unoverse update or unoverse start --pull (local)

Quick Commands

Local Development

# Full rebuild: builds all node packages, restarts services
unoverse build

# Build one package only
unoverse build @unoverse-platform/my-package

# Restart only: component nodes re-synthesize from rx/ definitions at boot
unoverse build

Production Server

Content does not ride deploys. Nodes, design, and prompts reach a server through Studio publish (over the API, live immediately) and the Marketplace (installed per item, database-driven). unoverse deploy moves platform images only:

unoverse deploy    # pull latest images + restart

What Each Step Does

Step	Command	What happens
1. Install deps	`npm install`	Installs workspace dependencies
2. Build packages	`npm run build`	Compiles node packages (TypeScript → `dist/`)
3. Restart unoverse	`unoverse build`	Reloads built packages, and re-synthesizes component nodes from `rx/` definitions: the node catalog is loaded at boot, so a rebuild without a restart appears to do nothing

Which change needs which step?

You changed	Do
A newly published node (from Studio)	nothing: live on the next workflow run
An existing component/template’s look (`rx/`)	nothing: definitions are read live; hard-refresh the client
A new component, or props/structure changes (`rx/`)	`unoverse build`
A skill or prompt block (`prompts/`)	`unoverse build`

Manual Step-by-Step (when CLI commands aren’t enough)

# 1. Install dependencies
npm install

# 2. Build all node packages
npm run build

# 3. Restart the service that loads packages (the workflow engine runs
#    in-process in unoverse, so one restart covers everything: component
#    nodes re-synthesize from rx/ at this boot)
unoverse build

# 4. Verify
unoverse check

Nuclear Restart (full teardown + rebuild)

When things are truly stuck:

unoverse stop
npm install
npm run build
unoverse start

unoverse start also rebuilds the universal component-node package in-container, so a cold start always runs fresh executor code.

Verify

# Check all services are running
unoverse check

# Full health check
unoverse check

# Check nodes loaded in unoverse (:4106 is Docker-internal and :4105 /plugins
# is JWT-gated, so count from inside the container)
docker compose exec -T unoverse node -e \
  "fetch('http://127.0.0.1:4106/nodes').then(r=>r.json()).then(d=>console.log((d.nodes||[]).length)).catch(()=>console.log(0))"

Troubleshooting

Issue	Cause	Fix
New component not in Canvas	unoverse not restarted since the definition was added	`unoverse build`
Node shows in Canvas but errors	Package not built	`unoverse build`
Component renders old version	Client caching	hard-refresh the browser
`nodes: 0` in status	unoverse didn’t load packages	Check `docker compose logs unoverse`
Build fails	Dependencies missing	`npm install`, then `unoverse build`

core.md: Initial deployment
test.md: Full health check

Deploy

Operate

Runbook: Restart & Rebuild

When To Use

Quick Commands

Local Development

Production Server

What Each Step Does

Which change needs which step?

Manual Step-by-Step (when CLI commands aren’t enough)

Nuclear Restart (full teardown + rebuild)

Verify

Troubleshooting

​When To Use

​Quick Commands

​Local Development

​Production Server

​What Each Step Does

​Which change needs which step?

​Manual Step-by-Step (when CLI commands aren’t enough)

​Nuclear Restart (full teardown + rebuild)

​Verify

​Troubleshooting

​Related

When To Use

Quick Commands

Local Development

Production Server

What Each Step Does

Which change needs which step?

Manual Step-by-Step (when CLI commands aren’t enough)

Nuclear Restart (full teardown + rebuild)

Verify

Troubleshooting

Related