arizuko › howto › getting started

getting started

This page walks a fresh host from zero to a running instance with one channel and one invited user. Each step is one command. Skim the whole list first; come back and run them in order.

1. What you need

• A Linux host you can sudo on. arizuko is tested on Debian 12.
• Docker (with the docker compose plugin). Every daemon and every agent runs in a container.
• Go 1.22+ if you build from source. Skip this if you grab a pre-built binary.
• About 4 GB of free disk under /srv/data/ per instance.
• A public domain and TLS, only if you want web chat, OAuth login, or inbound webhooks from Slack/Discord. A local-only instance needs neither.
• No ports open to the internet by default. Channel adapters listen on the docker network; webd + proxyd bind :80/:443 only when you turn on the web layer.

2. Install

Clone the repo and build. The Makefile produces ./arizuko plus every daemon binary.

git clone https://github.com/kronael/arizuko.git
cd arizuko
make build
sudo make images   # build agent + daemon docker images
sudo install -m 0755 arizuko /usr/local/bin/arizuko

The make images step is the longest (several minutes the first time). It builds arizuko-ant:latest, the per-group agent image, plus one image per shipped adapter.

3. Create your first instance

Pick a short name. The name becomes the data directory and the systemd unit name.

sudo arizuko create demo

This seeds /srv/data/arizuko_demo/ with:

• .env — instance config with a fresh CHANNEL_SECRET. Mode 0600. Edit it to add API keys later.
• store/messages.db — SQLite database (WAL). One default group called main.
• groups/main/ — the first agent's home: PERSONA.md, .claude/ session dir, facts/, diary/.
• ipc/main/ — placeholder for the MCP unix socket the agent will use.
• web/pub/ — a copy of these docs, served by vited.

Pass --product <name> (for example --product assistant) to seed skills and a checklist of API keys to fill in. See products for the catalog.

4. Run it

arizuko run generates docker-compose.yml from the instance state and brings the stack up in the foreground.

sudo arizuko run demo

You should see gated, timed, onbod, dashd, and the agent runner come up. In another shell, check status:

sudo arizuko status demo

For production, run arizuko as a systemd service named arizuko_demo instead of in the foreground. Logs then live in journalctl -u arizuko_demo — the docker log driver is none on purpose, so docker logs shows nothing.

5. Wire your first channel

An instance with no channel adapter has no way to receive messages from the outside. Pick one platform to start. Each guide covers the platform's app/bot setup, the env vars to drop into .env, and the arizuko group add command that binds a chat to a folder.

• Slack — Slack App, signing secret, Events API.
• Discord — bot token, mention-only channels, threads.
• Asymmetric channels — ingest on one platform, reply on another.

Telegram, WhatsApp, Mastodon, Bluesky, Reddit, Email, X, and LinkedIn adapters ship in the repo. Their setup follows the same shape; see the README.md next to each daemon (teled/, whapd/, …).

6. Invite your first user

Mint a one-time invite link. target_glob decides which folders the new user will be granted access to. main/** means “the main group and any sub-group under it.”

sudo arizuko invite demo create 'main/**' --max-uses 1 --expires 24h

The command prints a token. Share https://<your-host>/onboarding/<token>. The recipient signs in with one of the configured OAuth providers, lands on a confirmation page, and their auth_users.sub is granted admin on the matched folders. List and revoke with arizuko invite demo list and arizuko invite demo revoke <token>.

7. Verify the agent responds

Two ways to confirm the loop is live.

From the host, inject a message and wait for the reply:

sudo arizuko send demo main "ping" --wait

From the channel, send a message in the wired chat and watch the gateway pick it up:

sudo journalctl -u arizuko_demo --since "2 min ago" --no-pager | grep -iE 'mention|spawn|reply'

Red flags in the log: error in message loop, container timeout, circuit breaker open, pull access denied for arizuko-ant (means make images never ran on this host).

Further reading

Vocabulary:

group

A workspace. Files, diary, skills, and one agent live here. Folder name like main or corp/eng/sre.

agent

The Claude Code instance for a group. Runs in a docker container, started on demand, idle-killed.

channel

Where messages flow in and out: Slack, Discord, Telegram, web, email, …. Each adapter is a separate daemon.

skill

A markdown file under groups/<folder>/.claude/skills/ the agent loads on start. One file, one capability.

route token

A URL-bound credential mapping to a group. /chat/<token>/ opens the guest chat widget; /hook/<token> accepts fire-and-forget webhooks. Legacy /slink/<token> 301s to the new paths. See route tokens.

More guides:

• Talking to agents — mentions, slash commands, sticky routing, MCP tools.
• Put a chat link on your site — visitor chat via /chat/<token>/.
• Wire webhooks into arizuko — GitHub, Linear, custom alerts via /hook/<token>.
• Mount the workspace over WebDAV — rclone, Finder, curl.
• Deploy on Kubernetes — StatefulSets, PersistentVolumes, agent image pull, health checks.
• Concepts — routing, auth, grants, route tokens, voice.
• Reference — CLI, env vars, MCP tools, schema.

Audit mode (mute outbound)

Two env vars on the gateway run a group or platform in shadow mode: the agent keeps producing turns, every outbound row lands in messages, but nothing reaches the channel.

SEND_DISABLED_GROUPS

CSV of folder names. Example: SEND_DISABLED_GROUPS=atlas,research.

SEND_DISABLED_CHANNELS

CSV of platform prefixes (the part before : in a JID). Example: SEND_DISABLED_CHANNELS=discord.

Inbound is unaffected. The agent does not know it was muted — send_reply returns success. Rows are visible at /dash/activity/ and via the inspect_messages MCP tool. Source: gateway/gateway.go (group + platform mute), core/config.go (parsing), gateway/gateway_test.go TestMakeOutputCallback_MutedGroup (locked behaviour).