Before you begin
You will need PHP 8.5, Composer, PostgreSQL, and Node.js compatible with the installed Vite version. PHP must have the pdo_pgsql extension. Use a private development database and a separate orbit_testing database for tests.
Check your PHP version Run
php -vfirst. If Herd’s default is still PHP 8.4, use its installed PHP 8.5 binary or select PHP 8.5 for this project before running Artisan or Composer.
On macOS with Herd, you can invoke PHP 8.5 explicitly:
"$HOME/Library/Application Support/Herd/bin/php85" artisan test --compact
Install the application
From a fresh checkout:
composer install
cp .env.example .env
php artisan key:generate --no-interaction
npm ci
npm run build
Copy .env.example only on a fresh installation. Keep an existing application key and environment configuration intact.
Configure PostgreSQL
Create the development database and set its credentials in .env:
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=orbit
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password
For a private local HTTP endpoint, set ORBIT_REQUIRE_HTTPS=false. Keep HTTPS required on a remote deployment.
Apply the migrations and create your workspace:
php artisan migrate --no-interaction
php artisan orbit:workspace "My workspace" --no-interaction
The workspace defaults to Europe/London. Use --timezone=America/New_York, for example, to choose a different IANA timezone when first provisioning it. Running setup again returns the existing workspace; it does not rename it or create another.
Issue an agent credential
Give each agent its own credential. A contributor can read and manage contacts:
php artisan orbit:agent-issue Hermes --role=contributor --no-interaction
Save the returned agent ID and bearer token securely. The token is displayed once. The database stores only its hash. Omitting the role option creates a read-only agent.
Start Orbit
php artisan serve --host=127.0.0.1
Open /docs on your local application to read these pages. Run npm run dev in a separate terminal when working on the documentation’s styles or JavaScript.
You are ready to connect Hermes.
Prefer a browser for agent setup?
Run php artisan orbit:install in an interactive server terminal. It guides you through workspace and owner details, then gives you the sign-in URL. It reuses a workspace already created above and preserves existing agents. No email service or setup code is required. After signing in, the getting-started checklist leads to Connect an agent, where you create tokens and copy configuration for your own endpoint. See Your account & agents.