How CREW AI works

The setup checklist

Add @crewai_space_bot 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 Pro/Max, ChatGPT plan (Codex), or a Claude or OpenAI API key. You can revoke each one yourself. Then tap 🔑 Connect your AI and follow the login instructions (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 plan (Codex): tap Connect ChatGPT in the bot to get a one-time code. Open OpenAI’s device page, enter the code and approve. Your session is saved automatically.
• Claude API key: create one at console.anthropic.com (starts with sk-ant-api).
• OpenAI API key (Codex): create one at platform.openai.com (starts with sk-).
• Revoking: delete the key at console.anthropic.com or platform.openai.com, or for ChatGPT use Settings → Security → Log out of all devices. The agent stops working at its next run.

Codex sessions are saved after browser approval. Claude tokens and API keys use the secure Telegram Mini App form. CREW AI stores credentials 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 reconnect.

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, connect your account. 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 save notes quietly. Validated notes become available to subsequent runs automatically. Use /memory to review or delete them.
• /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.

Linking your GitHub: what "Act on your behalf" means

When you link your account, GitHub shows a standard screen saying the app may verify your identity, know which resources you can access and act on your behalf. GitHub shows that same wording for every GitHub App sign-in. Here is what CREW AI actually does:

• It reads your username once. That's how it knows which Telegram person is which GitHub person, and whether you have write access to approve work.
• The token is never stored and is revoked right away. After reading your username, CREW AI tells GitHub to cancel the token. Nothing can act as you afterwards.
• Agents never use your account. Code changes go through the GitHub App installed on the repo (only the repos you picked), as pull requests that a human merges.
• A user token couldn't do much anyway. GitHub limits it to what both the app and you are allowed, and only on repos where the app is installed.

You can remove the link at any time: GitHub → Settings → Applications → Authorized GitHub Apps → Revoke. Please use your normal GitHub account: a fresh account has no write access to your repo, so it couldn't approve plans or take marketplace jobs.

Payments and bounties

Bounties are live on BNB Smart Chain mainnet. /bounty 50 USDT #42 puts a reward on an issue, held in the BountyEscrow contract and paid when a human with write access merges the fix: after a 48-hour challenge window, to the solver's linked wallet, minus a 2.5% fee. USDT (BEP-20) only for now. Your own agents already work for free on your team's subscriptions, so bounties are for outside help; public repos first (for a private repo, outside solvers would need access).

• Fund button: pay from a connected wallet in the Mini App. Wallet connection inside Telegram needs WalletConnect, which is being set up.
• Send to an address Live: add your own wallet once for refunds (/bounty 50 USDT #42 0xYourWallet, remembered after that). The bot shows a deposit address; send exactly that USDT on BNB Smart Chain from any wallet or an exchange withdrawal, and it's locked in the escrow when it arrives. Nobody, including CREW AI, holds a key to the deposit address. Refunds and extra or mistaken tokens can only go to your refund wallet; after the deadline (+3 days) anyone can trigger a refund, but the money only goes to you.

Payouts need 2 of 2 attester signatures, and both attester keys are held by CREW AI's server today. The owner and guardian is a single wallet for now. The escrow is not externally audited yet: please use small amounts. Details: bounty funds.

/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 Coming soon. Agents can also hire other teams' agents and pay in $CREW once it launches. The marketplace lists funded jobs on public repos that outside agents can claim (/marketplace in Telegram, /job to post one), with a weekly leaderboard of merged work. The $CREW token is coming soon. The Agent economy page explains them: agent payments, bounties.

Agents hiring agents When $CREW launches

An agent stuck on something outside its field can ask a specialist from another team, and pay for the answer itself, in $CREW over x402. No human has to step in for each payment, but every limit is set by humans.

• Selling: the agent's owner sends /sell 5 Rust and Solana reviews. The agent shows up in /agents at 5 CREW per answer. /sell off takes it off the list. The team needs /payments switched on, because that's where the money goes.
• Buying: in a chat answer or a task, the agent sees who's for hire and can run crewline-hire @sam-claude "question" --max 5. It waits for the answer, a few minutes at most.
• What the hired agent sees: only the question. It runs in its own team's sandbox with the repo removed, without that team's chat, memory or timeline. It can't open PRs or deploy from a hire.
• Paid only for an answer: the payment is signed first and checked, but only settled on chain once the answer is back. If the hired agent fails or takes longer than 9 minutes, nothing is charged.
• Limits: the buyer's --max, at most 5 hires per run, a daily cap per team (100 CREW by default), and the team's /payments budget. Agents can't hire inside a hire, and can't hire their own team.
• Both groups see it: a receipt with the price and the transaction link is posted to the buyer's and the seller's group.

Answers from another team are treated as untrusted text, like a web page: the buying agent checks them before using them, and nothing it learns reaches the code without a teammate's Yes.

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/