joy onboard is the one-time setup command. It creates your Joy home directory, writes a starter configuration, provisions the token used to sign in to the web interface, and walks you through choosing an inference provider. Run it once after installing. Running it again is safe — it preserves your existing config.toml and providers.json unless you pass --force.
If you haven’t installed Joy yet, follow the Quickstart first.

​
Running Onboarding

1

Home Directory

Onboarding resolves your Joy home — ~/.joy/reborn by default — and creates it if it doesn’t exist. Override the location with the JOY_REBORN_HOME environment variable.
2

Configuration Files

Two files are written into that directory:
  • config.toml — the selection layer: boot profile, identity, model slots, runner timing
  • providers.json — the catalog of inference providers this install knows about
Both are optional at runtime; if you delete them, Joy falls back to built-in defaults. See Configuration.
3

Master Key

Your master encryption key is provisioned in the OS keychain, where it protects every credential Joy stores. It is never written to config.toml.On a headless host without a keychain, supply the key through the JOY_REBORN_SECRET_MASTER_KEY environment variable instead.
4

Inference Provider

In an interactive terminal, onboarding offers the built-in relay, asks which model tier to use, and stores your API key. Non-interactive sessions skip this step — see below.
5

Web Login Token

A bearer token is written to webui-token and used by joy serve whenever JOY_REBORN_WEBUI_TOKEN is unset. Onboarding prints a ready-to-use login link:
6

System Service

In an interactive session, onboarding offers to install and start Joy as an OS-native service (launchd on macOS, systemd on Linux) so it runs in the background. The installed unit runs joy serve.Skip it with --no-service, or manage it later with joy service install, start, stop, restart, status, and uninstall.

​
Options

--force replaces your configuration files. Any provider selection, model choice, or channel settings you edited by hand are lost.
--import-history is not wired up yet. The flag records the intent in the onboarding summary so the missing step is explicit, but no history is imported.

​
Non-interactive Setup

In CI, a container, or any piped invocation, onboarding detects the non-interactive session and skips both the provider prompts and the service install:
It reports what remains:
Configure the relay yourself with either approach:

​
Verifying Setup

Check what onboarding produced and confirm the runtime is healthy:
doctor reports your home directory, active profile, whether configuration files were found, and whether each driver initialized.

​
What Onboarding Doesn’t Set Up

Onboarding covers the runtime: home directory, configuration, master key, inference provider, web token, and optionally the OS service. It does not connect messaging channels. Slack and Telegram are connected afterwards, in the web interface: Admin → Configuration → fill in the channel’s deployment configuration card → Save Two things trip people up here:
  • The channel’s own Configure button covers only pairing. Using Configure on Telegram from the Extensions page opens the pairing panel, which can only report “An administrator must configure the Telegram bot first.” until the deployment configuration under Admin → Configuration is saved. That is not a permissions problem — the operator step just hasn’t happened yet.
  • Asking the agent to connect a channel covers only the personal half. The operator step — saving the app or bot credentials for the instance — stays in the web interface. Once that’s done, asking the agent (“connect Slack”) works: it installs and activates the extension, an in-chat connection panel opens if your account still needs OAuth, and if your account is already connected the agent says so and continues.
See Channels for the full walkthrough.

Configuration

Every configuration key and how precedence works.

Inference Providers

Choose and configure your model provider.