Installation

Prerequisites

• PHP 8.4+
• Composer 2
• Node.js 18+
• PostgreSQL or MySQL

Create a New Project

laravel new my-app --using=nubos-ai/starter-kit --pest

This installs all dependencies, generates an application key, and launches the interactive nubos:init command. The Nubos Starter Kit uses Pest for its own tests, so it makes sense to install Pest as well

The nubos:init Command

nubos:init is an interactive setup wizard that scaffolds your project's organization structure. It generates models, migrations, actions, routes, seeders, and tests based on your choices.

The command runs once. After initialization, a config/nubos.php file is created. To re-initialize, delete that file and run the command again:

php artisan nubos:init

Step 1: Organization Type

The first prompt asks for your organization type:

Type	Use Case
Team	Simple multi-team apps. Users belong to one or more teams. Each user gets a personal team on registration.
Workspace	Apps where users manage multiple workspaces. Optionally with teams inside each workspace.
Tenant	Full multi-tenancy with domain-based identification, isolated data, and optional sub-structures.

Step 2: Additional Prompts

Depending on the organization type, additional prompts appear:

Workspace asks whether to enable teams within workspaces. If enabled, the command scaffolds both workspace and team models with a hasMany relationship between them.

Tenant asks two follow-up questions:

1. Database strategy -- Single-Database or Multi-Database. Single-database uses a tenant_id foreign key for scoping. Multi-database creates separate database credentials per tenant, stored encrypted on the tenant model.

2. Sub-structure within tenant -- None, Teams, Workspaces, or Workspaces + Teams. This determines what organizational layers exist inside each tenant.

What Gets Generated

The command scaffolds files into standard Laravel directories:

• app/Models/ -- Organization models (Team, Workspace, Tenant)
• app/Actions/ -- Create, AddMember, RemoveMember actions
• app/Events/ -- Domain events for creation, member changes
• app/Traits/ -- HasTeams, HasWorkspaces, BelongsToTenant, TenantScope
• app/Http/Middleware/ -- Organization switching, tenant identification
• app/Providers/ -- NubosOrganizationServiceProvider for route and middleware registration
• database/migrations/ -- Tables for organizations and pivot tables
• database/factories/ -- Factories for all generated models
• database/seeders/NubosSeeder.php -- Demo data seeder
• routes/ -- Organization-specific route files
• tests/Feature/ -- Tests for actions, middleware, and models
• config/nubos.php -- Your chosen settings

The command also adds the required traits to app/Models/User.php automatically (e.g., HasTeams, HasWorkspaces, BelongsToTenant) and their import statements.

Post-Install Steps

After nubos:init completes, run migrations:

php artisan migrate

Install frontend dependencies and start development:

npm install
npm run dev

Or use the built-in dev script that starts the Laravel server, queue worker, log viewer (Pail), and Vite dev server simultaneously:

composer dev

Seed Demo Data

The generated NubosSeeder creates two users (demo@nubos.dev and second@nubos.dev, both with password password) and sample organizations depending on your chosen structure:

php artisan db:seed --class=NubosSeeder

Paid Modules

Paid modules are distributed via Packeton, a private Composer repository. Configure authentication first:

composer config http-basic.packages.nubos.dev your-username your-token

Then install the module:

composer require nubos/identity-pro

Modules register themselves through Laravel's package auto-discovery. No additional commands required.

Re-Initialization

The nubos:init command refuses to run if config/nubos.php already exists and contains an organization_type key. To start over:

1. Delete config/nubos.php
2. Revert generated files (migrations, models, etc.) or start from a fresh project
3. Run php artisan nubos:init

The command does not provide automatic rollback. A fresh project is the cleanest path if the organization type needs to change significantly.