> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unoverse.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"system"}
# 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:

```bash theme={"system"}
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)

```bash theme={"system"}
# 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:

```bash theme={"system"}
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

```bash theme={"system"}
# 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` |

## Related

* [core.md](/runbooks/core): Initial deployment
* [test.md](/runbooks/test): Full health check