DocsBuildDeploying

Deploying

Deploy with a single command. The Core handles manifest sync, dependency install, backend startup, and frontend publishing.

Deploy from the CLI

rootcx deploy

That is the entire workflow. The CLI deploys to the Core instance you are signed in to. Your internal tool is immediately live at https://<your-ref>.rootcx.com/apps/<appId>/.

What happens on deploy

The CLI runs a pipeline:

  1. Install manifest: sends manifest.json to the Core via POST /api/v1/apps. The Core creates or updates database tables, columns, permission keys, webhook tokens, and cron schedules.
  2. Build frontend: runs bun run build locally if a src/ directory exists.
  3. Deploy backend: packs backend/ as a tar.gz, uploads via POST /api/v1/apps/{appId}/deploy. The Core extracts it, runs bun install if package.json is present, registers the agent (if agent.json exists), stops the old worker, and starts the new one.
  4. Publish frontend: packs dist/ as a tar.gz, uploads via POST /api/v1/apps/{appId}/frontend. The Core extracts it and serves the static assets.

This pipeline is idempotent. Change anything, deploy again, and the Core applies only what changed.

How apps are served

The Core serves your frontend at /apps/{appId}/. It operates as an SPA: any path that does not match an existing file returns index.html.

Caching:

  • Hashed asset filenames (JS, CSS, images): Cache-Control: public, max-age=31536000, immutable
  • HTML files: Cache-Control: public, max-age=60, must-revalidate

Share URLs: Apps can generate share links at /share/{token}. These serve the same frontend but with X-Robots-Tag: noindex, nofollow.

Deploy via the API

You can deploy without the CLI using the REST API directly:

Backend

cd backend && tar -czf ../backend.tar.gz . && cd ..
curl -X POST https://<your-ref>.rootcx.com/api/v1/apps/{appId}/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -F "archive=@backend.tar.gz"

Frontend

cd dist && tar -czf ../frontend.tar.gz . && cd ..
curl -X POST https://<your-ref>.rootcx.com/api/v1/apps/{appId}/frontend \
  -H "Authorization: Bearer $TOKEN" \
  -F "archive=@frontend.tar.gz"

Max upload size: 50 MB per archive.

Worker lifecycle after deploy

After a backend deploy, the Core:

  1. Stops the existing worker (if running).
  2. Starts the new worker from the extracted archive.
  3. Sends a discover message with appId, runtimeUrl, databaseUrl, and all secrets.
  4. Supervises the process with automatic crash recovery (exponential backoff: 0s, 2s, 4s, 8s).
  5. Detects crash loops: after 5 crashes within 60 seconds, the worker is marked crashed and stops restarting.

Check worker status: GET /api/v1/apps/{appId}/worker/status. Possible values: starting, running, stopping, stopped, crashed.

Self-hosting

When self-hosting, the deploy workflow is identical. The CLI targets your self-hosted Core URL:

rootcx auth login http://localhost:9100
rootcx deploy

Same binary, same API, same behavior. See the self-hosting guide for setup.

Further reading

PreviousIntegrationNextOverview