Hosted SaaS Getting Started

    This guide is the shortest path from a fresh ByteOr Cloud workspace to a usable hosted SaaS demo environment.

    What you get

    After following this guide you should have:

    • a local Postgres-backed control plane
    • the API and worker running
    • the UI running separately
    • one organization, project, and environment you can use for agent enrollment and deployments

    Prerequisites

    • Docker and Docker Compose
    • Rust toolchain matching rust-toolchain.toml
    • Node.js for the UI workspace

    Start the backend

    Use the local helper when you want API and worker processes on the host:

    scripts/dev_up.sh

    This starts Postgres in Docker, applies migrations and demo seed data, then runs the API and worker.

    Use Compose when you want the whole control plane containerized:

    docker compose up --build

    Add the UI profile if you also want the frontend container:

    docker compose --profile ui up --build

    Start the UI

    Run the UI separately during normal development:

    cd ui
npm install
npm run dev

    Default local endpoints

    • UI: http://localhost:3000
    • API: http://localhost:8080
    • Worker health surface: http://localhost:9090/healthz
    • Metrics: http://localhost:8080/metrics

    First operator flow

    Use the local environment to validate the core SaaS loop in this order:

    1. Sign in through the browser flow.
    2. Create or select an organization and project.
    3. Create an environment for the project.
    4. Create or open a pipeline draft.
    5. Select an explicit execution target in the editor. Use SingleRing for ordered linear execution and LaneGraph when the draft needs branching, fanout, merge, or richer boundary routing.
    6. Author the draft through the shared planning model. The editor can reproject that plan as a linear SingleRing canvas or a LaneGraph-style topology canvas without changing the underlying draft document shape.
    7. Save the draft and compile it into a canonical version. Preview and version creation both validate and lower the synchronized plan through the compiler-backed WASM path.
    8. Create a config bundle for that version.
    9. Register an agent for the environment.
    10. Create a deployment and verify the agent targets it.
    11. Confirm heartbeats, snapshots, and artifacts appear in the control plane.
    12. Launch a replay from an incident artifact.

    Hosted environment naming

    The intended hosted naming layout is:

    • cloud.byteor.com for production UI
    • api.byteor.com/v1 for production API
    • cloud.staging.byteor.com and api.staging.byteor.com/v1 for staging
    • cloud.dev.byteor.com and api.dev.byteor.com/v1 for development

    OIDC callbacks should stay on the cloud.* origin rather than the API origin.

    What to verify before a demo

    • /readyz returns success on API and worker
    • /metrics exposes auth, request, unauthorized, forbidden, and rate-limited counters
    • the seeded or demo org can reach compile, config, deploy, and replay flows without direct database edits
    • agent enrollment returns a per-agent runtime API key and steady-state heartbeats work with that key
    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index