Project lifecycle

The five steps below are the whole path: create, add resources, configure environments and secrets, deploy, then retire.

1. Create a project

The response is 201 with the project record. workspace_slug or external_workspace_id also resolve the workspace; slug is derived from name when you omit it.

Sandboxes, computers, deployments, databases, storage, functions, jobs, and domains all accept project_id. When you only have your own identifier, pass external_project_id and MIOSA resolves or creates the project for you. Machine commands in the CLI take --workspace, not a project, so the project resolves from the workspace default; use the API or an SDK when a resource must land in a named project.

3. Environments and secrets

Runtime environment variables resolve narrowest-wins:

tenant defaults < workspace defaults < project defaults < resource env < request env

A project-scoped variable reaches every resource in the project without copying values into each one.

Values are encrypted at rest and never returned in plaintext. Production configuration for a single deployment is separate: a Deployment owns its own environments (production, staging, preview, development) with their own config.

4. Deploy

Publishing creates an immutable version under the Deployment and prints the URL. Display the URL the API returns; never rebuild it from a slug.

5. Archive or delete

A project row has no state, so there is no project archive. Archive is a resource concept: a Product is active or archived, and a deployment environment is active, inactive, or archived. To retire a project, move or delete its resources first, then delete the project.

Delete returns 204. It returns 409 PROJECT_HAS_RESOURCES with a details.impact document listing what still blocks the delete, and 409 DEFAULT_PROJECT_PROTECTED for a workspace’s Default project. Move is refused for the Default project and for a caller who is not a workspace admin.