Appearance
Your first agent
About fifteen minutes, assuming someone has already set up a model (if not, start at Models and keys).
The quickest start
The first time you sign in, CrewHall welcomes you with four ready-made agents: Researcher, Executive assistant, Content writer and Developer. Pick one and it's created in your personal space, published, and its conversation opens with a few example messages to try: click one to send it. It needs a model: the server may offer one, or add your own key first. If an organization invited you, the welcome shows the agents it shares with you instead.
Show me around points out the main places on the screen, one after another. Help (the question mark in the top bar) has the tour again later, and Show the welcome and tips again brings back the welcome and the tips some pages show on your first visit. On a phone there's no tour.
To make an agent of your own, read on.
1. Pick where it lives
Top left, the switcher shows your personal space and any organizations you belong to.
- Your personal space: private to you, shared only with people you name. Good for a first try, and for anything you don't want colleagues to see.
- An organization: its owners and admins can see and edit everything in it. Good for an agent other people will depend on.
You can't move an agent between owners later, so if it is for the team, start it there.
2. Create it
New agent (top right, or the + in the bar) first asks where to start:
- A template: a ready-made role such as Developer, Bug analyst, Customer support, Business analyst, Project manager, Researcher, Accountant, Lawyer, Executive assistant or Content writer. It brings a written soul and instructions, the tools and integrations that role uses, and a model chosen for cost.
- Blank agent: you write the role yourself, or let the agent interview you (see below).
Templates your space saved come first, and the gallery has more, shared by people on this server.
Picking a template shows, before anything is created, what it comes with in the space you chose:
- Ready (green): the tool or integration is on, and the agent gets it.
- Connect your account (amber): the integration is on, but it uses each person's own account and you haven't connected yours. The agent gets it; connect from its Configure tab or under Account → Connections.
- Not enabled, Not set up or Not offered (red): an admin has to turn it on first. The agent is created without it, and it stays listed on the Configure tab (see step 3).
Integrations always start with their read-only tools: a template never lets an agent change data until you tick its write tools yourself.
Then name it:
- Name: what people will call it. "Melissa", "Release notes", "On-call helper".
- Slug: its address, unique within the owner.
- Description: one line, shown in the list. Write it for a colleague who has never seen it.
- Model: a suggestion, which you can change. For a template, it's the cheapest one in the space that suits the role: light work (support, scheduling) gets an inexpensive model, everyday work a mid-range one, and long reasoning (code, contracts) the most capable. A blank agent gets a mid-range one. The list shows roughly what a conversation costs with each, and the suggestion what it saves against the priciest. Costs need prices on your models (Settings → Models).
- Coworkers: other agents of the same owner it can hand work to (Coworkers). Optional, and you can change them later.
- Several conversations: off by default, so each person keeps one conversation with it (see below). Turn it on to let people start new chats.
Every agent can search and read the web wherever its space has those tools on; its Search the web and Read web pages switches on the Configure tab turn that off.

Tick Publish directly to publish version 1 right away and go straight to the chat. Leave it off and the agent starts as a draft: only you can see it, and nobody can chat with it yet. If something blocks publishing (no model it can use, for instance), it is saved as a draft and the Configure tab says what to fix.
3. Give it a role
The Configure tab is where the agent is written. The two text boxes matter most:
- Soul: who it is and how it behaves. Stable, rarely changes.
- Instructions: how it does the job, step by step.
Writing an agent goes into what belongs in each. For now:
Soul. You are a careful release assistant for a small engineering team. You are brief. When you are not sure, you say so rather than guessing.
Instructions. When asked about a release, list what changed, grouped by area, with the risky parts first. Use plain language a non-engineer can follow.
Choose a model from the list. If one is marked unavailable, its key or provider has been turned off.
Rather talk it through?
Leave the soul and instructions empty, choose a model, and publish. Then open Set up by chatting: the agent asks what it's for, who it serves and how it should work, and proposes its own soul and instructions. Nothing changes until you press Apply (or Edit, then apply), which publishes them as the next version. Until then, only its editors can talk to it. If the job should run on its own ("every morning at 8, send me…"), it proposes that task too, to create once the role is applied.
Click the agent's icon, next to its name, to give it another icon and color.
What its template still needs
An agent made from a template lists what the template asked for and the space didn't have, in red, under Abilities and Integrations:
- Set it up takes you to the settings page where it's turned on, if you manage the space (or, for a tool the server doesn't offer, if you administer the server).
- Ask an admin sends the people who can turn it on a notification that links to the agent. Once a day per item is enough.
- Add appears once it's available: it turns the tool on, or adds the integration with its read-only tools. Save or publish as usual. Web search and web fetch need nothing: they come with the agent's web switches once the space has them.
- ✕ means you don't need it: it leaves the list.
Under the model, the Configure tab keeps showing the template's recommendation and what a conversation costs with it.

4. Publish it
Publish (in the bar at the top of Configure, or in the panel beside the settings) takes a snapshot of the draft as version 1. Publishing is what makes an agent usable: before it, nobody can chat with it.
If the button refuses, it tells you exactly what is missing: usually a model.
From here on, people use the published version while you edit the draft. Versions shows the history, and what changed between them.
5. Talk to it
Chat starts a conversation. Its editors find Configure at the top of the chat, beside Memory, to go back to its settings. Once it is published, it also appears in the Chat view (the switch in the top bar), where everyone it's shared with talks to it: their agents and conversations on the left, a message box in the middle, nothing to configure. You will see, as it works:
- the answer streaming in;
- a card for every tool call, with what it sent and what came back;
- a card when it hands work to another agent;
- a marker when it saves something to memory.
If it goes astray, Stop ends the answer and keeps what was written so far.
Long conversations
Under the message box, Context shows how much the agent reads with your next message: the whole conversation, its role and its tools. With the model's context window known (see Models), it's shown as a share, which turns amber past 80%.
Compact summarizes the conversation so the agent reads less: its model writes a summary of everything but the last four messages, and the agent works from that summary from then on. Nothing disappears from what you see; a line marks where the summary ends, and opening it shows the summary. It happens on its own before a message when the conversation is past 80% of the context window, or longer than the 40 messages an agent is sent. The summary costs one model call, counted in usage like any other.
Finding an earlier answer
Search at the top of the Chat view's sidebar (or ⌘K, Ctrl K on Windows and Linux) looks for words in all your conversations, your tasks' included, and in the halls you're in: newest first, with the passage that matched. Every word must be there, and a word matches the start of longer ones (roadm finds "roadmap"). Narrow it to one agent, or to the past week, month or year. A result opens the conversation at that message.
Only what you can already read is searched: never someone else's conversations.

Attaching files
The paperclip beside the message box attaches files; you can also drop them on the box, or paste a screenshot. Up to five per message:
| Kind | What the agent gets |
|---|---|
| Text: notes, logs, CSV, JSON, code | The text, up to about 50,000 characters |
| Its text, read once when you attach it. A scan with no text in it is refused | |
| Images: PNG, JPEG, GIF, WebP, up to 5 MB | The picture, if its model can see images |
The type is read from the file itself, not from its name, so renaming a file doesn't get it past the check. A file longer than the limit is cut, and both you and the agent are told so.
Files stay part of the conversation: the agent re-reads them on every later turn, which costs tokens each time. A picture is the exception: only the latest one is shown again, and older ones are mentioned by name. To start fresh, start a new chat.
Files are as private as the conversation they are in. Whoever can read the conversation can open them; an organization admin who opens one leaves a line in the audit log.
One conversation, or several
An agent keeps a single conversation with each person, unless its editors turn on Several conversations (when creating it, or on its Overview, where it takes effect at once, without publishing). Opening the agent goes straight to your conversation, which carries on; there is no New chat, and a long conversation is compacted as it grows. The same conversation continues by API key and in private chats on Telegram and Slack; group chats and channel threads keep their own. Your interviews to refine its role stay apart. To start afresh, delete the conversation.
Talking instead of typing
When the agent's space has a speech-to-text model, a microphone sits beside the paperclip, and on Chat's home page. Click it, say what you want, and click again to stop: what you said appears in the message box, for you to check and send. The browser asks once for the microphone.
The recording goes to that model and is gone once it's written down; only its cost is kept, like any model call, and budgets apply. Without such a model there is no microphone.

6. Share it
Sharing decides who else can use it. Add a person (or, in an organization, a team) and pick a level:
| Level | They can |
|---|---|
| User | Chat with it |
| Operator | Also read its soul, instructions, memory and versions |
| Editor | Also change it and publish |
| Owner | Also manage sharing, archive and delete |

What next
- It should remember things between conversations → Memory
- It should read a web page, or work with files → Tools
- It should reach Slack, Notion, GitHub… → Integrations
- It should run every morning, or when something happens → Tasks
