Docs Self-hosting & operations
Self-hosting & operations
First run and recovery
What to do on your first visit to a new installation, and how the owner gets back in after losing a session or account access — with nothing more than shell access to the machine running Kumo.io.
Two kinds of login
A self-hosted installation has two separate logins:
| Login | Where | Who | For |
|---|---|---|---|
| Product login | /login | Everyone on your team | Workspaces, sources, diagrams — the product |
| Owner login | /signin | The installation's owner | The installation's system pages under /admin/system |
The owner is whoever approved the installation's connection to a Kumo.io account. There are no default passwords for either login.
Your first visit
- Start Kumo.io and wait for
✓ Kumo.io is readyin the log — see Run Kumo.io in one container. - Connect the installation. Open http://localhost:9500. Until the installation is connected it shows the setup screen; follow Connect an installation. Connecting makes you the installation's owner, and Open Kumo.io at the end signs you in to the product.
- Invite your team rather than having teammates sign up on their own — signing up without an invitation creates a separate account. See Invite your team.
- Set a recovery passphrase — see below. It is optional, but it is the only owner login that needs neither Kumo.io's service nor shell access.
If the installation has an email relay configured, sign-up sends a verification link and you must open it before you can log in. Without a relay, no verification is needed. See Email.
The startup page
/setup shows each startup step and whether it passed. If Kumo.io could not start, the page says Kumo.io could not start and each failed step has a What to do note. Once Kumo.io is ready, /setup shows the setup screen instead; once the installation is connected, it shows You're all set.
Log in as the owner
Open /signin on the installation, for example http://localhost:9500/signin. The Owner login page offers:
- Log in with your Kumo.io account — approve the login in the account portal from the account this installation is connected to. The page checks automatically and logs you in once you approve.
- A one-time code or recovery passphrase — paste it and choose Log in.
Get a one-time code with shell access
If you can't use your Kumo.io account — no network, or no access to the account — shell access to the machine running Kumo.io is enough:
docker exec <container> kumo recoverIt prints a one-time owner sign-in code. Paste it into the /signin page. The code:
- works once,
- expires after 15 minutes,
- changes nothing else about the installation.
If the installation has no owner yet, kumo recover says so and exits — open /setup and connect the installation first.
Set a recovery passphrase
As the owner, open Security at /admin/system/security. Enter a passphrase of at least 12 characters and choose Set passphrase. To change it later, enter a new one and choose Rotate passphrase.
With a passphrase set, you can log in at /signin with it, even when Kumo.io's service is unreachable.
Lost your product password
Choose Forgot Password? on the Log in to Kumo.io page at /login. Password reset sends an email, so it needs an email relay; see Email.
The admin API credential
The admin API has its own credential, separate from both logins. A new container creates it on first boot and prints it once in the log; it is also stored at /data/keys/admin-bootstrap.token on the data volume. See Run Kumo.io in one container.