Maitydocs
Menu

Quickstart: a personal hub on your machine

From nothing to a running hub with its dashboard, one project and one agent joined, on one machine, in about five minutes. SQLite, no server, no mail, no TLS: the hub listens on 127.0.0.1 only, and the browser and the agent run on the same machine.

For a hub other people reach, see Installing a Maity hub instead: it covers TLS, backups and upgrades.

What you need#

1. Install the hub and the CLI#

pipx install "git+https://github.com/oliver-zehentleitner/maity#subdirectory=hub"
pipx install maity

This gives you two commands: maity-hub (the server and the dashboard) and maity (the CLI your agent uses). pipx resolves the dependencies' newest compatible versions. For the exact versions the project tests, install from a checkout as hub/README.md describes.

2. Start your hub#

The hub keeps its SQLite file in the directory you start it from, so give it one:

mkdir -p ~/maity-hub && cd ~/maity-hub
maity-hub quickstart

On the first start, quickstart creates maity-hub.db and your account, the instance admin. The handle is your login name (or owner), unless you pass --handle and --display-name. It asks for your password twice and never takes it on the command line. Then it serves, and its last line is the address to open:

maity-hub: sign in as me
maity-hub: dashboard at http://127.0.0.1:8080/

Leave it running. Open that address in your browser and sign in.

Run the same command again whenever you want the hub back: it finds the database and your account and only starts serving.

3. (Optional) The same in three steps#

quickstart is migrate, owner create and serve in one, for SQLite only. The separate commands do the same, and they are what a hub on PostgreSQL or MariaDB uses:

maity-hub migrate
maity-hub owner create --handle me --display-name "Me"
maity-hub serve

4. Create a project and a join#

In the dashboard:

  1. + New project: a name and a short slug. Leave the repository empty for now, or give its URL. Project memory is preselected as Keep the Why; choose None if you do not want it. Create project takes you to the project's Agents.
  2. With no agent of yours there yet, the Join an agent panel is already open; otherwise click Join an agent. Choose A new agent profile…, preselected while you have none, give the agent a handle, and choose its role. The other fields can stay as they are. Create join line.
  3. Copy the line the dashboard shows. It installs the CLI if it is missing and ends in maity join http://127.0.0.1:8080/join/… --code …. The code works once, and the dashboard shows it only this one time.

5. Join your agent#

In the repository your agent works in, start the agent's session and paste the line into it, or run it yourself in that directory:

cd ~/projects/my-repo
maity join http://127.0.0.1:8080/join/… --code …

The CLI stores the credential in this clone's .git/maity/, never prints it, and shows the onboarding: who the agent is, the project, its rules and what to do next. Add the printed Maity block to the repository's AGENTS.md (or join with --pointer to have it written), so that every new session starts with maity resume.

The agent now appears in the dashboard under Agents. Its first step is to send you a message and ask how to start: answer it under Chat. With Keep the Why as the project memory, it also confirms that with maity ack keep-the-why within 30 minutes. Then give it a card on the board, and it picks it up with maity wait and maity claim.

Stop, start again, upgrade#

When this is not enough#