Install q15

q15 installs with four commands.

on your server

curl -fsSL https://q15.co/install.sh | sh
q15 init
q15 up
q15 status

Command	What it does
the curl	One signed binary into ~/.local/bin. No sudo, nothing installed system-wide.
q15 init	Names the agent, picks a model, sets the address.
q15 up	Renders the units, starts the stack, waits for health.
q15 status	What runs, and what the agent can reach.

init prints the address of the browser client. Open it, create your passkey, send a message.

The installer is not built yet

There is no q15 binary in any release. The tickets that produce it are filed and none has shipped, so those four commands do not work today. Until they do, run the published images: that page has the Compose file, the volumes, the secret files and the health checks, and it is how every deployment that exists was built.

What init asks

• The agent’s name. It names the units and the volumes, so renaming it later means a migration.
• The address. Your passkey is bound to its hostname, so decide it before you enrol. Changing it later fails startup.
• The model. An Ollama API key, an Ollama server you run yourself, or any OpenAI-compatible endpoint. This one is not final: the agent lists and switches models at runtime.

The name and the address are the two that do not change afterwards.

Before you start

FOR THIS YOU NEED
· SSH and a shell
· A DNS record, only if you want a public hostname

AND THIS
· Linux with systemd and rootless podman 4.9 or newer
· 2 GB RAM for the stack, plus room for the models you pick

Tested minimum CPU, RAM and disk figures are in development. What is known: the images, the embedding weights the stack downloads on first start (the project’s own figure is about 1.2 GB for the default model), and your growing /workspace and /memory.

Synced passkeys are refused. q15 needs a credential it can revoke for one device, so iCloud Keychain and password-manager passkeys do not enrol. Use a security key with PIN verification, or a device-bound platform authenticator. The reason is in Chat.

What you end up with

Six containers: the four q15 images (q15-web, q15-agent, q15-exec, q15-proxy), a vector database for search, and a model server. The four q15 images always carry the same release tag, because the agent and the browser client share a bridge protocol.

What runs today is one step behind this page

Today’s stack serves embeddings from a local TEI container and talks to a model provider you configure. Shipping Ollama inside the stack, so that a local model is the default, is filed work. The reference describes the stack as it is.

Your data is files. /workspace is the project tree, /memory is the transcript and what the agent has learned from it, and both survive updates and reboots. See Backups for what to copy.

Only the browser client binds a port, and only on 127.0.0.1:8080. Everything else is reachable only inside the stack, and the credentials never reach the agent: every outbound request goes through q15-proxy, which holds them.

A Telegram bot is optional and takes two values, a bot token and your numeric user ID. See Telegram.

Serving it

The browser client binds loopback, so reach it over an SSH forward or put a TLS terminator in front. The hostname you give init is the public one: your passkey is bound to it. A worked reverse-proxy example is in development; the reference lists what the stack expects.

Keeping it running

once the binary ships

q15 status
q15 logs -f q15-agent
q15 doctor          # what runs, which credentials resolve, what the agent can reach
q15 secret set      # add or replace a credential

Not built yet. Those four are the goal, not the current state; today the same four things come from the Compose commands in the reference.

The units are systemd user units, so the stack comes back after a reboot without you logging in. To move to another release, install the newer q15 and run q15 up again.

Where to go next

• Reference for the stack as it runs today: files, volumes, ports, tags, keys.
• Updating for releases and what does not roll back.
• Backups before you have anything to lose.
• Troubleshooting when something is not healthy.
• Security before you give the agent a shell.