Getting started

The fastest way to run Aictiq is the compose bundle in the repository's deploy/ directory - five commands from a clean host to a running instance. This page gets you there; Self-hosting covers everything you may want to change afterwards.

Prerequisites

• A host with Docker and the compose plugin. The images build from source, so no .NET or Node tooling is needed on the host.
• The repository checkout - the bundle, its .env.example and the Garage configuration live in deploy/.
• For evaluation, nothing else. For a real deployment: ports 80 and 443 reachable from the internet and a DNS name pointed at the host.

Start the stack

cd deploy
cp .env.example .env
$EDITOR .env          # fill in every CHANGE_ME - the file shows how to generate each secret
docker compose up --build -d
open http://localhost

Compose refuses to start rather than inventing a default for any secret, so a half-filled .env fails loudly instead of shipping a guessable key.

The first start builds the API and web app images, initializes Postgres, gives Garage a cluster layout and a bucket, and the API applies migrations and seeds the administrator. Sign in at http://localhost with the SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD you set in .env.

What is running: Postgres, Garage (object storage), the API - which serves the web app from the same origin - the background workers, and Caddy terminating TLS. Only Caddy publishes ports; the rest are reachable only inside the compose network.

First steps in the app

1. Change the seeded administrator's password - it stays in .env until you do.
2. Create a project. Its key (ACME in ACME-123) prefixes every item id your team will quote in commits, chat and agent configuration, and it is permanent.
3. Invite the team. With no SMTP relay configured, invitations are shared as links instead of mail - email is optional everywhere. See Self-hosting → Email.

Switch projects using the project list in the left sidebar. The current view stays open for the selected project: Overview, Items, Wiki, Board, Backlog, Sprints or project Settings. Backlog and Sprints use that project's remembered team, or its default team. An open item, wiki page or sprint returns to the corresponding list. Personal and organization pages stay open; project Settings opens Items if you are not an admin in the selected project.

In descriptions, comments and wiki pages, type # or choose the # formatting button to reference a ticket from the current project. Search by key, number or title, then use arrow keys and Enter/Tab, or click a result. The saved Markdown contains plain #ACME-123 text. Rendered descriptions, comments and wiki pages link existing tickets in the same project; code, unknown keys and other-project references remain plain text.

The in-app tour and Get started

Aictiq offers a short product tour on a new account's first working screen, and a resumable Get started checklist behind the account menu, the command palette (Ctrl/Cmd+K) and Account settings → Profile. Both stay available afterwards: Get started reopens the checklist, Replay product tour starts the orientation again, and neither undoes anything you have already set up.

The tour explains the navigation, organizations, projects and teams, the board, writing an item an agent can run, project knowledge in the wiki, and - for whoever may operate the factory - agents, runners, playbooks, the explicit handoff, and reviewing the result. It is read-only: walking it dispatches nothing and changes no configuration.

The checklist is the same path as this page and the factory guide, with a live status per task computed from the API: Ready, Needs setup, Needs an admin, or Could not check. It tells registration apart from an online runner, and an online runner apart from a machine whose harness, repository checkout and push credentials actually work - those last it can only tell you to verify on the machine itself.

Teams that only track work can ignore the AI tasks indefinitely; nothing prompts again once the tour is skipped or finished.

Connect an agent

Setting up AI work end to end - an agent account, a runner, a playbook and a repository - is what Get started walks through, and the factory guide is the long form. The steps below are the separate, optional path for pointing your own MCP client or terminal at Aictiq with a personal access token. A personal token is not a runner credential: a runner gets its own secret from Factory → Runners.

1. Create an agent and its token in Organization settings → Agents. A token for MCP needs the mcp scope and an organization binding; add read and write for an agent that will claim and update work. The full instructions are in Connect an agent.

2. Point Claude Code at it over HTTP:

   {
     "mcpServers": {
       "aictiq": {
         "type": "http",
         "url": "https://aictiq.example.com/mcp",
         "headers": { "Authorization": "Bearer aiq_your_token" }
       }
     }
   }

3. Or work from a terminal through the CLI:

   npm install -g @aictiq/cli
   aictiq auth login --url https://aictiq.example.com
   aictiq item list -p ACME --filter "state:todo"

The loop the agent should follow - claim before writing code, heartbeat while working, report progress by editing one comment, link the pull request - is the second half of Connect an agent.

Serving a real domain

Set AICTIQ_URL=https://aictiq.example.com in .env and Caddy obtains and renews the certificate automatically; ports 80 and 443 must be reachable for the ACME challenge. A non-default port must also appear in AICTIQ_URL. Published-image configuration, realtime scale-out and troubleshooting live in the repository's deploy/README.md.

React to a comment

On an item's comment thread, choose React next to Reply, then select 👍 👎 ❤️ 🎉 👀 or ✅. Each used emoji appears below the comment with its count. Your reactions are highlighted; click a chip again to remove yours. Hover over a chip to see who reacted. Replies have the same controls, and you can use several different emojis on one comment. Archived projects show existing reactions without allowing changes.

The comment author receives an Inbox update and email for your first use of an emoji. Reacting to your own comment, removing a reaction, or adding it back sends no further notification. Change the Reacted row in Settings → Notifications to mute these updates.

Notifications

The notification bell opens a popup with updates from work you follow. Unread updates are bold and count toward the bell badge. Click an update to open its item and mark it read, or choose Mark all read to clear the unread styling and badge. View all notifications opens the full inbox. Notification item links retain their original organization, even when you are working in another one. Run-completion updates open the run for factory operators and the related item for other members.

Choosing how you hear about things

Settings → Notifications has one row per kind of update. Inbox turns a kind on or off everywhere: with Inbox off you get nothing for that kind on any channel. Email is Off, Immediate, or Daily digest (one mail at 08:00 in your time zone). Immediate email and chat messages are skipped while you are active in the app, since you see the update there. Mentions and replies to your comments are always sent.

Three kinds are about factory runs: Run succeeded, Run failed (including timed out and cancelled), and Run needs input (a refine run came back with questions). They go to the person who started the run and to the item's assignee, and link to the run.

Telegram, Slack and Discord

Under Channels on the same page you can connect your own:

• Slack: create an incoming webhook for a channel or your DMs and paste its URL (https://hooks.slack.com/services/…).
• Discord: in a channel's Integrations → Webhooks, create a webhook and paste its URL (https://discord.com/api/webhooks/…).
• Telegram: choose Connect to get a one-time code. Open the link, or send /start <code> to the Aictiq bot yourself. The code expires after 15 minutes. Telegram only appears if the instance has a bot configured. Self-hosted operators should read Self-hosting.

Each connected channel adds a column with Default, Off, Immediate and Daily digest. Default uses your organization's default for that kind. If the organization has none, it does whatever your Email does. A newly connected channel therefore starts out matching email. A digest is one message a day at 08:00 your time.

Send test posts a test message. Webhook URLs and chat ids are stored encrypted and only shown masked. If a channel keeps failing (for example, the webhook was deleted or the bot was blocked), it is marked broken and stops receiving messages, while your other channels keep working. A successful Send test brings it back.

Organization channels and defaults

Org admins have Org settings → Notifications:

• Shared channels: connect a Slack or Discord webhook, or a Telegram group (add the bot to the group and send /start <code> there), for example #dev. Shared channels get organization-wide events only, never personal ones like "you were mentioned". These events are state changes, sprint started and completed, and run succeeded, failed and needs input. Each one can be Off, Immediate or Daily digest (08:00 UTC). New channels start with sprints and failed or blocked runs on.
• Member defaults: a default per kind for email and each chat platform. It applies to members who have not chosen a setting themselves; a member's own choice always wins.

Every plan includes chat channels.

Where to next

• Self-hosting - object storage (AWS S3, MinIO, R2), external Postgres, rate limits, backups and the restore drill.
• Operations - the observability profile, dashboards, and what pages an operator.
• REST API - authentication, filtering, concurrency and error conventions.
• Outgoing webhooks - events, signatures and retries.
• FAQ - the questions that come up after the first week.