Provisioning

Provisioning is step 2 of delivery — the point where an approved blueprint becomes real infrastructure: a repository, six databases, a deploy pipeline, and a registered app the builder agent can start working against.

This page is the reference for what provisioning creates, what you have to supply, and how an agent or integrator drives it over the API. It is written to be read by people and by AI agents; see also /llms.txt and /agent.json.

Where your app lives

Every app is served from public_html/<slug>/ — never from the domain root. This stays true even when the app owns the primary domain on the hosting account.

The layout on the hosting account is always the same:

public_html/
├── admin/          → wave-networks-core   (auth, sessions, sharding, email)
├── <your-slug>/    → your application
└── index.php ...   → your marketing website (the domain root)

URL	What it serves
`https://yourdomain.com/`	Marketing website
`https://yourdomain.com/<slug>/app/`	The application
`https://yourdomain.com/admin/`	Shared core — login, account, admin

A 404 at https://yourdomain.com/auth/login.php is the expected result, not a broken deploy. Auth lives under /admin/. Pointing a deploy at public_html/ instead of public_html/<slug>/ overwrites the domain root and collides with the core deploy.

What you provide

Nokemo does not create hosting accounts or databases on your behalf — those stay in your name, on your account. Provisioning collects:

Input	Detail
App identity	Slug (lowercase `[a-z0-9-]`, unique — becomes the repo name, the webroot directory, and the database prefix), display name, description, primary domain.
Specification	The approved blueprint document. It becomes the repo's `docs/spec.md`, seeds the agent instructions, and generates the builder's first tasks.
Six databases	Pre-created by you in the hosting control panel: `<slug>_admin_main`, `<slug>_admin_shard_1`, `<slug>_admin_shard_2`, `<slug>_main`, `<slug>_shard_1`, `<slug>_shard_2`. Host, port, name, user and password for each — with a "same credentials for all" shortcut. Every connection is tested before the step is accepted.
SFTP credential	Host, port, user, password — issued by your hosting provider.
SSH access	Nokemo generates an ed25519 keypair and shows you the public half plus control-panel instructions. You add it and enable SSH on the package; Nokemo then verifies the connection before continuing. The private key is never displayed — it is installed as the repository's deploy secret and then purged.

Two databases per tier are shards. Core distributes users across them automatically; you do not manage the routing.

What provisioning creates

A private repository in your name containing the scaffolded application — cloned from the reference child app, not generated from scratch.
Core installed alongside it as admin/, sharing auth, sessions, sharding, the email queue, notifications, and GDPR tooling.
Configuration written out-of-band — config/config.php holds the database credentials and is deliberately excluded from the deploy pipeline, so credentials never enter git history.
A CI/CD pipeline — GitHub Actions deploys over SSH on push, with the deploy key and cross-repo checkout token installed as repository secrets.
Database migrations run, then an installer pass that creates the first administrator account.
The app registered for monitoring and tied to your user, so the five-minute error/feedback/change-request poll begins.
Handoff to the builder, which clones the new repository and starts working the spec-derived task queue. From here the maintenance loop takes over.

Credential handling

Database, SFTP, and SSH credentials are stored AES-256 encrypted for the duration of the job and destroyed once setup completes. The provisioning record keeps only non-sensitive fields — slug, domain, repository URL, status, timestamps.

Job lifecycle

A provisioning job moves through a fixed set of states. Both the dashboard and the API report the same values.

Status	Meaning
`collecting`	Wizard in progress — inputs still being gathered.
`pending`	Reviewed and enqueued; waiting for a runner to claim it.
`running`	Claimed. Repository creation and scaffolding under way.
`awaiting_ssh`	Parked until the generated public key is installed and the connection verifies.
`verifying`	Connections and deploy pipeline being checked.
`installing`	Migrations and the installer pass are running.
`completed`	App is live, registered for monitoring, and handed to the builder.
`failed`	Halted with a recorded reason. Resumable — a job is re-claimed from where it stopped rather than restarted.
`cancelled`	Withdrawn by the owner. Stored credentials are purged.

API surface

Provisioning is fully driveable over the API. All actions are POSTed to the app API endpoint as application/x-www-form-urlencoded with an action parameter, authenticated with a scoped service API key as Authorization: Bearer <key>. These endpoints are not public — a key is issued per integration.

Owner actions

Used by the dashboard wizard; available to the account that owns the job.

Action	Purpose
`provisioningCheckSlug`	Validate slug availability against existing apps and the repository host.
`provisioningLaunch`	Enqueue a reviewed job — `collecting` → `pending`.
`provisioningJobStatus`	Current status, step, and progress detail for one job.
`provisioningCancelJob`	Withdraw a job and purge its stored credentials.
`provisioningReprovision`	Re-run provisioning for an existing app.

Runner actions

Used by the execution agent that performs the build.

Action	Purpose
`provisioningListJobs`	List jobs, filterable by status.
`provisioningClaimNextJob`	Atomically claim the next `pending` job.
`provisioningClaimResumable`	Reclaim a job that stopped mid-flight and continue from its last completed step.
`provisioningGetJobSpec`	Fetch the uploaded specification document.
`provisioningGetJobBranding`	Fetch brand assets and tokens produced by the brand compiler.
`provisioningGetJobSecrets`	Fetch decrypted credentials for the claimed job. Scope-gated; single purpose.
`provisioningStoreDeployKey`	Record the generated deploy keypair against the job.
`provisioningUpdateJobStatus`	Advance the job through the lifecycle and record progress detail.
`provisioningRegisterApp`	Register the finished app for monitoring and tie it to the owner.
`provisioningGetAppDeployCredentials`	Retrieve deploy credentials for a registered app on later runs.
`provisioningNotifyUser`	Send the owner a progress or completion notification.
`provisioningPurgeJob`	Destroy all stored credentials for a job.

Specification coverage

Provisioning binds the delivered app back to the approved specification, so "built" can be checked against "specified" rather than asserted.

Action	Purpose
`provisioningClaimAnalysisJob`	Claim a specification for analysis.
`provisioningStoreSpecAnalysis`	Store the parsed specification broken into discrete units.
`provisioningGetSpecUnits`	Retrieve those units for verification.
`provisioningBindCoverage`	Bind each unit to the code and tests that satisfy it.
`mcpOwnerExcludeCoverageUnit`	Owner only (`coverage:owner` scope). Take one unit out of scope with a reason and the owner’s verbatim authorisation, from an agent session the owner is directing. Recorded exactly like an exclusion made on the coverage page, and undone there.

Marking a unit out of scope is an owner decision, never the build’s: a build that marks its own units n/a is reverted and disputed. The owner excludes a unit on the app’s coverage page, or asks their own agent session to do it — that path uses a separate owner key the build does not hold, and stores the owner’s words alongside the reason.

Coverage proves code exists, not that the app works. A manifest can read near-complete against a placeholder screen. Coverage sign-off is therefore paired with an install check and an acceptance run against the live deployment before an app is called delivered.

After provisioning

A provisioned app is a monitored app. Its errors, user feedback, and change requests are polled every five minutes, triaged, and turned into builder tasks — described in full on How it works. You own the repository, the databases, the hosting account, and the developer accounts throughout; provisioning never places infrastructure in Wave Networks' name.

To start: request a blueprint — the specification and brand pass that provisioning consumes. It is free, and nothing is built until you approve it.