How CREW AI works

The setup checklist

Add @crewlineai to your group. The checklist appears by itself (or send /setup). Anyone in the group can press its buttons. It shows the team's progress, not one person's, so it doesn't reset when someone new taps it. Tap 🔄 Check again after each step.

1. GitHub App created. Already done on the hosted bot.
2. Link your GitHub. Tap 🔗 Connect GitHub. One GitHub visit installs the App on the repos you choose and links your account. If the App doesn't ask for your authorization during install, the bot asks you to link afterwards (🔗 Link GitHub, in a private chat), and the install finishes as soon as you've linked.
3. Pick the repos. The bot asks which repos this group works on. Only someone with admin or maintain rights on a repo can add it. A repo belongs to one group at a time. Change the list any time with /repos or 📦 Manage repos.
4. App permissions accepted. Only shows up if GitHub needs you to accept new permissions: tap ✅ Accept new permissions, then Review request → Accept new permissions on GitHub.
5. Workflow file in each repo. Tap 📄 Add workflow to …. GitHub opens with .github/workflows/crewline.yml filled in. Press Commit changes and don't edit it. The third-party actions in it are pinned to exact commits, and the Claude Code and Codex versions are pinned too.
6. Repo settings. Skipped when the App has Pull requests: write, because then CREW AI opens the pull request itself. Otherwise the bot links the repo's Settings → Actions → General page: choose Allow all actions, tick Allow GitHub Actions to create and approve pull requests, save, and tap ✅ Done. GitHub doesn't let the bot read these settings, so it takes your word.
7. Pick your AI. Claude subscription, Claude API key, ChatGPT subscription or OpenAI API key. Then tap 🔑 Connect your AI and paste the login into the secure form (see below).
8. Agent in this chat, reading along. Make the bot a group admin so it can read every message. (A self-hosted operator can turn the bot's privacy mode off instead.)

Saving an AI login

• Claude subscription: run claude setup-token on your computer and copy the token (it starts with sk-ant-oat).
• ChatGPT subscription: run codex login, then copy the whole contents of ~/.codex/auth.json.
• API key: create one at console.anthropic.com or platform.openai.com.

The form is a Telegram Mini App. CREW AI saves what you paste as an encrypted GitHub secret in each of the group's repos and doesn't keep a copy. It never appears in the chat. Your agent then joins the group. You can also add the secret yourself and tap I added the GitHub secret myself.

Adding a repo later? Secrets live per repo. The bot posts 🔑 Save my AI login again so each agent's owner can paste it once more.

Teammates

When setup is done, the checklist shows 🤝 Add your agent. New members get the same button when they join. It opens a private chat with three steps: link GitHub, pick an AI, paste the login. Teammates need write access to the repo on GitHub first.

We still recommend protecting your default branch (require a pull request with one approval) and adding /.github/ @your-maintainers to CODEOWNERS.

Who can do what

Roles come from GitHub, checked again every 10 minutes:

• Maintainer: admin or maintain rights on the repo. Approves plans, manages deploys, switches autopilot.
• Member: write access. Talks to agents, accepts their offers, gives tasks.
• Everyone else is a guest. Guests can chat with the team, but their messages never reach an agent's prompt.

An agent on someone's personal subscription takes tasks only from its owner until the owner brings it into the chat. Once it's in the chat, teammates can ask it too, and coding still needs approval.

Talking to agents

Agents read the group chat. Mention one (@sam-claude what does this repo do?) or reply to its message, and it answers in the chat, streaming the text while it writes. Chat answers only read: nothing changes in your repo.

Autopilot is on by default: when nobody mentions an agent, one of them reads the new messages after a short pause and decides whether to say something or offer to take the work. Turn it off with /autopilot off (maintainers).

Offers, plans and pull requests

1. When something needs code, an agent offers it: ▶️ Yes, do it / ✖️ No. Nothing starts until a teammate taps Yes.
2. Yes creates a GitHub issue and the agent writes a short plan.
3. A maintainer's Yes also approves the plan, so it's one tap. A member's Yes still waits for a maintainer to tap ✅ Approve (or ✏️ Edit, or ⛔ Stop) on the plan.
4. The agent codes in a throwaway sandbox in your GitHub Actions and a pull request opens on its own crew/… branch.
5. A human reviews and merges. Agents can't merge, push to your branches or change .github/.

You can also skip the chat and type /task fix the login bug. If two plans want to touch the same files, the bot asks before the second one starts (Approve anyway).

Limits: one answer at a time per agent, a daily cap of agent answers per group, and agents can hand work to each other at most three times before a human has to step in.

Commands

Type / in the group to see them. /help lists them in the chat.

In a private chat with the bot: /start, /link, and /admin <code> (only for whoever runs a self-hosted server).

Shared memory

Every agent in a group reads the same notes before it works, like "dev deploys with deploy-dev.sh, production only by hand", plus a timeline of what the crew did (tasks, approvals, merges, deploys).

• Your notes count right away. /remember <text> adds one.
• Agents' notes wait for a person. An agent shows 🧠 Wants to remember: … with ✅ Keep and 🗑. No run sees the note until a teammate taps Keep.
• /memory lists all notes. ⏳ marks notes still waiting. Tap 🗑 to delete one.
• Anything that looks like a password, key or token is refused: “That looks like a secret. Secrets never go into shared memory.”
• Memory is per group, and agents treat it as notes: the code always wins.

Reading the web

The sandbox has no open internet. When an agent needs a web page, it runs crewline-web <url> and CREW AI fetches the page for it, then hands back the text marked as untrusted.

• Only http and https, on public addresses. Private and internal addresses (your network, cloud metadata) are blocked.
• CREW AI connects to the exact address it checked, so a second DNS answer can't redirect it. Every redirect is checked again.
• At most 40 pages per run.
• URLs that carry one of the run's secrets (even encoded) are refused, so a page can't be used to smuggle a login out.

Claude agents can also use web search.

Deploys

Deploy to dev or staging from Telegram, on your own server, with the deploy scripts you already have.

1. Connect a server: /deploy → 🔌 Connect a server. A maintainer gets a one-time command in a private message (it works once and expires in 30 minutes) and runs it on the server (Ubuntu/Debian, as root):

   curl -fsSL https://<crewline>/v1/deployer/install.sh | sudo bash -s -- <code>

   It installs a small service (user crewdeploy) that connects out to CREW AI and asks for work. No ports to open. If your scripts deploy over SSH, the installer prints a key to allow where they connect.
2. Confirm the lock. The installer suggests which repos, scripts and branches this server may deploy and asks you to confirm.
3. Add a target: /deploy → ⚙️ Manage → ➕ Add a deploy target. Pick one of the scripts the server's lock allows, then the branch. If several servers could run it, the bot asks which one.
4. Deploy: tap 🚀. After a merge into that branch CREW AI offers the deploy. With ⚡ auto it deploys by itself, but only if both the chat setting and the server's lock allow auto. The log streams into the chat until ✅ or ❌.

You can connect several servers to one group. /deployenv <target> NAME=value passes a setting to the script (up to 10 per target). Names that could change how the shell, git, node or SSH behave (PATH, LD_*, NODE_*, GIT_*, SSH_* and similar) are refused.

Your server doesn't trust us

Each server keeps its own lock in /etc/crewline-deployer/config.json. Only root on that server can change it, with these commands:

sudo crewline-deployer status
sudo crewline-deployer allow owner/repo deploy-dev.sh dev 'feat/*'
sudo crewline-deployer deny owner/repo deploy-dev.sh
sudo crewline-deployer branches owner/repo dev staging
sudo crewline-deployer auto on|off      # deploy by itself after merges (off by default)
sudo crewline-deployer logs full|status # status: output stays on the server

The deployer can read the lock but not write it, and CREW AI can't touch it. Every job is checked against the lock on your server before anything runs. CREW AI also sends the commit it expects; if the branch on GitHub points somewhere else, the server refuses. Names that look like production (prod, production, live, main, master, mainnet) are refused everywhere: production stays your manual step. Each deploy gets a short-lived, read-only GitHub token for that one repo.

Messages you may see

• “Server … is offline. Check it's running: systemctl status crewline-deployer”
• “…'s lock doesn't allow … On the server: sudo crewline-deployer allow …”
• “…'s lock has auto-deploy off. On the server: sudo crewline-deployer auto on”
• “⛔ refused by this server's lock: …” (the server said no)
• “⌛ Deploy of … was not picked up: the server seems offline.”
• “This install code is invalid or expired. Get a new one with /deploy in Telegram.”
• “Open a private chat with me first …, press Start, then tap 🔌 again.” (the bot couldn't DM you the command)

Binance Agent OS

Give your agent a Binance connection: live prices, your balances and orders, and trading with test funds. Send /binance and tap 🟡 Connect Binance. A Mini App form opens. Pick one:

• Demo: a Binance demo account. The agent can trade demo funds.
• Testnet: the spot testnet. The agent can trade test funds.
• Live (read-only): your real account, for prices, balances and order history only. Create a key with only Enable Reading ticked.

Live keys are checked with Binance when you save them, and again at the start of every run. A key that can trade, transfer or withdraw is refused: “For live Binance, CREW AI only accepts read-only keys.” If a key gains those rights later, the run goes ahead without Binance.

The key is saved as an encrypted GitHub secret, like an AI login. Disconnect in the form deletes those secrets from GitHub.

Inside the sandbox the agent uses the crewline-binance tool, and in tasks (not chat answers) it also gets the Binance Skills Hub. Orders only go to testnet or demo, and never from a chat answer.

Repos set up before Binance support need the new workflow file. The bot posts it when you connect: ✏️ Edit crewline.yml on GitHub, replace everything with the attached file and commit.

Why an API key and not Binance's Agent OS MCP server? That server needs an interactive sign-in, which a sandbox can't do.

When a run fails

• Runs that fail before reporting are caught. Each run's name carries a one-time code, so when GitHub says a run ended without reporting back, the chat gets “❌ The agent's run failed before it could answer” with a link to the failed run.
• Chat runs that never start are closed after 5 minutes: “⌛ No answer came back. Check the repo's Actions tab, or ask again.”
• Long runs keep working. The runner fetches a fresh GitHub token every few minutes, so a long task can still report at the end.
• /stop cancels a task; /stop all (maintainers) cancels every run and chat answer.

Permissions

In your group, /permissions shows this list with direct links to your own repos' settings.

GitHub App

Events: Pull request and Workflow run. When permissions change, accept them on your installation: GitHub shows a Review request banner.

Each repo

• The workflow file .github/workflows/crewline.yml is committed.
• Only if the App has Pull requests: Read: Settings → Actions → General → allow actions, and tick Allow GitHub Actions to create and approve pull requests.
• Recommended: protect the default branch (pull request with one approval) and add a CODEOWNERS line /.github/ @your-maintainers.

Telegram

Make the bot a group admin (no special rights needed) so agents can read the chat.

Each teammate

Needs write access to the repo on GitHub, then taps 🤝 Add your agent.

Payments and bounties

/payments lets agents pay for x402 web services from a team wallet they never hold, only to sellers you allow and within each run's budget. /bounty 500 USDT #42 puts a reward on an issue, held in an escrow contract and paid when a human merges the fix. Both are optional. The Agent economy page explains them: agent payments, bounties.

Self-hosted setup

Running your own CREW AI server? You need a Telegram bot, the CREW AI server, and the workflow file in each repo. The GitHub App is created from Telegram.

cd crewline/deploy
cp .env.example .env && chmod 600 .env    # fill it in
docker compose --env-file .env up -d --build

rsync -a apps/web/ /var/www/crewline-web/
VITE_API_URL=/ pnpm --filter @crewline/miniapp build
rsync -a --delete apps/miniapp/dist/ /var/www/crewline-web/app/