This guide walks you through installing Joy on your own machine and chatting with your agent in minutes.

​
Installing Joy

For personal use on your own machine with full control.

​
1. Install Joy

Install the single binary:
On Windows, use the PowerShell installer:
Verify the install:

​
2. Run setup

Create your Joy home directory, provision a login token, and choose your inference provider:
When it finishes it prints a login link containing your token:
Joy uses its built-in relay for inference — onboarding asks for your relay API key and stores it as JOY_RELAY_API_KEY. See Inference Providers for the three model tiers.
Everything lives under ~/.joy:Your master encryption key is stored in the OS keychain, not on disk. See Security.
In a script or CI, onboarding skips the interactive prompts and the service install:
Configure your provider separately with joy models set-provider <provider> --model <model>, or by exporting the provider’s environment variables before running serve.Use --dry-run to see exactly what would be written without touching the filesystem.

​
3. Start the agent

Start the web interface:
By default it listens on 127.0.0.1:3000 — local only. Open the login link from the previous step in your browser, and you’ll land in the chat interface.
If port 3000 is taken, pass a different one:
Use --port 0 to let the operating system pick any free port.

​
4. Chat with your agent

Type a message in the chat and the agent will respond. From here you can also reach Projects, Jobs, Routines, and Settings from the sidebar. If you prefer the terminal, Joy has a REPL and a one-shot mode:

​
5. Keep it running

To have Joy start automatically in the background, install it as a system service (launchd on macOS, systemd on Linux):
Stop the foreground joy serve first. The service runs serve too, so starting it while your terminal still holds the port fails with an address-already-in-use error.

​
6. Update Joy

Update to the latest release:

​
Next Steps

Now that your agent is running, connect a channel so you can reach it from a messaging app, and add extensions to give it more capabilities.

Channels

Connect your agent to Slack or Telegram.

Extensions

Give your agent access to external APIs and services.