Josi Help
Install Josi on a computer you own, finish setup in your browser, and manage the day-to-day work inside Josi.
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.
1. Run the installer
Install and open Docker first. You do not need Git, Node.js, a source checkout, or a Josi command-line tool.
Choose the command for your computer and paste the whole block into Terminal.
Mac
JOSI_HOST_IP="$(ipconfig getifaddr "$(route -n get default | awk '/interface:/{print $2;exit}')")" && \
test -n "$JOSI_HOST_IP" && \
mkdir -p "$HOME/josi-ce" && cd "$HOME/josi-ce" && \
docker run --rm \
-e JOSI_INSTALLER_HOSTNAME="$JOSI_HOST_IP" -p 8080:8080 \
-v "$HOME/.docker/run/docker.sock:/var/run/docker.sock" \
-v "$PWD:$PWD" -w "$PWD" \
docker.io/romanvaxman/josi-ce-installer:latest
Linux
JOSI_HOST_IP="$(ip -4 route get 1.1.1.1 | awk '{for(i=1;i<=NF;i++)if($i=="src"){print $(i+1);exit}}')" && \
test -n "$JOSI_HOST_IP" && \
mkdir -p "$HOME/josi-ce" && cd "$HOME/josi-ce" && \
docker run --rm \
-e JOSI_INSTALLER_HOSTNAME="$JOSI_HOST_IP" -p 8080:8080 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$PWD:$PWD" -w "$PWD" \
docker.io/romanvaxman/josi-ce-installer:latest
The installer prints one private setup link using the computer's LAN address. Leave the Terminal window open while setup is running. The same link works from another device on the local network, including a headless Josi server. It never uses Docker Desktop's hidden Linux-VM address.
The temporary installer can control Docker so it can create the Josi services. It exits when installation finishes. Normal Josi services do not receive the Docker socket.
2. Finish setup in your browser
- Open the setup URL printed in Terminal.
- Accept the temporary local-certificate warning.
- The private link connects to the installer automatically.
- Choose whether Josi is available on this computer, your local network, a public domain, or through an existing proxy or tunnel.
- Optionally choose one project folder for coding features. Skip it if you do not need Josi to work with local files.
- Review the choices and select Install Josi.
The browser installer writes the configuration, generates the installation secrets, downloads the published images, starts Josi, and checks that it opens.
You do not edit .env, run Compose, or use the Josi management CLI
during the normal installation path.
3. Open Josi
When installation succeeds, select Open Josi. The first person through setup becomes the administrator.
Josi walks through the account, AI provider, privacy choices, and optional connections. When the recovery key appears, copy or download it and store it somewhere other than the Josi computer.
4. Confirm it works
Open the Josi URL and send a message. If Josi opens and answers using the provider configured during setup, the installation works. You do not need to inspect containers or call health endpoints.
After installation
Use Josi's Admin screens for normal management:
- Overview shows status and recommendations.
- System checkup explains problems, offers safe automatic repairs, and installs approved stable updates.
- Network & address changes local, LAN, domain, proxy, or tunnel access.
- Backups creates backups and configures storage.
- Model chooses the AI model and holds your key.
- Connectors holds your own Google and Microsoft keys.
- Integrations opens the developer services view of Connectors.
- Users manages workspace access.
Keep Docker running. On a dedicated Mac mini, enable Docker Desktop at login so Josi returns after a restart.
Use Josi on your devices
Your Josi server is the home for every client. The web app and native apps use the same account, workspace, conversations, memory, and tools.
- Android: Install Josi from Google Play.
- iPhone and iPad: Install Josi from the App Store.
- Windows, Mac and Linux: the downloads at get.heyjosi.com.
On a Mac there are two apps. Josi sets up and runs the server on that Mac and opens your workspace. Josi Client is for a Mac that uses a server running somewhere else: you give it the server's address and sign in.
Every app asks for the server's address once. Type the address the server
answers at: a LAN IP, a hostname or a domain. Remote access needs HTTPS. The
apps accept plain http:// only for localhost and
addresses on your own network. The server's address is set on its
Network & address page (in the Josi app on the server PC, or
the web app as a super admin). There are three common setups:
- A LAN IP or hostname. Set the public address to
https://<name or IP>:8080. Josi answers over HTTPS with a certificate it issues itself; the app shows the certificate fingerprint once and you compare it with the one on the Network page. Works at home or at the office, and over a VPN. - Tailscale. For a phone or a PC anywhere, with no public domain and no port forwarding. Install Tailscale on the server and on each device and sign them all in to the same Tailscale account. The Network page then shows the server's Tailscale address and a Use the Tailscale address button; press it and restart the server. On the phone, with Tailscale on, give the Josi app that address. Josi does not install Tailscale and does not talk to Tailscale's service; it only reads the state of the Tailscale you installed.
- A public domain.
https://your.domainserved through a tunnel or a reverse proxy you run, pointed at the server PC.
To connect an app:
- Open Josi on the device.
- Enter the server's address.
- If the app shows a certificate fingerprint, compare it with the Network page and accept it.
- Sign in with the same Josi account you created in the browser.
The app connects to the Josi server you installed. It does not install or create another server.
Updating Josi
Open Admin → System checkup as a super-admin, select Check for updates, review the release notes, enter the exact confirmation shown, and approve the update. Josi creates a backup, applies the pinned release, verifies health, and rolls back automatically when a safe rollback is possible.
If Josi cannot open or the maintenance helper is unavailable, run the same
installer command again. The browser installer detects the existing installation
and preserves its configuration and data. Do not delete the
josi-ce folder or Docker volumes during an update.
Backups
Open Admin → Backups to create a backup or configure SMB/NFS storage. Keep the recovery key separately from the backup destination. A backup and the key protect different things, so you need both.
Troubleshooting
Docker is not running
Open Docker Desktop on Mac, or start Docker Engine on Linux, then run the same installer command again.
The Mac reports that the Docker socket does not exist
Wait until Docker Desktop says the engine is running, then retry. Josi uses
Docker Desktop's user socket at $HOME/.docker/run/docker.sock.
Port 8080 is already in use
Stop the program using port 8080, then run the installer again. That port is used only for the temporary setup page.
The browser warns that the setup page is not private
This is expected for the temporary local setup certificate. Confirm that the address matches the one printed by the installer before continuing.
Setup was interrupted
Run the same installer command again. It reuses the
$HOME/josi-ce directory and preserves completed configuration.
Josi installed but does not open
Return to the installer window and use its reported error. If Josi previously worked, open Admin → Overview for the system checkup. Do not delete Docker volumes or the installation directory while troubleshooting.
Source code and licence
Josi is licensed under GNU AGPL v3. The source code is available on GitHub. Licence terms, security reporting, and developer documentation are kept separate from this end-user installation path.
