# Quickstart

> From a fresh installation to your first contact.

## 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 -v` first. 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:

```sh
"$HOME/Library/Application Support/Herd/bin/php85" artisan test --compact
```

## Install the application

From a fresh checkout:

```sh
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`:

```dotenv
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:

```sh
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:

```sh
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

```sh
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](/docs/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](/docs/account).