JosiBeta
Official Josi documentation

Josi Help

Choose a guide, or browse help for the current features.

BetaDocker ComposeAMD64 + ARM64Self-hosted
On this page

Beta warning

Josi is beta-quality software. Features may be incomplete, unavailable, delayed, inaccurate or changed without notice. Do not use Josi as the sole system for emergencies, safety, healthcare, legal, financial, compliance, access control or backups. Review AI output and consequential actions yourself.

Help and current features

Josi is one edition, and it is self-hosted. It gives you one workspace on a computer you own, with conversations, tasks, approvals, contacts, memory, connected accounts, operational mail, documents, Slack messaging, backups, diagnostics, an installable web app, optional Voice Box, and integrations.

You choose the AI model and use your own key with it. Your apps reach your server by its address: a LAN IP, a hostname or a domain, with HTTPS for access from outside your network.

Administrators configure the installation under Admin. Members use their own accounts under Workspace.

Choose a model and use your own key

Open Admin → Model and select Change model. Pick a provider: a model on your own hardware, or a cloud provider such as OpenAI, Anthropic, Google Gemini, Mistral or OpenRouter. Enter the key that provider gave you, select Show me my models and choose one. For a provider outside your server, tick the box that confirms data leaves your server. Then select Save & test. The key is encrypted with your installation's master key.

First-run recovery key

The setup wizard shows the recovery key once. Select Copy key or Download key, store it away from the Josi computer, and then confirm that it was saved. There is no separate terminal command for this step.

Backups and system checkup

Admin → Overview shows installation status and recommendations. Admin → System checkup runs Josi Doctor. It explains problems, offers only bounded automatic repairs, asks for approval, and verifies the result. It also checks the stable release channel and applies an exactly approved update only after creating a backup. Admin → Backups creates backups and configures SMB or NFS storage. Keep the recovery key separately from the backup destination.

Connect Google and Microsoft with your own keys

Josi ships with no Google or Microsoft application of its own. To let people connect Gmail, Google Calendar, Contacts and Drive, or Outlook, Microsoft Calendar, Contacts and OneDrive, you register Josi with each provider and give Josi the keys.

  1. Set a public address first. Google and Microsoft only accept an HTTPS redirect on a real domain name, so a LAN IP address or localhost cannot be registered. Set the domain under Admin → Network & address. Until then, Connectors says A public address is needed first.
  2. Open Admin → Connectors, then Account providers, and open Google application or Microsoft 365 application.
  3. Copy the redirect URL shown there into the provider's own console when you register the application. For Google, also register the extra URL listed for Sign in with Google, if one is shown.
  4. Enter the Client ID and Client secret from the provider and select Save. Josi encrypts the secret with the installation's master key and never shows it again.

Registering the application connects nobody. Each person then connects their own account under Workspace → Connections and is asked for read-only access first. Anything that writes is a separate choice. Member permissions on the same page can switch a permission off for everyone, and Connection health shows whose connection works without showing what is inside the account.

Integrations

Admin → Integrations opens the Developer services view of Connectors, where you choose who may connect GitHub, Netlify, Vercel, Supabase and similar services with their own tokens. Credentials stay in the Master Vault. Consequential writes and deletes still require approval.

Family / Parental Controls BETA

Do not rely on these controls for a child's safety. They control only access to Josi. They do not lock a device, block other apps or websites, monitor location or actual screen time, contact emergency services, or replace active adult supervision and proven device-level controls.