# Eggent documentation # Eggent documentation > Eggent is an AI employee with their own computer. This is everything it can do and how to use it — in the cloud, in Telegram and on your own server. Source: https://eggent.ai/docs/ Eggent is a workspace for an AI agent. The agent has a computer of their own: files, a terminal, memory, a schedule, skills and connected services. You describe the job in plain language, the agent does the work there, and the result stays in files and in the chat. There are two ways to use Eggent: - **Eggent Cloud** — a ready workspace at `cloud.eggent.ai`. Nothing to install, an AI model is already connected, and the trial lasts 7 days. - **Your own server** — the open core from [GitHub](https://github.com/eggent-ai/eggent), installed with one command. All data lives in `./data` on your machine. ## Where to start {#start} - [Core concepts](https://eggent.ai/docs/concepts.md): Workspace, orchestrator, project, skill and memory — in five minutes. - [Sign up for the cloud](https://eggent.ai/docs/cloud-signup.md): Create a workspace from the website or from the Telegram bot. - [First steps](https://eggent.ai/docs/first-steps.md): Your first task, the quick-start cards and a few habits that save time. - [Your own server](https://eggent.ai/docs/self-host-install.md): One-command install, Docker and the published image. ## How these docs are organised {#structure} The docs are split into eight sections, from simple to advanced: 1. **Getting started** — what Eggent is and how to begin. 2. **Working with the agent** — chats, projects, the task board, files, voice and images: what you use every day. 3. **Setting up the agent** — models, context, memory, skills and MCP: making the agent yours. 4. **Automation and integrations** — schedules, Telegram and the HTTP API. 5. **Eggent Cloud** — plans, syncing files with your computer, workspace sleep, sign-in and support. 6. **Mac app** — the Eggent app for your own computer: installing it, connecting your cloud workspace and working on your own subscription. 7. **Self-hosting** — installing, configuring and maintaining the open core. 8. **Reference** — agent tools, the HTTP API, the folder layout and fixes for common problems. For a specific question, start with the search box at the top (press `/`) or with [common problems](https://eggent.ai/docs/troubleshooting.md). ## For agents and developers {#agents} Every page is also available as plain Markdown: add `.md` to the address without the trailing slash, for example [`/docs/chats.md`](/docs/chats.md). The list of all pages for language models is at [`/docs/llms.txt`](/docs/llms.txt), and the whole documentation in one file at [`/docs/llms-full.txt`](/docs/llms-full.txt). More on the [For agents](https://eggent.ai/docs/for-agents.md) page. The Russian version of every page has the same address under `/r`: [`/r/docs/`](/r/docs/). --- # Core concepts > The parts Eggent is made of — workspace, orchestrator, projects, chats, skills, memory, context, schedules and models — and how they fit together. Source: https://eggent.ai/docs/concepts/ Eggent is built like an employee's desk. Below is every concept you will meet in the interface and in these docs. If you read one page from start to finish, make it this one. ## Workspace {#workspace} A **workspace** is your whole Eggent: one computer for the agent, with all its projects, files, chats and settings. In the cloud every workspace has its own address, `name.cloud.eggent.ai`. On your own server the workspace is the `./data` folder. Everything the agent does happens inside the workspace. It cannot see other workspaces, and nobody else can see yours. ## Orchestrator {#orchestrator} The **orchestrator** is the agent that answers when no project is selected. It is the workspace's main conversation: good for anything at all, and it knows which projects exist, so it can switch into the right one by itself. The orchestrator has its own context, memory, skills and MCP servers, separate from the projects. Its model is always the workspace model. ## Project {#project} A **project** is a separate desk for one job or area: "Website", "Sales", "Channel content". Every project has its own: - files (the project folder); - context — standing instructions for the agent; - memory; - skills; - MCP servers; - optionally, its own model. When a project is selected, the agent works in its folder and sees only its settings, so instructions for the website do not get in the way of a conversation about accounting. From any chat you can also hand a task to a project by writing `@` and its name. More in [Projects and the orchestrator](https://eggent.ai/docs/projects.md). ## Chat {#chat} A **chat** is one conversation with the agent. A chat belongs to the project it was started in, or to the orchestrator. Every chat has its own address and can be opened from a link, in another tab or from your phone. The work in a chat keeps going if you close the tab. See [Chats](https://eggent.ai/docs/chats.md). ## Context {#context} **Context** is the standing instructions the agent receives with every message: who you are, how to answer, what matters in this project. It lives in `context.md` — one for the orchestrator and one per project. See [Context](https://eggent.ai/docs/context.md). ## Memory {#memory} **Memory** is what the agent wrote down to remember between chats: facts, decisions, preferences. It lives in `memory.md`. The agent searches it when needed, and you can ask it to remember or forget something. The agent also keeps a few short notes about you and the work by itself, and reads them in every chat. See [Memory](https://eggent.ai/docs/memory.md). ## Skill {#skill} A **skill** is a ready-made instruction for one kind of work: how to run a knowledge base, how to write articles for a site, how to fill documents from a template. A skill is a folder with a `SKILL.md` file and, if needed, scripts. The agent picks up the right skill when it sees the task the skill was written for. See [Skills](https://eggent.ai/docs/skills.md) and [Skill catalog](https://eggent.ai/docs/skill-catalog.md). ## MCP {#mcp} **MCP** (Model Context Protocol) is the standard way to connect an external service to the agent: spreadsheets, a CRM, social networks, databases. A connected MCP server gives the agent new tools. See [MCP](https://eggent.ai/docs/mcp.md). ## Model {#model} The **model** is the language model that thinks and writes for the agent. The cloud comes with **Eggent AI** connected — a set of models from several families, paid for from the workspace balance. You can also connect your own key from any provider. The model is chosen for the whole workspace and, separately, per project. See [Models](https://eggent.ai/docs/models.md). ## Schedule {#schedule} A **schedule** is a task the agent runs by itself at a given time: every day at 9:00, every hour, in 10 minutes. You create one by asking in chat, and the result arrives in the same chat or in Telegram. See [Schedules](https://eggent.ai/docs/schedules.md). ## Board {#board} The **board** is where work is handed to the agent as **cards**. Each card is a task the agent carries out by itself in a conversation of its own, one after another; a card can wait for others and start with what they came to: "collect → compare → summarise". See [Task board](https://eggent.ai/docs/board.md). ## How it fits together {#how-it-fits} ```text Workspace (name.cloud.eggent.ai or ./data) ├── Orchestrator ─ context, memory, skills, MCP │ └── chats without a project ├── Project "Website" ─ files, context, memory, skills, MCP, model │ └── project chats ├── Project "Sales" ─ … ├── Schedules ─ live in the chats that created them └── Settings ─ models, Telegram, API ``` A simple rule: **keep everything that belongs to one job in one project.** The agent in a project sees its files, instructions and memory, so you do not have to explain it all again every time. --- # Sign up for Eggent Cloud > How to create your workspace in Eggent Cloud from the website or from the Telegram bot, what the trial includes, and where to find your Eggent afterwards. Source: https://eggent.ai/docs/cloud-signup/ Eggent Cloud is Eggent already deployed for you: no server, no Docker and no model keys. Every workspace runs in its own private container. ## From the website {#web} 1. Open [cloud.eggent.ai](https://cloud.eggent.ai/?lang=en). 2. Pick the language your Eggent will speak. It sets the interface language, the language of the agent's answers and the set of ready-made skills. You can change it later in settings. 3. Fill in the form: - **Workspace name** — becomes your address, for example `acme.cloud.eggent.ai`. At least three characters. - **Email** — this is also your login. - **Password** — at least 8 characters. 4. Press the create button. The workspace is usually ready in under 30 seconds. While it starts, the page asks what to do first: make a document, set up a morning brief in Telegram, compare competitors or make a file in your Google Drive — with one optional line about the task — or "I'll look around myself". 5. Eggent opens already signed in, so you do not type the password twice. If you chose a task, the agent is already working on it in its own project. While the workspace starts, a letter with a 6-digit code comes to your email: type it on the page to confirm the address, or press the button in the letter later. If you ever lose the password, **Forgot your password?** on the sign-in page sends a reset link to that email — see [Forgot the password](https://eggent.ai/docs/account.md#reset). ## From Telegram {#telegram} 1. Open the [@eggentai_bot](https://t.me/eggentai_bot) bot and press **Start**. 2. The bot asks for the workspace name and your email and creates the workspace — there is no password to think up. It answers with a button that opens the workspace signed in, and sends a 6-digit code to your email: send the code to the bot to confirm the address, or `/skip`. 3. From then on, just write to the same bot: it passes your messages to your agent and sends the answers back. While an answer is being written you see a draft and what the agent is doing right now. A workspace created from Telegram is the same as one created on the website. To open it in a browser later, send **`/login`** to the bot: it answers with a button that signs you in. A password of your own can be set in **Settings → General**, or through **Forgot your password?** on the sign-in page. ## What the trial includes {#trial} - **7 days** — then a [plan](https://eggent.ai/docs/plans.md#plans) keeps the workspace running. - **Your own disk** for files — 100 MB during the trial. - **Eggent AI credits** — a model is already connected, no keys needed. Every model in the list is available during the trial. The remaining credits are shown on the billing page and in the sidebar, or just ask the agent: "how much do I have left?". More in [Plans and balance](https://eggent.ai/docs/plans.md). ## Where to find your Eggent later {#address} - **Workspace address**: `https://name.cloud.eggent.ai`. Bookmark it. - **Billing and plan**: `https://cloud.eggent.ai/billing/name`. - **File sync with your computer**: `https://cloud.eggent.ai/sync/name` — see [Files on your computer](https://eggent.ai/docs/file-sync.md). ## Signup limit {#limits} At most two workspaces can be created from one address. If you need more (a team in one office, say), write to [support](https://eggent.ai/docs/account.md#support). --- # First steps > What to do in the first half hour — launch a ready-made skill, give it a real task — and a few habits that make Eggent work better. Source: https://eggent.ai/docs/first-steps/ After signing in you land on the new-chat screen. On the left is the sidebar with projects and chats, in the middle the message box, and the **Files** button on the right opens the file tree. ## The screen in brief {#screen} - **New Chat** — start a new conversation. - **Projects** — the list of projects. The selected project decides which folder and which instructions the agent works with. With no project selected, the **orchestrator** answers. - **Chats** — the conversations of the current project. A dot next to a chat means the agent is still working on it. - **Board** — the task board: work handed to the agent as cards. - **Settings** — models, context, memory, skills, MCP, schedules, messengers and API. - **Files** (button in the header) — the current project's files: upload, open, download. - **Message box** — your message, attachments, voice and the model picker. Under it is the chat mode line. ## Step 1. Start with a card {#about-you} If you chose a first task at signup, the agent is already working on it. Otherwise, the new-chat screen shows quick-start cards, and the first three produce something right away: **Make a document**, **Morning brief in Telegram** and **Build a table from other sites**. All cards are described in the [Skill catalog](https://eggent.ai/docs/skill-catalog.md). If you run a business, try the **Business AI system** card: the agent sorts everything about your business into files, and every chat after that works with the full picture. ## Step 2. Give it a real task {#first-task} Write the way you would write to a colleague — plain words, with details: - "Find five competitors of our coffee shop in Austin, compare their cappuccino prices and make an Excel table with links." - "Here is the contract (attached). List every deadline and penalty." - "Write three versions of a post about opening our new branch, short and without exclamation marks." The agent decides what it needs: search the web, read a file, run code, build a document. Files it produces appear in the **Files** panel, and paths to them in the answer become links. ## Step 3. Make a project for recurring work {#project} If the work will repeat, give it a project: ask in chat "create a project called Channel content", or use a quick-start card — many cards create a project for themselves. Keep everything about that work there from then on: files, instructions, memory, schedules. See [Projects and the orchestrator](https://eggent.ai/docs/projects.md). ## Step 4. Connect Telegram {#telegram} If you signed up through [@eggentai_bot](https://t.me/eggentai_bot), Telegram is already connected. If you signed up on the website, ask the agent to connect Telegram: it gives you a link to the shared bot. Or connect your own bot with the **Your own Telegram bot** card or in **Settings → Messengers**. Then you can write to the agent from your phone with text, voice and files, and it can send results there on a schedule. See [Telegram](https://eggent.ai/docs/telegram.md). ## Habits that make it easier {#habits} - **One topic, one chat.** A long chat about everything is more expensive and more confusing. New task, new chat. - **Standing things go into context, one-off things into the message.** If you keep repeating yourself, ask the agent to write it into the project's context. - **Ask it to remember.** "Remember that I expect reports on Mondays" — and the agent saves it to memory. - **Don't wait at the screen.** You can close the tab or switch chats: the work continues and the result waits in the chat. - **Stop and steer as it goes.** The stop button interrupts the work, and a message sent while the agent is working is taken into the current task. - **Use the light mode for simple questions.** If you only need a conversation with no files or tools, pick "plain chat" in a new chat — it costs many times less. See [Chats](https://eggent.ai/docs/chats.md#modes). --- # Chats > How to work in a conversation with the agent — start a chat, attach files, stop the work or steer it as it goes, answer the agent's questions and pick the mode that saves tokens. Source: https://eggent.ai/docs/chats/ A chat is the main way to work with Eggent. You write a task, the agent does it and shows what it is doing along the way: searching, reading, running commands, writing files. ## New chat {#new} Press **New Chat** in the sidebar. The chat starts in the current project, or with the orchestrator if no project is selected. After the first message the chat gets a title and its own address, `…/dashboard/`: bookmark it, open it in another tab or send it to your phone. All chats of the current project are in the sidebar under **Chats**. To delete a chat, hover over it and press the delete icon. ## Attachments and images {#attachments} - Attach a file with the paperclip button in the message box, or drag it into the window. - A screenshot can be pasted straight from the clipboard (`Ctrl+V` / `Cmd+V`). - Attachments are stored with the chat; the agent gets their path and can read them: text, PDF, Word, Excel, images, audio. If a file is needed by the whole job rather than one chat, upload it to the project through the **Files** panel. See [Files](https://eggent.ai/docs/files.md). ## The file beside the chat {#open-file} When a file is open in the **Files** panel beside the chat, the agent is told which one with your message, so "fix the second paragraph here" means that file. Lines you select in it are sent too, and so is the block you pick on a [page](https://eggent.ai/docs/files.md#pages) with **Select**. A line above the message box says what the agent sees; its cross stops it for that file until you open another one. If the file has edits you have not saved, the agent is told so and asked not to change it under you. When the agent, a restore or the sync changes a file while you are editing it, the panel offers the new version instead of replacing your edits; whichever you keep, the other stays in the [file's history](https://eggent.ai/docs/files.md#history). ## While the agent is working {#while-working} The work belongs to the chat, not to the open tab: - **You can leave.** Close the tab, open another chat, shut the laptop — the agent keeps going. A chat that is still being worked on has a dot next to it in the list. - **You can come back.** Open the chat again and the answer keeps appearing from where it is now, not from the start. - **You can add to it.** Type while the agent works and send: the message goes into the current task, and the agent reads it before its next step. Handy for corrections ("only in Chicago") without stopping the work. Until the agent has read it, it waits under the answer, marked as waiting; once read, it stands in the chat at the point where the agent read it. Several quick messages are read together. A file attached while the agent works goes with the next message, and the agent is told where it is. A command (a message that starts with `/`) can be sent once the work is over. - **You can stop it.** The stop button beside the message box interrupts the work. Everything the agent has done and written so far is kept. A message it had not read yet stays in the chat with a **Send** button. You can also stop with a word: a message that is just "stop", "cancel" or "enough" (including from Telegram). ## When the agent asks {#questions} Sometimes the agent needs a decision from you: which option to take, confirming an action, a value to enter. A card appears in the chat with the question, buttons with ready answers and a field for your own answer. The agent waits and carries on from the same place. It waits up to a day: a question still unanswered after that ends the work, the question stays in the chat, and when you answer it later the agent picks up from there. ## Chat modes {#modes} Under the message box is the mode line. The mode decides how much of the workspace goes into every message, and it is chosen **once, when the chat starts** — it does not change afterwards. Need a different one? Open a new chat. | Mode | What the agent can do | Tokens per message, roughly | | --- | --- | --- | | **full context** (default) | Everything: files, web, commands, images, Telegram, schedules, skills and the workspace instructions | ~12,000 | | **chat + files** | Read files and switch between projects. No writing, commands or web | ~700 | | **plain chat** | Just your question and the chat history. No tools at all | ~250 | The light modes suit questions, translation, talking ideas through and working on a text: they are dozens of times cheaper. Real work with files, the web and documents needs the full mode. > [!NOTE] > The mode stays with the chat wherever the next message comes from, Telegram included. Schedules, cards on the board and the HTTP API always run in full mode. ## Choosing the model in a chat {#model} Left of the send button is the name of the model that will answer the next message. Click it to change the model: inside a project the choice is saved for that project, in the orchestrator for the whole workspace. More in [Models](https://eggent.ai/docs/models.md). ## Links and files in answers {#links} When the agent mentions a file that exists, the path becomes a link: web pages, PDFs and images open in a new tab, anything else on the file's own screen. Audio files play right in the answer. Images the agent embeds in an answer are shown inline. ## Keys and passwords {#secrets} Whatever you send is kept in the chat's history, and the agent sees it. When a message looks like a key, a token, a password or a private key, the chat says so before sending and offers **Send anyway** or **Edit**. A Telegram bot token and a model provider key have their own places — **Settings → Messengers** and **Settings → Models** — and the notice links to them. Credentials are also **masked in stored chats**: after a reload, in the chat list, in what the agent reads when it looks at other chats and in the files that sync to your computer, a key shows as `[hidden key]`. The agent's own working memory of the conversation is not changed, so a key you gave it for a task keeps working. Only well-known shapes are masked (provider and cloud keys, bot tokens, bearer headers, private keys, links with a password in them, and a value kept under a name such as `api_key` or `password` in what the agent sent to a tool); a password inside ordinary text is not. A name written in code, like `api_key = settings.client_key`, is left alone — that is an example, not a key. Chats written before this are cleaned once, the first time the workspace starts after the update. ## Other chats {#other-chats} The agent can look into your other chats: list them, search them and read them. Ask "what did we decide about pricing last week?" or "what did this morning's report say?" and it finds the place. It can also move the conversation: in Telegram, "go back to the chat about the price list" switches there; in the browser it gives you the chat's link. Chats with a clock icon were written by a [scheduled task](https://eggent.ai/docs/schedules.md#results): one chat per task and day. Chats with an arrow are a project's work for another chat, started with `@project` — see [Asking a project](https://eggent.ai/docs/projects.md#ask). ## Tips {#tips} - New task, new chat. A long history makes every next message more expensive and slower. - If the agent heads the wrong way, stop it and say what is wrong — faster than waiting for the end. - Leave long jobs running (visit 50 sites, process a folder of documents): the result will be in the chat and the files in the **Files** panel. --- # Projects and the orchestrator > Why work is split into projects, how to create and switch them, what projects and the orchestrator share, and how the agent finds the right project by itself. Source: https://eggent.ai/docs/projects/ One workspace, many lines of work. To keep them apart each one gets a **project**, and the **orchestrator** sits above them all. ## Orchestrator {#orchestrator} With no project selected in the sidebar, the orchestrator answers. It is the main conversation: - for tasks that do not belong to any project; - for questions like "where did I put…"; - for tasks that touch several projects at once. The orchestrator's context holds what should be known everywhere: who you are, what you do, how you like your answers. The **Business AI system** card writes there. ## Projects {#projects} A project is a folder of files plus the agent's own settings: context, memory, skills, MCP servers and, optionally, a model. When a project is selected, the agent works in its folder and sees only what belongs to it. Good projects are ongoing lines of work: "Website", "Telegram channel content", "Contracts", "Sales analytics", "Studies". A bad project is a one-off question: a chat with the orchestrator is enough for that. ## Create a project {#create} Four ways: 1. **From the sidebar**: the **+** beside the **Project** heading opens a short form: name, description, instructions for the agent. The new project opens with an empty chat, ready to write in. No agent turn is spent on it. 2. **Ask in chat**: "create a project called Contracts for our supply contracts". The agent creates it, can write its instructions right away and switch into it. 3. **Launch a quick-start card.** Most cards create a project for their work and name it after the card. 4. **In settings**: **Settings → Projects**, the same form. ## Switching between projects {#switch} - **By hand**: pick a project in the sidebar. A new chat starts in it. - **By the agent**: the orchestrator knows the project list and, when a message clearly belongs to one of them, switches there and continues. The conversation is not cut off: the chat stays the same and only the working folder changes. To help the orchestrator decide what belongs where, its context has a **Projects in this workspace** table: the project, its id and what it is for. A new project adds its own row. You can edit the table in **Settings → Context** (orchestrator). ## Asking a project from another chat {#ask} Start a message with `@` and a project's name, then say what you want done: > @Shop how many orders came back last week? The project does the work with **its own** files, skills, connected services, instructions and model, in a chat of its own, and the answer comes back to the chat you wrote in. You stay where you are: the active project does not change, and the agent in your chat says the answer comes from the project. - **In the browser**, typing `@` at the start of the box lists your other projects; **Tab** or **Enter** picks one. A message that starts with a project's name is marked, so you can see it was understood. - **In Telegram and through the [external API](https://eggent.ai/docs/external-api.md)** the same message works as typed. - The work is kept in a **chat of the project's own**, titled *From "…"* and marked with an arrow in the project's chat list. The card in your chat has an **Open in …** link to it, with everything the project did. Writing `@Shop` again from the same conversation **continues** that chat, history included. - Names are matched the way you write them: capitals, a hyphen instead of a space and ё instead of е do not matter, so `@my-shop` is "My Shop". If two projects fit equally well, the agent asks which you meant. - **Only you start it.** The agent never asks a project on its own, and a project cannot ask another project. Good to know: - Two projects work at the same time at most; the rest wait their turn. One piece of work is stopped after ten minutes. **Stop** in your chat stops the project too. - A project is a desk, not a locked room: it keeps instructions and files apart but its commands can still reach other places in the workspace. - If the project uses a connected service ([MCP](https://eggent.ai/docs/mcp.md)) that asks for approval the first time, approve it once in the project's own chat: a visit has nobody to ask, and an unapproved service is simply not there. - It is not offered in a [light chat](https://eggent.ai/docs/chats.md#modes) or in a shared public chat, and a message whose name matches no project is an ordinary message. ## Project settings {#settings} Every settings tab where it makes sense (models, context, memory, skills, MCP, schedules) has a switcher in the top right: **orchestrator** or a specific project. Pick a project and the tab shows its settings. | What | Where it lives | More | | --- | --- | --- | | Instructions | the project's `context.md` | [Context](https://eggent.ai/docs/context.md) | | Memory | the project's `memory.md` | [Memory](https://eggent.ai/docs/memory.md) | | Skills | the project's `skills/` folder | [Skills](https://eggent.ai/docs/skills.md) | | External services | the project's `.mcp.json` | [MCP](https://eggent.ai/docs/mcp.md) | | Model | the project's `model.json` | [Models](https://eggent.ai/docs/models.md#project-model) | ## Delete a project {#delete} Hover over the project in the sidebar, open its menu and choose **Delete Project**. The project folder with all its files and its settings are deleted. This cannot be undone — if you need the files, download them first or turn on [sync with your computer](https://eggent.ai/docs/file-sync.md). ## Tips {#tips} - One project, one job. If a project's context grows instructions "for case A" and "for case B", that is two projects. - Keep source material in the project: samples, price lists, examples of good texts. The agent will lean on them. - Just tell the orchestrator: "do this in the Website project". It will switch by itself. --- # Task board > Hand work to the agent as cards. Each card is carried out in a conversation of its own, one after another; cards can wait for each other, and the board tells you when one needs you. Source: https://eggent.ai/docs/board/ The **board** is where you hand work to the agent and leave it. Each piece of work is a **card**: a task the agent carries out by itself, in a conversation of its own, while you do something else. The board shows what is waiting to start, what is being worked on and which cards need you. Open it with **Board** in the sidebar, under New Chat. The number beside it is how many cards are waiting for you; a dot means cards are being worked on. ## Columns {#columns} | Column | What is in it | | --- | --- | | Inbox | Cards written down but not started. Cards the agent proposes always land here and wait for you | | Queue | Cards that start by themselves as soon as there is room, top first | | Working | Cards the agent is working on right now | | Waiting for you | Cards stopped for you: the agent asked a question, the run failed, you stopped it, or the result waits for your check | | Done | Finished cards. The last answer of each is its result | ## Writing a card {#create} **New card**, then: 1. **Title** — a short name. 2. **Task** — what to do, written so it can be done without you: the sources, what the result should look like, where to save it. 3. **Project** — the card runs in that project, with its instructions, skills, memory and files, or in the orchestrator. 4. **Start after** — the cards this one waits for (see below). Optional. 5. **Let me check the result** — the card stops in "Waiting for you" when finished instead of going straight to Done. Optional. **Start now** puts it in the queue; **Save to Inbox** keeps it for later. ## Asking the agent to plan {#from-chat} In any chat: > "Split the competitor study into tasks and put them on the board." The agent writes the cards, chained where one step needs the previous one, into the Inbox. It cannot start them: look them over, change what you want and press **Start all** above the Inbox, or **Start** on one card. ## Cards that wait for each other {#after} A card with **Start after** starts only when every card it waits for is done, and its first message includes what those cards came to: their final answers and the files they made. That is how a chain like "collect → compare → summarise" runs, across projects too: the first card in one project, the next in another. ## Each card is a conversation {#chat} Everything a card's agent did is in the card's conversation: an ordinary chat, marked with the board icon in the chat list. Open it from the card with **Open the conversation**. You can write in it: an answer, a follow-up, a correction. The card follows that turn - it shows as working while it runs and takes its new result when it ends. A line at the top of the chat says which card it is and where it stands. ## When a card needs you {#waiting} - **Question.** When nobody is watching, the agent puts its question on the card and stops there. Answer on the card, with one of its buttons or in your own words: the card goes to the front of the queue and carries on with your answer. **Let the agent decide** carries on without one. - **Failed.** A run that ended with an error is retried once by itself a minute later. If it fails again, the card waits with the error; **Run again** once the cause is fixed. - **Went quiet.** A run that stopped saying anything for too long is stopped, as in a [chat](https://eggent.ai/docs/chats.md#while-working). - **Stopped.** You pressed **Stop**. **Continue** picks up where it stopped. - **Check the result.** The card was written with a check. **Accept as done**, or **Run again**. - **Interrupted.** The workspace restarted in the middle of a run. The board picks such a card up again by itself, twice in a row at most; after that it waits for you. ## When the model service refuses {#paused} If the model service refuses a card's run — the balance is spent, the workspace is closed — the whole board pauses, because every card after it would be refused in turn. Deal with the cause and press **Resume** on the board. ## How many at once {#limits} Up to three cards work at the same time, and one per project: cards of one project share its folder and could overwrite each other's files. Cards of different projects run side by side. On your own server this is set with `EGGENT_BOARD_MAX_RUNNING` and `EGGENT_BOARD_MAX_PER_PROJECT` (see [Configuration](https://eggent.ai/docs/self-host-config.md)). ## Moving cards {#moving} Drag a card between the Inbox and the Queue, or up and down inside them: the queue starts from the top. The same moves are buttons in an opened card - Start, Back to Inbox, Move up, Move down, Put away, Delete. A card being worked on is not moved, only stopped. **Put away** hides a finished card from the Done column; **Show cards put away** under the board brings them back into view. **Delete** removes the card and its conversation; the files it made stay where they are. ## What the agent may do with the board {#agent} The agent reads the board and writes new cards with the `eggent_board` tool. Only you start work: a card the agent writes always waits in the Inbox, and once a card is started its task is no longer the agent's to change. This is deliberate: the agent reads pages, files and messages from outside, and a line in any of them must not be able to put a task with a shell into the queue. ## Pipelines {#pipelines} The board replaces pipelines: a chain of steps is now cards that wait for each other. The old Pipelines page opens the board. --- # What the agent can do > The tools an Eggent agent has — a terminal, Python with document libraries, the web, files, helpers, images, Telegram, schedules — and what it cannot do. Source: https://eggent.ai/docs/capabilities/ An Eggent agent is not just someone to talk to. It has a computer of its own (a Linux container), and nearly anything that can be done on a computer without a mouse it does by itself. ## Files and the terminal {#files-terminal} - **Read, write and edit files** in the project folder: texts, spreadsheets, code, configs. - **Run commands** in a terminal: `bash`, `git`, `curl`, `jq`, `zip`, `ripgrep` and more. - **Write and run programs** in Python and Node.js — for calculations, data processing, conversion. Whatever the agent creates appears in the **Files** panel right away, where you can open or download it. ## Documents {#documents} The libraries most often needed for documents are installed in advance, so the agent has nothing to install: | What | With | | --- | --- | | Excel (`.xlsx`) — read and create | `openpyxl`, `pandas` | | Word (`.docx`) | `python-docx` | | PowerPoint (`.pptx`) | `python-pptx` | | PDF — text and tables | `pypdf`, `PyPDF2`, `pdfplumber`, `poppler-utils` | | Images — crop, compress, convert | `Pillow` | | HTML and XML | `beautifulsoup4`, `lxml` | | Audio and video | `ffmpeg` | | Postgres databases | `psycopg2` | Scans and photos of documents are read with the model's own vision, when the model can look at images. ## The web {#web} - **Search** the web for a query. - **Read pages** from a link, including pulling the text out of articles and documentation. - **Call service APIs** with `curl` or code. The agent reads pages as text. It has no browser with a screen: it cannot press buttons on a site, sign in to accounts or look at how a page renders. ## Helpers {#subagents} A big task can be split between **helpers** — separate agents that each take one part and work at the same time. For example, "make three agents: one reads IT news, one medicine, one cars", or visiting twenty sites a few at a time. Up to six helpers run at once. The agent waits for its helpers: each one reports back, and the agent continues with all of the results and writes the answer in the same reply. While they work, the chat shows every helper on its own row — what it is doing right now, how many steps it has taken and for how long. Open a row to see the task it was given, each search, page and file it went through, and what it found. Stop stops the helpers too. A helper exists only for the task at hand. For an agent that keeps working on a topic, use a [project](https://eggent.ai/docs/projects.md) with a [schedule](https://eggent.ai/docs/schedules.md). To have a project you already have do a piece of work, write `@` and its name at the start of a message: it works with its own files, skills and instructions and the answer comes back to your chat ([how](https://eggent.ai/docs/projects.md#ask)). Schedules are created through the same mechanism as helpers. ## Images {#images} The agent can **draw** images from a description and **edit** existing ones: change the background, make a variant, build a cover from a sample. See [Images](https://eggent.ai/docs/images.md). ## Talking to you {#communication} - **Ask a question** with a card of answer options and a field for your own — when it needs your decision. - **Write to Telegram** — a message or a file to your chat with the bot, or to a channel where the bot is an admin. See [Telegram](https://eggent.ai/docs/telegram.md). - **Remember** what matters in [memory](https://eggent.ai/docs/memory.md) and find it later. ## Managing the workspace {#workspace} When asked in chat, the agent can by itself: - create a project, switch to another project; - write a new [skill](https://eggent.ai/docs/skills.md); - connect an [MCP server](https://eggent.ai/docs/mcp.md); - create, change or delete a [schedule](https://eggent.ai/docs/schedules.md); - put work on the [task board](https://eggent.ai/docs/board.md), as a chain of steps when one needs the previous one; - connect your own model provider or Telegram bot; - tell you how much balance and plan time is left. The full list of tools with their parameters is in the [agent tools reference](https://eggent.ai/docs/agent-tools.md). ## What the agent cannot do {#limits} - **Press buttons on websites** or sign in to accounts: there is no browser with a screen. - **See your computer**: it works only inside its workspace. Upload files to it, or [sync with your computer](https://eggent.ai/docs/file-sync.md). - **Work without a model**: every step costs tokens. Light tasks are cheaper in a [light chat mode](https://eggent.ai/docs/chats.md#modes). - **Guarantee the truth**: the agent can be wrong, like a person. Check figures that go into contracts and reports, and ask it to cite sources. --- # The agent's browser > In Eggent Cloud the agent has a real browser on a machine of its own. It opens sites, clicks, fills in forms and scrolls, while you watch in the Browser panel and take control whenever you need to, for instance to sign in to an account yourself. Source: https://eggent.ai/docs/browser/ Usually the agent reads pages by itself: it fetches them and takes out the text. When that is not enough (a page needs clicks, a form, a sign-in or several steps in a row), the agent has a **real browser**. It runs on a separate Eggent machine, not in your workspace, and the agent drives it the way a person would: it opens an address, presses buttons, types, scrolls. > [!NOTE] > The browser is part of Eggent Cloud. A free install on your own server does not have it. ## When the agent reaches for it {#when} - A page is empty without JavaScript, or shows its content only after a click. - A form has to be filled in, filters chosen, steps followed. - Something has to be looked at or done inside an account. You can also ask outright: "open it in the browser and look at…". Pages the agent could not read the ordinary way are read through the same machine; they count as the plan's [hard pages](https://eggent.ai/docs/plans.md#tools), not as browser minutes. ## The Browser panel {#panel} The globe button in the top right opens the Browser panel. It shows the page the agent is working on, live. Above the picture it says who is in control, below it how many browser minutes are left this month. If the browser is not open, you can open it yourself with **Open the browser**, for instance to sign in to a site before the agent needs it. ## Taking control {#control} Press **Take control** and the browser is yours: click, scroll and type on the picture, from a phone too. The agent waits and does nothing meanwhile. When you are done, press **Hand back to the agent**. While you have control, an address bar with **Back**, **Forward** and **Reload** sits above the picture: type an address and press Enter to open a page yourself. Only web pages open there, and an address typed without `https://` is taken as one. A browser you open yourself with **Open the browser** starts with control in your hands and the cursor in the address bar. That is how the steps a person has to take get done: - **Signing in.** You type the password yourself, in the panel. Never write a password in the chat; the agent will not ask for one. - **A code from a text message or an email.** - **A captcha.** ## Sign-ins are kept {#sign-ins} The browser remembers the sites you signed in to, and next time the agent gets there already signed in as you. Sign-ins are kept on the browser's machine, separately for each workspace. **Forget sign-ins** (the arrow button in the panel's header) closes the browser and erases every sign-in it kept. ## Minutes {#minutes} The browser is counted in minutes while it is open. How many minutes a month you have depends on the plan: the billing page lists them, and the trial has a few to try it. How many are left this month is shown in the panel; they start again on the first of the month. The agent closes the browser when the task is done; a browser nobody uses for a few minutes closes by itself. You can close it too, with **Close the browser**. In a company everybody shares the administrator's minutes, and every place bought on top adds more. ## Good to know {#good-to-know} - The browser does not run from Russia. Some Russian sites that are closed to foreign addresses will not let it in. - Sites with strong protection against robots may show a captcha; you pass it after taking control. - The agent does not see the values of password fields. - A screenshot the agent takes is saved as a file in the project, in the [Files panel](https://eggent.ai/docs/files.md#panel). --- # Files > Where workspace files live, how to upload them (whole folders included), open, download and delete them, see a web page as it looks and change its words, save a file as PDF, how every change is kept as a version you can compare and restore, what the limits are, and how the agent shows files in its answers. Source: https://eggent.ai/docs/files/ Every project has its own folder of files. The agent works right in it: it reads what you uploaded and puts what it made there. ## The Files panel {#panel} The **Files** button in the header opens the file tree to the right of the chat. It shows the folder of the current project (or of the orchestrator) and stays open as you move between screens. On a phone the panel opens over the chat. In the tree: - **the open file is highlighted**, along with the current folder; - **folders** expand on click and stay expanded when you move to another chat or screen; - every folder has buttons: **upload files**, **upload folder**, **download as .zip**, **new file**, **new folder**; the top row (`/`) downloads the whole workspace folder; - every file has **open**, **download** and **delete**. Clicking a file opens it **in the same panel, beside the chat**, so the conversation stays in view: text and code can be read and edited in an editor with line numbers and highlighting (**Save** or Cmd/Ctrl+S), a web page seen as it looks (see [Pages](#pages)), an image viewed, audio played. The panel widens for the file — drag its left edge to change the width, which is remembered. The arrow takes you back to the tree, and **Open full page** shows the file on its own screen. A file path the agent names in an answer, and a file in the list under an answer, open the same way; Cmd/Ctrl-click opens the full page in a new tab. ## Uploading {#upload} - **Files** — with the button on the folder you want, or by dropping them onto a folder. - **A whole folder** — with "upload folder": the whole structure of nested folders comes across, as on your computer. Folder picking is available in desktop browsers; on an iPhone the button picks files. - **Into a chat** — message attachments are stored with the chat. If a file is needed for the whole job rather than one conversation, upload it to the project. If a file with the same name already exists, Eggent asks whether to replace it. > [!NOTE] > One upload carries at most **100 MB**. Large folders are sent in several parts automatically, so the limit only applies to the size of a single file. ## Open and download {#open} - **Open** — web pages (`.html`), PDFs and images open rendered in a new tab. Handy when the agent has built a site or a report: you can look at it straight away. The page opens isolated and has no access to your workspace. - **Download** — any file downloads with the download button. Names in any language are kept. ## Pages {#pages} A web page (`.html`) opens **as it looks**, with its styles and pictures from the folder beside it; **Code** switches to its source. The page is shown isolated: its scripts run, but they cannot reach your workspace or send anything anywhere. - **Select** lets you point at the page: a click picks a block, and the agent beside the chat sees exactly that piece of the file — so "make this heading shorter" means that heading. **Show in code** finds it in the source. - **A double click changes the words** of a block right on the page; Enter saves, Esc cancels. Only those words change in the file — everything else stays as it was, byte for byte — and the change is a version in the [file's history](#history). Anything else (a new block, a style) is for the agent or the code. - If the file changed while the page was open, the page is shown afresh and nothing is written. ## Save as PDF {#pdf} The printer button beside a file opens a copy made for paper and the browser's print dialog: choose **Save as PDF**. A web page prints as it looks on screen: what appears as you scroll is shown, animations are stopped, a header that stays on screen is let go so that it does not cover every page, backgrounds are kept, and a block is not cut across two pages where that can be avoided. Markdown prints as a document, other text as it is. ## Sharing and approval {#company} In a workspace that belongs to a [company](https://eggent.ai/docs/company.md), a file's panel and page have two more buttons: **Share** gives the file to colleagues to read, comment on or change ([Shared files](https://eggent.ai/docs/company.md#shares)), and **Approval** sends the version it holds now to colleagues for approval, in order ([Approvals](https://eggent.ai/docs/company.md#approvals)). A line above the file says when it is shared or on approval. ## A folder as one .zip {#zip} The archive button on a folder (and on the top row, which stands for the whole project) downloads it as a single `.zip`: structure, Russian and other-language names and the executable bit are kept. The archive is built as it is sent, so a large folder does not load the workspace. - Files that hold secrets are **left out**: `.env` files, `.mcp.json`, `auth.json`, key and certificate files (`.pem`, `.key`, `.p12`), cloud credentials (`credentials.json`, service-account keys, `kubeconfig`, `*.tfvars`) and folders made to hold them (`.ssh`, `.aws`, `.kube`) — also when you name such a folder yourself. After a download from an answer's card the page says how many were left out. - So are dependencies and the agent's own working state (`node_modules`, `.git`, `.venv`, `.pi`). Links are never followed out of the folder, a file that also has another name somewhere else is left out, and a file that disappears or is swapped for a link while the archive is being sent is skipped rather than ending the download. - The limit is **1 GB and 10 000 files** per archive; above that the button says so and you download parts of it. One archive is prepared at a time, so a second one asks you to try again in a moment. ## Files in the agent's answers {#in-answers} When the agent mentions a file that exists, the path becomes a link — no need to hunt for it in the tree. Audio files (`mp3`, `ogg`, `wav`, `m4a` and others) play right in the answer: a play button, the duration and progress. Images the agent embeds in an answer are shown in the chat. ### The files an answer made {#produced} When an answer made files, they are listed under it: the files it names, the files its tools wrote, and — when it ran commands and nothing else points at a result — what is new in the folder. Each row has **open** (for pages, PDFs and images), **download**, and, when Telegram is connected, **send to Telegram**, which sends the file to your own chat. With more than five files the rest are counted and **Download all as .zip** takes the lot. The list is deliberately cautious: only plain files written during that answer, inside the folder it worked in, never the agent's own notes, skills or tools, never files that hold secrets. If a file is deleted later, its row disappears. Edits to files that already existed are listed only when the answer names them. What a project made for an [`@project` request](https://eggent.ai/docs/projects.md#ask) is listed under the answer of the chat that asked. ## File history {#history} Every change to a document or text file in a project is kept as a version, whoever made it: you saving it in the editor, the agent writing it or running a command that rewrites it, an upload that replaces it, or the sync bringing a copy edited on your computer. A history begins with a file's first change — what the file held just before it is kept too; a file that has only been created or uploaded has nothing to go back to yet and takes no extra space. The clock button in the header of an open file (**History** on the file's own page) lists the versions, newest first, each with who made it: *You*, *The agent* with the chat it was working in, *Uploaded*, *Changed outside the editor* (the sync, the terminal or another program). - **Compare.** Choose a version to see what changed from the one before it, or compare it with the file as it is now, or with any other version. **Text** shows the newer wording with the older words struck through, the way an edited document reads; **Lines** shows the older lines over the newer ones, numbered, which suits code. Unchanged parts are folded away, and the arrows (or Alt+↑ / Alt+↓) go from one change to the next. - **Restore.** **Restore** brings a version back. What the file held before is kept as well, so a restore can itself be undone. The exception is a file that has since grown past 10 MB or cannot be read: the list says so above the versions, and a restore asks first, because what it replaces cannot be kept. - **Download** saves any version as a file named after it, for example `contract (v3).docx`. Documents (`.docx`, `.xlsx`, `.pptx`, `.odt`) are compared by the text inside them: paragraphs, table rows, slides, the rows of a sheet. Formatting is not compared. Pictures, recordings, archives and PDFs get no history, and neither do the agent's own notes and skills, dependency folders, files that hold secrets, or a company's shared folders (those are the company's files, not the workspace's). Every version is kept for 30 days after a newer one replaced it, then one a day up to 90 days, at most 200 per file. The history counts toward the workspace's disk and never takes more than a quarter of it: past that, the versions replaced longest ago go first, and when the disk is nearly full the history shrinks to make room for the files themselves. **Settings → General → File history** shows how much it takes, clears what is older than a week or all of it, and turns it off. A file's own history can be deleted from its list. The agent reads the history too: ask it what changed in a document since yesterday, or to go back to an earlier version. When a file is open beside the chat, the agent knows which one you mean — see [Chats](https://eggent.ai/docs/chats.md#open-file). ## Deleting {#delete} The delete button on a file or folder deletes it after you confirm. Deleting a folder deletes everything in it. A file deleted here takes [its history](#history) with it. With [sync with your computer](https://eggent.ai/docs/file-sync.md) turned on, deleted files are kept in the sync trash for 30 days. ## Disk space {#storage} In the cloud a workspace has a limited disk: 100 MB during the trial, more on a plan. [File history](#history) counts toward it as well. When the disk is three-quarters full, a warning appears in the sidebar. When it is completely full, the agent stops answering, but the **Files** panel keeps working — delete what you do not need and work continues from the next message. More in [Plans and balance](https://eggent.ai/docs/plans.md#storage). On your own server the only limit is the machine's disk. ## Where the files physically live {#layout} | What | Path inside the workspace | | --- | --- | | Project files | `data/projects//` | | Orchestrator files | `data/projects/` (beside the project folders) | | Chat attachments | `data/chat-files//` | | Versions of files | `data/versions/` | The full layout is in [Workspace layout](https://eggent.ai/docs/workspace-layout.md). --- # Working in a company > A company is a group of workspaces, one per person, run by an administrator. Its people write to each other, share files with each other to read, comment on or change, and send versions of files for approval in order - with their agents' help. Source: https://eggent.ai/docs/company/ In Eggent Cloud a workspace can become a **company**: the administrator's workspace plus one workspace for each person in it. Everyone keeps their own agent, files and chats. What the company adds is a way to work together: messages between people, files shared with each other, and approval of documents. > [!NOTE] > Companies are being opened gradually. To make your workspace a company, write to support. What is included, how it is paid for and how to start: [Eggent Business](https://eggent.ai/docs/business.md). ## The administrator and the people {#people} The administrator runs the company from the **Company** item of the floating button in the corner of the screen: - **People.** Each person gets a workspace of their own and a one-time sign-in link (valid for 72 hours, it works once). The administrator can send a new link or set a new password. - **Money.** The people's work with the agent is paid from the company's balance. Monthly limits can be set for each person and for each team; when one is reached, that person's agent stops until next month or until the limit is raised. The disk is shared too: people's files count against the administrator's plan. How many people a plan includes is on the [Eggent Business](https://eggent.ai/docs/business.md#price) page. - **Teams** group people, for limits and for folders. - **Company folders** are shared disks: a folder is given to one person, a team or everyone, to read or to read and write, and appears in their workspace under `.shared/`. Folders are the company's files and get no [history](https://eggent.ai/docs/files.md#history). The administrator's agent can do the same by request - create a person, send a sign-in link, reset a password - and can read people's chats to prepare a report. Every such read is recorded, and each person's agent knows it may happen. Deleting a person, a folder or the whole company is done only in the console. ## Messages {#messages} **Messages** in the sidebar holds a thread with each person: the administrator writes to each person, and each person to the administrator. - Write and attach files. Files from a thread are copied into the **Messages** folder of both workspaces, under the other person's name, so the agent can read them. - **Reply** answers a message with a quote. - **Hand to the agent** opens a chat with your agent about the message: the agent reads it as material, prepares an answer, and **Send to …** under its answer sends it - with the answer's files if you want them. Nothing is sent until you press it. - A new message is announced in Telegram through Eggent's bot, if you are connected to it. A reply to that notice in Telegram goes into the thread. Your agent can write to colleagues too: "tell Peter the meeting moved to 10" is sent to Peter, marked as written by the agent. ## Shared files {#shares} Any file of your workspace can be shared with people of the company. The file stays where it is: they see it as it is in your workspace, with every change you save. **Share** beside a file - in the [Files panel](https://eggent.ai/docs/files.md#panel) or on the file's page - lists who has it and what each may do: - **Can view** - look at it and download it; - **Can comment** - also leave comments; - **Can edit** - also change it. Add people with their buttons, choose a role and press **Share** (later **Save**); each newcomer hears of it in Telegram. A line above a shared file says who sees it. **Stop sharing** takes it from everyone and deletes its comments. ### Files shared with you {#shared-with-you} **Shared** in the sidebar lists the files colleagues shared with you (**New** marks something changed or commented since you last opened it) and the files you shared. A shared file opens on its own page: - a web page as it looks, or its code ([Pages](https://eggent.ai/docs/files.md#pages)); text and code; the words of a document (`.docx`, `.xlsx`, `.pptx`); a picture; - **Download** and **Save as PDF** ([PDF](https://eggent.ai/docs/files.md#pdf)); - the comments beside it. ### Comments {#comments} A comment is about the whole file or about one piece of it: pick a block on the page with **Select**, or select lines in the code, and the comment keeps that piece with it as it read then. Comments can be answered. Its author or the file's owner marks a thread resolved (**Resolve**) and can delete it. The owner hears of every comment in Telegram, and the author of a thread of every reply. ### Changing a colleague's file {#edit} With **Can edit**, change the words right on the page (double-click a block, Enter saves) or the code, then **Save**. The change is written into the owner's file, and only onto the version you opened: if the file changed in the meantime, nothing is written and you are offered the new version to make your change there. For the owner nothing is lost. Before anybody may change a file, what it holds is kept in its history, and each colleague's change becomes a version signed with their name - "Peter, through sharing" - that can be compared and restored like any other ([File history](https://eggent.ai/docs/files.md#history)). A change also voids an approval of the file, as any change does. Files that hold credentials (`.env`, keys and the like) are never shared. A shared file can be up to 20 MB; a change made from the screen, up to 5 MB. ## Approvals {#approvals} An approval is a strict yes to **one version** of a file. 1. **Approval** beside a file: choose who approves it, **in order**, add a note and press **Send for approval**. The version the file holds now goes out and is kept in its history under its number. 2. The first person decides: **Approve** or **Return for changes** with a comment saying what to change. The next person is asked only after the one before approves. 3. When everyone approves, the version is approved. **Any change to the file voids it** - while it goes round and after it was approved. Change the file and send the new version: the chain starts over from the first person. Approvals are never carried from one version to the next. **Approvals** in the sidebar has three boxes: **Waiting for you**, **Sent by you** and **Asked before**. An approval's page shows the chain with decisions and comments, what changed since the previous version, the whole text, and the file to download. The author can **Withdraw** a version. Everyone involved hears of their turn, a return, the final approval and a change of the file in Telegram. A file sent for approval can be up to 20 MB, and a chain up to 10 people. ## Projects for your people {#projects} The administrator can open one of their projects to the company's people - to everyone, to a team or to named people. It appears under **Projects** in each of their workspaces, with a building mark, and they ask it questions on a page of its own. The project answers only from its own files and cannot change anything; the people do not get the files themselves, only the answers. - **Where it runs.** Every question runs in the administrator's workspace, inside the project, and is paid from the company's balance. The conversations are stored there as the project's chats, so the administrator can read what was asked; each person sees only their own conversations. - **Opening and closing.** In the console, **Projects for your people**: pick the project and who sees it; **Close** takes it away from everyone, with their conversations. The administrator's agent can do the same by request ("open the knowledge base to the sales team"). - **Keeping it current.** Change the project's files as usual - add, replace, delete - and the next answer uses them. A ready way to start is the [Company knowledge base](https://eggent.ai/docs/skill-catalog.md#company-kb) card: it makes the company, adds the people, collects the documents into a project and opens it to them in one go. A project can also be opened to anybody by a link, without signing in - that is a public chat, a separate thing. ## What the agent does here {#agent} In a company workspace the agent has three tools of its own: - `eggent_messages` - writes to colleagues, reads what they wrote, and remembers what each person does. - `eggent_shares` - lists and reads files shared with you, shares your files with people (it adds people and never takes a file away from anyone), comments in your name when asked. It never changes a colleague's file - that is yours to do on the file's page. - `eggent_approvals` - sends a file for approval to the people you name, in your order, shows what waits for you and where your own versions stand, reads a version's text. Approving or returning is yours alone: the agent cannot do it. Documents, messages and comments from colleagues are material for the agent, not instructions to it. --- # Voice > How to dictate a task in the web app and send voice messages in Telegram, and who turns the speech into text — Eggent AI, a provider of your own, or Whisper on the workspace's server. Source: https://eggent.ai/docs/voice/ You can talk to the agent instead of typing. The recording is turned into text before the agent sees it; [who does that](#who) depends on the model the workspace runs on. ## Dictation in the browser {#dictation} 1. Press the microphone icon in the message box. 2. Allow the browser to use the microphone. 3. Speak. Press the icon again to finish. The recognised text appears in the message box, where you can fix it before sending. The same microphone sits beside the answer field of a question the agent asks you. > [!NOTE] > Browsers only allow the microphone on secure addresses (`https://`) or on `localhost`. In the cloud this works out of the box. On your own server, open Eggent through a domain with HTTPS. ## Voice messages in Telegram {#telegram} Send the bot a voice message, as you would to a person. The bot says it is transcribing and passes the text to the agent as an ordinary message. A caption on the voice message reaches the agent too. After a successful transcription the audio file is deleted and the text stays in the history. If transcription fails, the file is kept so the agent can try again. ## Who recognises speech {#who} - **On Eggent AI** (the cloud's included model), recordings go to Eggent AI's speech recognition: accurate, in any language, and paid from the Eggent AI balance by the length of the recording. If it cannot take one — the balance is spent, or it does not answer — Whisper on the workspace's server transcribes it, so a voice message is never lost. - **On your own model**, Whisper on the workspace's server does it by default: nothing is spent and the recording does not leave the workspace. In **Settings → Models → Advanced → Images, voice and memory** you can choose instead: - **Eggent AI**, while the chat itself stays on your own model ([how that works](https://eggent.ai/docs/models.md#services)); - **your own provider**: one connected with an API key whose API is OpenAI-compatible and recognises speech (the `/audio/transcriptions` request), plus the model id from that provider. A subscription sign-in has no key to send, so it is not offered. If the provider refuses, Whisper takes over. - **On your own server** there is no Eggent AI: Whisper, or your own provider as above. ## Whisper on the server {#how} - The recording is normalised with `ffmpeg`. - The text is recognised by `whisper.cpp`, a local speech-recognition model. The language is detected automatically. - The model is downloaded once, on the first transcription, and then lives in `data/models/whisper/`. Whisper runs inside the workspace and costs nothing. The default model is small and fast; on your own server a larger one is more accurate (`EGGENT_STT_MODEL` below). ## Settings on your own server {#self-host} | Variable | Default | What it does | | --- | --- | --- | | `EGGENT_STT_ENABLED` | `1` | Turns speech recognition on | | `EGGENT_STT_MODEL` | `base` | Model: `tiny`, `base`, `small`, `medium`. Larger is more accurate and slower | | `EGGENT_STT_LANGUAGE` | `auto` | The spoken language, or auto-detect | | `EGGENT_STT_AUTO_DOWNLOAD_MODEL` | `1` | Download the model on first use | More in [Configuring your server](https://eggent.ai/docs/self-host-config.md). --- # Images > How to ask the agent to draw an image or edit one of yours — from a sample, in the right aspect ratio and quality — and what it costs. Source: https://eggent.ai/docs/images/ The agent can create new images from a description and change existing ones: remove or replace a background, make a variant in another style, build a cover from a sample. ## How to ask {#ask} Describe what you need, as you would to a designer: - "Draw a cover for a post about our autumn sale: a coffee shop, warm light, room for a headline at the top, 4:5." - "Here is a product photo (attached). Replace the background with white and make it a 1:1 square." - "Make three pixel-art logo options, transparent background." The more precise the description (what is shown, style, colours, format, what to keep from the sample), the fewer attempts it takes. ## Reference images {#references} Attach one or more images to the message, or point to a file in the project. The agent passes them on as a reference: you can ask it to keep the composition, the colours, a face or a product and change the rest. ## Options {#options} | Option | Values | Note | | --- | --- | --- | | Aspect ratio | `1:1`, `16:9`, `9:16`, `4:3`, `4:5` and others | For posts, stories, covers | | Size | `1K`, `2K`, `4K`, or exact, like `1024x1024` | | | Quality | `low`, `medium` (default), `high` | `high` costs several times more | | Format | `png`, `jpeg`, `webp` | | | Background | normal or transparent | Transparent for logos and icons | | Count | how many variants at once | Each variant is paid for separately | Saying the options in plain words is fine and encouraged: "vertical for stories", "high quality", "transparent background". ## Where the result goes {#result} Finished images are saved to the `generated-images/` folder of the current project and show up in the **Files** panel right away. The agent shows their paths in the answer, and you can open or download them. Ask, and it sends an image to Telegram or posts it to a channel. ## Cost {#cost} - In the cloud, images are drawn by **Eggent Images**. Every plan [includes some images a month](https://eggent.ai/docs/plans.md#tools) that are not taken from the balance; the billing page says how many. Past them an image is paid from the Eggent AI balance: the price depends mostly on quality, and the agent sees what each image cost and can tell you. - The trial includes **two** images; more need a plan. - If the workspace runs on [your own key](https://eggent.ai/docs/models.md#own-provider), images are off until you choose in **Settings → Models → Advanced → Images, voice and memory**: Eggent AI, paid from its balance as above, or a provider of your own, connected with an API key ([more](https://eggent.ai/docs/models.md#services)). --- # Models > Which model answers for the agent, how to change it for the whole workspace or one project, what Eggent AI is, how to connect your own key from any provider and how to switch back. Source: https://eggent.ai/docs/models/ The model is the agent's brain: it reads your task, decides which tools to call and writes the answer. The model decides the quality, speed and cost of the work. ## Eggent AI {#eggent-ai} The cloud comes with **Eggent AI** connected — a catalog of models from several families: GPT, Claude, Gemini, DeepSeek, GLM, Kimi. No keys needed: every model is paid for from one workspace balance. - Prices are per million tokens, separately for input, cached input and output. The price table is on the billing page and in **Settings → Models**. - Prices are based on the model makers' published prices, so you can check them. - Cheaper models make the balance last longer; stronger ones handle hard work better. The same job can run on different models in different projects. Every model in the list is available, on the trial as well. If an installation restricts part of the list, the rest is visible but disabled, with a note on how to open it. See [Plans and balance](https://eggent.ai/docs/plans.md). ## Changing the model {#change} **Quickly, right in the chat.** Left of the send button is the model's name. Click it, find a model with the search and pick it. Models are grouped by family. - Inside a project, the choice is saved **for that project**. - In the orchestrator, **for the whole workspace** and every project without its own model. The line shows which model will answer **the next** message. **In settings.** **Settings → Models** → **Workspace model**: provider and model. Under **Advanced** are the thinking level (how much the model reasons before answering), image generation and editing `models.json` by hand. ## A project's model {#project-model} A project can have a model of its own: a cheap one for bulk work, a strong one where it pays off. In **Settings → Models**, switch the scope in the top right to the project and choose: - **the workspace model** — the project answers with the same model as the orchestrator; - **its own model** — from the providers that can answer right now. While the workspace runs on Eggent AI, a project chooses among Eggent AI models. If a project's saved model cannot be used (its provider was disconnected, say), the project quietly answers with the workspace model. ## Your own provider {#own-provider} You can work on your own key — OpenAI, Anthropic, Google, OpenRouter, DeepSeek or any service with an OpenAI-compatible API, including your own local model on your own server. Requests then go straight to the provider at its prices, and the Eggent AI balance is not spent. 1. **Settings → Models → Use my own provider.** 2. Pick the provider. 3. Paste the API key and press **Save key**. Some providers offer sign-in with a subscription instead of a key. 4. Pick the model. Eggent tells you which model the workspace now answers with. > [!WARNING] > Paste keys into settings, not into the chat. A key saved in settings is kept in a protected file and never enters the conversation history. **A provider that is not on the list** is easiest to add through the agent: write "connect the provider at `https://…/v1` with the model `…`". The agent registers it, and you paste the key in settings. The other way is **Advanced → Custom providers and models**, where `models.json` is edited. If a key does not work or an address is unreachable, Eggent says exactly what is wrong: the address does not answer, the key was rejected, or the provider has no such model. ## On this computer {#on-this-computer} In the [Eggent app for Mac](https://eggent.ai/docs/desktop-app.md), a project can also run on **Claude Code** or **Codex** already installed on the computer, with your own subscription instead of a model: see [Working on your own subscription](https://eggent.ai/docs/desktop-programs.md). ## Images, voice and memory {#services} While the workspace runs on Eggent AI, it also draws [images](https://eggent.ai/docs/images.md), turns [voice](https://eggent.ai/docs/voice.md) into text and runs the short look-back after a reply that keeps [what the agent learns](https://eggent.ai/docs/memory.md#learned). When you move to your own provider, all three stop using Eggent AI, so nothing more is spent from its balance: - images are off until you choose who draws them; - voice is transcribed by Whisper on the workspace's own server; - the look-back runs on the chat's own model. In **Settings → Models → Advanced → Images, voice and memory** you can turn Eggent AI back on for any one of them — keep your own model for the chat and Eggent AI for voice, say — or point images and voice at a provider of your own. That has to be a provider connected with an API key: a subscription sign-in has no key to send. Leaving Eggent AI again turns it off for all three, and a project that was put on an Eggent AI model follows your new model. Its last choice is remembered in the project's model settings, so putting it back is two clicks. ## Back to Eggent AI {#back} In **Settings → Models**, press **Use Eggent AI again**. No key needed, it is one click, and images, voice and the look-back go through it again. Your own providers' keys are kept, so you can go back to them too. ## Your own server {#self-host} The open core has no Eggent AI: on first launch connect a provider in settings or set a key in an environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY`). See [Configuring your server](https://eggent.ai/docs/self-host-config.md). --- # Context > The standing instructions the agent receives with every message — what to put in them, where to edit them and why to keep them short. Source: https://eggent.ai/docs/context/ **Context** is what the agent always knows without asking: who you are, what this project is, how to answer. It lives in a `context.md` file and is added to every message. ## Where to edit it {#where} **Settings → Context.** In the top right, pick the orchestrator or a project: each has its own `context.md`. Changes apply from the next message, including in chats that are already open. You can skip the settings too: ask the agent in chat — "add to the project context that we write plainly and without jargon". ## What goes into the orchestrator's context {#orchestrator} What should be known in every chat: - who you are and what you do; - how you like your answers (short or detailed, lists or prose, which language); - the project table — which project handles what, so the orchestrator switches into the right one by itself. The **Business AI system** card fills this context for you. ## What goes into a project's context {#project} What this job needs and nothing else does: - the project's goal and who the result is for; - rules and style: tone of the texts, report format, required sections; - where things are in the project folder: "samples are in `samples/`, finished work goes to `out/`"; - what must never be done. Example: ```markdown # Content for the "Neighbourhood Coffee" channel We write posts for the Telegram channel of a coffee chain in Austin. Audience: locals, 25–45. - Friendly tone, no exclamation marks. - A post is up to 600 characters and ends with one question to the reader. - Photos come from `photos/`; finished posts go to `posts/YYYY-MM-DD.md`. - Never mention prices: they change. ``` ## Keep the context short {#keep-short} The context goes **into every message** of every chat it applies to, and is paid for every time. So: - write rules and pointers, not the material itself. Not "here is the whole price list" but "the price list is in `price.xlsx`"; - put large reference data into the project as files: the agent reads them when needed; - let what the agent learns along the way live in [memory](https://eggent.ai/docs/memory.md), not in the context. ## Context, memory and skills: what goes where {#what-where} | What | Where | | --- | --- | | A rule that always applies | Context | | A fact that may come in handy some day | [Memory](https://eggent.ai/docs/memory.md) | | Instructions for one kind of work | [Skill](https://eggent.ai/docs/skills.md) | | A large reference document | A file in the project | --- # Memory > How the agent remembers facts between chats — the notebook it searches, the short notes and skills it learns by itself, how to ask it to remember or forget, and where to see and edit all of it. Source: https://eggent.ai/docs/memory/ **Memory** is the agent's notebook. Unlike [context](https://eggent.ai/docs/context.md), it is not sent whole with every message: the agent searches it when needed, so it can hold lots of small facts. ## How it works {#how} - The agent **saves** to memory what will be useful later: your decisions, preferences, agreements, facts it found. - When a task may relate to something from before, the agent **searches** memory for it. - The agent **deletes** outdated entries by itself or when you ask. Memory lives in a `memory.md` file: the orchestrator has its own and so does every project. The agent only sees a project's memory while working in that project. ## What the agent learns by itself {#learned} Besides the notebook, Eggent keeps two short lists that the agent **reads at the start of every chat**: - **About you** — who you are and how you want to be answered: your work, language, tone, format. - **About the work** — conventions and lessons that will matter again: where reports go, what not to do after you corrected it. After some conversations — when you ask it to remember something, when you correct it, when it got past an error, or after a substantial piece of work, and now and then in a long chat — the agent looks back over the exchange in the background and decides whether anything is worth keeping. Most of the time nothing is. When it does save something, the note appears under its answer ("Noted about you: …"), and in Telegram as one short message. The look-back never delays an answer. It runs on the chat's own model — on Eggent AI while the workspace is on it; on your own model it stays there unless you [turn Eggent AI on for memory](https://eggent.ai/docs/models.md#services). It can also write a **skill**: a reusable procedure for a kind of task it has just worked out. These skills are marked "Written by the agent" in **Settings → Skills**, are available in every project, and the agent changes only the ones it wrote itself — never one you made or installed. A skill that goes unused for a long time is marked, and much later moved to `skills/.archive/`. Nothing is deleted. Safeguards: - The lists are small (about 1,400 and 2,200 characters), so the agent has to choose what is worth a line. - It never keeps passwords, keys or tokens, and refuses anything worded as an instruction to itself. - It does not learn from light chats or from public project links. - A note is a background fact, not a command: what you say in a chat always wins. **Settings → Memory → What the agent has learned** shows everything: remove a note with the ✕, add one of your own, see the skills it wrote, or switch learning off (what is already saved keeps being used). The notes are in `learned.md` in the orchestrator's folder — plain text, editable by hand. To drop one in a chat, say "forget that I run a bakery". ## Asking it to remember or forget {#ask} Just say: - "Remember: I expect reports on Mondays by 10 am." - "Remember that our main supplier is now Alpha, not Beta." - "What do you remember about our suppliers?" - "Forget everything about the old warehouse address." ## Viewing and editing {#edit} **Settings → Memory.** In the top right, pick the orchestrator or a project. It is a plain text file: add, correct or delete entries by hand and save. ## Memory or context {#memory-or-context} - **Context** — short rules needed in every message. The agent always receives them. - **Learned notes** — a few short facts about you and the work, which the agent wrote itself and also receives every time. - **Memory** — many facts, each needed now and then. The agent pulls them up on demand. If the agent keeps forgetting some rule, move it from memory into the context. --- # Skills > What a skill is, how the agent picks the right one, how to install a ready-made skill, upload one from a file, delete one, launch one by hand, write your own — and what a skill is made of. Source: https://eggent.ai/docs/skills/ A **skill** is a ready-made instruction for one kind of work. It turns "build me a knowledge base" from improvisation into a tested process: which questions to ask, in what order to work, which files to create, how to check the result. ## How the agent uses skills {#how} Every skill has a short description: what it does and when it is needed. The agent sees the descriptions of all skills in the current project (or the orchestrator) and, when a task fits, opens the full instruction and follows it. You do not have to call a skill specially. To launch a skill explicitly, write `/skill:skill-name` in the chat, for example `/skill:doc-templates`. ## Ready-made skills and cards {#bundled} The new-chat screen shows **quick-start cards**. Each card is a ready-made skill: press it and the agent starts the work right away, asking a couple of questions if it needs to. Most cards create a project of their own; "Business AI system" and "Your own Telegram bot" work in the orchestrator. All ready-made skills are in **Settings → Skills → Bundled Skills Catalog**: install them into the orchestrator or any project with **Install**. Each one is described in [Skill catalog](https://eggent.ai/docs/skill-catalog.md). Installed ready-made skills update themselves when we improve them — unless you have changed them by hand. Eggent leaves an edited copy alone. ## Uploading a skill from a file {#upload} If you already have a skill as a file — one you wrote yourself, got from a colleague or downloaded — put it into the workspace without the agent: **Settings → Skills → Upload skill**. Choose the orchestrator or a project at the top right (the skill is installed wherever the selector points), then drag files onto the dashed area, or press it and pick them. Several files can go at once; each gets its own answer. What can be uploaded: - a **`.md` file** — a `SKILL.md` that starts with a YAML header holding `name` and `description`; - a **`.zip` or `.skill` archive** — the skill's folder, with `SKILL.md` at the top of the archive or inside one folder, and whatever else the skill needs: `scripts/`, `references/`, `assets/` or any other folders. (A `.skill` file is the same ZIP archive under another name.) The file is checked before anything is saved. If a check fails, nothing is installed and nothing stays on disk, and the answer says what is wrong and where — that `SKILL.md` is not found (and where it was found instead), that the header is not valid YAML on line 3, that the name is not allowed, that an entry in the archive is a link or climbs out of the skill's folder. What is checked: - `SKILL.md` exists, is UTF-8 text and starts with a YAML header; `name` is lowercase letters, digits and single hyphens (up to 64 characters), and `description` is not empty (up to 1024); - file names stay inside the skill's folder, there are no links or special files, and the archive has no password; - the upload is at most 30 MB, and the skill at most 600 files and 30 MB unpacked. The check is about structure. What a script does is not checked, and the agent can run a skill's scripts, so upload only skills you trust. If a skill with that name is already installed, it is not overwritten: the answer says so and offers **Replace**. Replacing puts the new skill in place and moves the old folder to `skills/.replaced/` instead of deleting it, so what you added to it by hand is not lost. To get rid of the old one instead, delete it first (see [Installed skills](#installed)). A skill the agent wrote itself carries the line `origin: learned` in its header. When you upload such a skill — say, one downloaded from another workspace — the line is removed and you are told: from then on the skill is yours, and the agent will not change it. ## Installed skills {#installed} **Settings → Skills** lists the skills installed in the selected scope (orchestrator or project). Click a skill to read its instruction. A skill works only where it is installed. An orchestrator skill is not visible in projects, and the other way round — except skills the agent wrote itself, which are available everywhere (see [Skills the agent writes itself](#learned)). To remove a skill, press the trash icon at the end of its row and confirm. The skill's folder is deleted with everything in it, together with any earlier versions kept when a replacement put them aside (`skills/.replaced/`). This cannot be undone: a skill that exists only here is gone for good. A skill from the catalog can be installed again, and one you uploaded can be uploaded again. Deleting also frees the name, which is the way out when an upload says that a skill with that name is already installed and you do not want to replace it. ## Skills the agent writes itself {#learned} After a job that took real work — an error it got past, a procedure you corrected — the agent may save the procedure as a skill, without being asked. It shows under the answer ("Learned a new skill: …"), carries the mark "Written by the agent" in **Settings → Skills**, and lives in the orchestrator's `skills/` like any other. Details and safeguards: [Memory](https://eggent.ai/docs/memory.md#learned). The agent improves only the skills it wrote itself. A skill you made or installed is never changed by it. To keep one of the agent's skills as your own, edit it by hand and delete the line `origin: learned` from its header — from then on the agent leaves it alone. A learned skill that stays unused for a long time is marked "Not used for a while", and later moved to `skills/.archive/`; move the folder back to bring it back. You can also delete a learned skill from the list like any other; the agent may write it again if the same kind of work comes up. ## Writing your own skill {#create} The easiest way is to ask the agent: > "Make a skill for the weekly sales report: take the export from `sales/`, total revenue by category, compare with last week and write a three-paragraph summary plus a table." The agent creates the skill in the current project. A good moment for this is right after you have done the job properly together once: ask "turn what we just did into a skill". ## What a skill is made of {#structure} A skill is a folder in the project's (or the orchestrator's) `skills/`: ```text skills/ └── weekly-sales-report/ ├── SKILL.md # the instruction ├── scripts/ # scripts, if needed └── references/ # samples and reference material ``` `SKILL.md` starts with a YAML header: ```markdown --- name: weekly-sales-report description: Weekly sales report from the export in sales/. Use when asked for a sales report for the week. --- # Weekly sales report 1. Find the latest export in `sales/`. 2. … ``` - `name` — the skill's name, lowercase with hyphens, same as the folder name. - `description` — what the skill does and **when** to use it. The agent decides whether the skill fits from this description, so make it specific. ## Tips {#tips} - One skill, one kind of work. A skill "for everything" gets applied where it does not belong. - Write steps and a definition of done in the skill, not general wishes. - If the skill relies on samples, put them in the skill's folder, not in the context. --- # Skill catalog > Every quick-start card in Eggent Cloud — what each one does, what to bring to it, where it works and what you get at the end. Source: https://eggent.ai/docs/skill-catalog/ The quick-start cards are ready-made skills built from what people most often come to Eggent for. Press a card on the new-chat screen and the agent starts the work. Below are all the cards in the order they appear on screen. > [!NOTE] > The cards are part of Eggent Cloud. The open core has the same mechanism but ships no skill set: your own skills go into the `bundled-skills/` folder. ## Your Google: docs, sheets, slides {#your-google} **Works in:** its own project. **In:** Eggent Cloud. Say what you need - "a budget for the renovation", "slides about our product", "a plan for the week". The agent connects your Google account (one button, access only to the files Eggent makes) and makes a real Google Doc, Sheet or Slides in your Drive, then sends the link and changes it as you ask. More in [Google](https://eggent.ai/docs/google.md). ## Watch listings, prices and tenders {#site-monitor} **Works in:** its own project. Send a link to a search - flats, cars, vacancies, prices, public tenders - or describe what to look for. The agent writes a small script for that site, runs it at once to show what is there now, connects Telegram and puts the script on a schedule. After that you hear only about what is new; a check with nothing new stays silent. If the site changes and the script stops finding anything, the agent says so and offers to fix it. More in [Schedules](https://eggent.ai/docs/schedules.md#quiet). ## Make a document {#first-document} **Works in:** its own project. One sentence is enough: "a pitch deck for my studio, 8 slides", "a one-page report on the competitors", "a proposal for an office renovation". The agent builds the whole file first — a PowerPoint deck or a Word document — and only then asks what to change. Anything it does not know, such as your prices or client names, it leaves as a visible placeholder in square brackets instead of inventing it. New versions are saved beside the old ones. ## Company knowledge base {#company-kb} **Works in:** the orchestrator, and a project of its own for the documents. For a team that keeps asking the same questions. The agent asks who should be able to ask and where the documents are, then does the rest: makes your company if there is none, gives each person a workspace and a sign-in link, puts the documents into a project «Company knowledge base» and opens it to them. Each of them then asks it from their own workspace and gets answers from the files only. To update the base, change the project's files. More in [Working in a company](https://eggent.ai/docs/company.md#projects). ## Morning brief in Telegram {#daily-digest} **Works in:** its own project. Name a topic and a time — "property market news in my city, at 9:00", "the euro, oil and bitcoin, at 8:00". The agent connects Telegram first (if you signed up on the website, it gives you a link to the bot: open it and press **Start**), sends one real issue right away so you can adjust it, and only then puts it on a daily schedule. Each issue is 5–7 short items with links, and nothing repeats from the previous days. More in [Telegram](https://eggent.ai/docs/telegram.md#shared-bot). ## A letter from your agent {#email-digest} **Works in:** its own project. Name a topic - "AI for small business", "property in my city", or "a fact, a book and an idea for the week". The agent writes to your email from its own address: one real letter right away so you can adjust it, then the next ones on a schedule, nothing repeated from earlier letters. On the trial it suggests once or twice a week, because a plan's letters are counted. More in [The agent's email](https://eggent.ai/docs/email.md#to-you). ## Build a table from other sites {#rival-table} **Works in:** its own project. Give it a list: products, competitors, listings, channels. The agent visits the sources, pulls the same fields for each item and hands back an Excel table with a source link on every row. It does **three rows first** so you can agree the columns. If it could not find a value, the cell stays empty: a plausible invented price is worse than a gap. ## Articles for your site {#site-articles} **Works in:** its own project. The agent studies your site — its tone, structure and link format — and writes that into a site profile. Then it drafts a keyword list and an article plan and writes **one article for approval first**; after you approve it, the rest. Each article comes ready for the CMS, with a meta description, a preview and image descriptions. The agent does not invent facts it was not given: it marks those places "to confirm". ## Documents from a template {#doc-templates} **Works in:** its own project. Give it a sample of a document you make again and again: a contract, an invoice, an act, a protocol, a form. The agent finds what changes in it, builds a template and then fills new documents from your answers or in bulk from a table. The sample's formatting is kept exactly: fonts, tables, headers and footers. Amounts in words, formatted dates and item rows are filled in automatically. The agent will not hand over a document with a required field left empty. The result is Word or Excel; save a PDF from Word. ## Your own Telegram bot {#telegram-bot} **Works in:** the orchestrator. Connects a bot of your own so you can write to the workspace from Telegram with text, voice and files. The agent explains how to create a bot with @BotFather, asks you to paste the token on the **Messengers** page (not into the chat), checks the connection and gives out one-time access codes for you and your colleagues. The bot answers only in private messages and only to people you let in. More in [Telegram](https://eggent.ai/docs/telegram.md#own-bot). ## Business AI system {#business-system} **Works in:** the orchestrator. Tell it about your business once — products, customers, processes, team — and the agent sorts it into files in a `system/` folder, one per area. Only a short "what is where" table goes into the orchestrator's context, so messages do not get more expensive, while any chat can open the file it needs. You can give it up to five sources at once: a website, a deck, documents. ## RAG over your own files {#rag} **Works in:** its own project. Builds a vector base over your documents so the agent answers from them, with sources. The vectors are stored in **your own** Postgres database with the pgvector extension: the agent asks for a connection string, creates the table and index itself and updates the base when the files in the folder change. Eggent provides the embedding model, so no separate key is needed. ## Wiki LLM from your notes {#wiki} **Works in:** its own project. Turns a pile of notes, exports and documents into a linked knowledge base: separate pages by topic, links between them, an index and a change log. From then on, new material goes into a folder and the agent works it into the wiki and keeps it up to date. ## Daily posts for VK and Telegram {#social-daily} **Works in:** its own project. Russian set only. Connects your VK community and Telegram channel and then writes and publishes one post with a picture every day. The order is strict: connect a channel and publish one real post first, then write content, and only then set the schedule. VK needs a community access key with wall and photo permissions; the agent explains where to get it. ## Design your site or interface {#designer} **Works in:** its own project. Three questions — what it is, what the visitor should do, how it should feel — and the agent produces a brief, a design system and a real page in the `site/` folder. Before you see it, the page goes through a review of six areas: accessibility, layout, writing, typography, colour, motion. For viewing, the agent bundles the page into a single `preview.html`, which opens with the **Open** button in the Files panel. After that, ask for changes, pass after pass. ## Add to my calendar {#add-to-calendar} **Works in:** its own project. A meeting, a booking, a deadline or a reminder goes into your own calendar in one tap: the agent makes a calendar file for Apple Calendar, Google Calendar or Outlook and a link that adds the event to Google Calendar. Nothing to connect. More in [Google](https://eggent.ai/docs/google.md#calendar). --- # MCP > How to connect external services to the agent over the Model Context Protocol — by asking the agent or editing .mcp.json by hand, which kinds of servers exist and how to keep their keys. Source: https://eggent.ai/docs/mcp/ **MCP** (Model Context Protocol) is an open standard through which external services give the agent their tools: spreadsheets, CRMs, task trackers, databases, social networks, exchanges. Connect an MCP server and the agent gains new actions, such as "create a task in the tracker" or "read rows from the sheet". ## Where it applies {#scope} MCP servers, like skills, are connected to the orchestrator or to a specific project. A project's server is available to the agent only in that project. The settings are stored in a `.mcp.json` file in the project's (or the orchestrator's) folder. ## Connect through the agent {#via-agent} The easiest way is to ask in chat, saying what the server is: > "Connect the Notion MCP server. Launch: `npx -y @notionhq/notion-mcp-server`, I will paste the token myself." > "Connect the MCP at `https://mcp.example.com/mcp` with the header `Authorization: Bearer …`." The agent adds the server to the current project's `.mcp.json`, and its tools are available right away, in the same conversation. > [!WARNING] > Service tokens and keys end up in `.mcp.json`. That file is not synced to your computer, but a key pasted into a message stays in the chat history. Better to type the secret into **Settings → MCP** yourself. ## Connect by hand {#manual} **Settings → MCP.** In the top right, pick the orchestrator or a project. The screen shows the connected servers and, below them, the `.mcp.json` file itself for editing. After editing, press **Save .mcp.json**. The format is the same as in Cursor and Claude Desktop: ```json { "mcpServers": { "notion": { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "NOTION_TOKEN": "secret_…" } }, "tracker": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer …" } } } } ``` ## Two kinds of servers {#types} | Kind | Set with | Where it runs | | --- | --- | --- | | **Local (stdio)** | `command`, `args`, `env` | Started inside the workspace as a program, usually with `npx` or `uvx` | | **Remote (HTTP)** | `url`, `headers` | Runs at the service's side; the agent reaches it over the network | If a service offers both, the remote one is usually simpler: nothing to install. ## How the agent uses MCP {#usage} The agent sees the connected servers and their tools and calls them when the task needs it. You can point it there explicitly: "use the tracker MCP to see my tasks for today". ## If it does not work {#troubleshooting} - Ask the agent: "check the tracker MCP server" — it will show the start-up or response error. - For a local server, check that the command runs: the package exists and the Node or Python version fits. - For a remote one, check the address and the authorization header. - If the cloud workspace was [asleep](https://eggent.ai/docs/sleep.md), the first call to a local server can take a few extra seconds while it starts. --- # Schedules > How to hand the agent recurring work — daily digests, posts, checks — how to change or cancel a task, where the results go and what to know about time and reliability. Source: https://eggent.ai/docs/schedules/ A **schedule** is a task the agent runs by itself, without you: every morning, every hour, on a given day, or once after some time. ## Create one {#create} Ask in chat, in plain words, answering three questions: **what to do, when, and where to send the result**. - "Every weekday at 9:00 New York time, gather news about our market from these five sources and send me the top five as a list in Telegram." - "Every Monday at 10:00, make a sales report from the latest export in `sales/` and save it to `reports/`." - "In 20 minutes, remind me to call the supplier." The agent turns this into a schedule, confirms when the first run will be, and every run then happens in the same project where you asked. ## Where the results go {#results} - Every run reports into **a chat of its own**, named after the task and the day: `Morning review · Oct 1`. Runs of one task on the same day share that chat. In the sidebar these chats have a clock icon; the chat where you set the task up stays an ordinary conversation. - If you asked, also **in Telegram** (the connected bot) or in a channel. The report says which chat it comes from, and answering it — or just writing next — continues that chat, with the report in it. See [Telegram](https://eggent.ai/docs/telegram.md#which-chat). - Files the task makes are in the project, in the **Files** panel. ## Checks that stay quiet {#quiet} A task that checks something often - new listings, a price, a tender search - finds nothing new most of the time. Such a task can stay silent: when a run has nothing to report, nothing is sent to Telegram, and its chat gets one line saying there was nothing new. The **Watch listings, prices and tenders** card sets its task up this way. There is no limit on how many scheduled tasks a workspace keeps. ## View, change, cancel {#manage} **Settings → Schedules** lists every task in the selected scope: what it does, its schedule, the next and last run, how many times it ran and whether it is enabled. You can also **pause** and **resume** a task, **delete** it or **change its time** here. The easiest way is through the chat: - "Show my schedules." - "Move the morning digest to 8:30." - "Make the digest include the dollar rate too" — you can change what a task does, not only when. - "Cancel the supplier reminder." - "Pause the digest until I am back from holiday" and, later, "resume the digest" — a paused task stays in the list and does not run. If the task lives in another project or chat, the agent finds it. ## A task that cannot run {#paused} Sometimes a run cannot be carried out: the model's limit for the workspace is reached, or the disk is full. Left alone, such a task would be turned away every time it fires, and tell you so every time. So Eggent counts: - **The first refusal** reaches you as the run's report, with the reason and what to do. - **The next ones** are kept in the task's chat for that day and are not sent to Telegram again. - **On the third in a row** the task is **paused**: you get one message saying so, with the reason, and the task shows **paused by Eggent** in **Settings → Schedules**. A run that ends in an error is counted the same way, a little more patiently: it is announced once, and after five in a row the task is paused too. A good run clears the count. Once the reason is dealt with, **resume** the task in **Settings → Schedules**, or ask the agent: "resume the morning digest". Nothing is deleted by a pause, and the count starts again after a resume. A scheduled run's own report cannot create, change or delete tasks. Nobody is there to ask, so only you can — in a chat of your own or in **Settings → Schedules**. ## How time is written {#format} The agent understands time in words and stores it in one of these formats: | Format | Example | Means | | --- | --- | --- | | cron | `0 9 * * 1-5` | at 9:00 on weekdays | | interval | `30m`, `1h` | every 30 minutes, every hour | | delay | `+20m` | once, in 20 minutes | | date and time | `2026-10-01T09:00` | once, at that moment | > [!WARNING] > Time follows the server's clock, which in the cloud is usually UTC. Say your time zone ("at 9:00 London time") or write it into your [context](https://eggent.ai/docs/context.md) once, and check the next run time in **Settings → Schedules**. ## Reliability {#reliability} - **The cloud wakes the workspace for a run.** Even if the workspace has gone to sleep, it wakes a couple of minutes before the task. See [Sleep and wake](https://eggent.ai/docs/sleep.md). - **Missed runs are not repeated.** If the workspace was off at the moment (your own server was rebooting, say), the task runs at its next scheduled time. - **A task spends balance** like an ordinary message. Frequent tasks on a strong model use noticeable credits: for routine work pick a cheaper model in the [project settings](https://eggent.ai/docs/models.md#project-model). - **A task runs alone.** Nobody is there to answer a question during a run, so word the task so the agent has nothing to clarify. --- # Telegram > How to work with Eggent from Telegram — through the cloud's shared bot or your own bot, how to let colleagues in, what you can send, and how the agent writes to you and posts to channels. Source: https://eggent.ai/docs/telegram/ You can work with Eggent from Telegram just as from the browser: write tasks in text or by voice, send files, get answers and schedule results. Chats from Telegram are visible in the web app too. ## Two ways to connect {#ways} | | The cloud's shared bot | Your own bot | | --- | --- | --- | | What | [@eggentai_bot](https://t.me/eggentai_bot) | A bot you created with @BotFather | | Available in | Eggent Cloud only | Cloud and your own server | | Setup | Sign up through the bot, or open the link the agent gives you | Token in **Settings → Messengers** | | Who can write | You | You and the people you let in | | Posting to channels | No | Yes, if the bot is a channel admin | ## The cloud's shared bot {#shared-bot} If you signed up through [@eggentai_bot](https://t.me/eggentai_bot), it is already linked to your workspace. Just write to it. **`/login`** there answers with a button that opens the workspace in a browser already signed in. If you signed up on the website, ask the agent to connect Telegram (the **Morning brief in Telegram** card does it as its first step). It gives you a link to the bot: open it in Telegram and press **Start**, and the chat is linked to your workspace. The link works once and for 30 minutes. If this Telegram account is already linked to another workspace, the bot asks you to open the link a second time to move it. While the agent works you see a draft in the chat: first what the agent is busy with ("Thinking…", "Searching the web", "Reading a file"), then the answer as it is written. The finished answer arrives as a normal message. ## Your own bot {#own-bot} The easiest way is the **Your own Telegram bot** card on the new-chat screen: the agent walks you through it. By hand: 1. In Telegram, open [@BotFather](https://t.me/BotFather), send `/newbot`, choose a name and username and copy the token. 2. In Eggent, open **Settings → Messengers**. 3. In **1. Bot Token**, paste the token and press **Activate Bot**. 4. Eggent picks the connection mode. In the cloud it works right away; on your own server without a public HTTPS address it uses **Long Polling**. 5. Open your bot in Telegram and press **Start**. > [!WARNING] > Paste the token into settings, not into the chat with the agent. The token gives full control of the bot, and a message stays in the history. ## Who can write to your bot {#access} The bot answers only people on its allowlist. To let someone in (yourself included, the first time): 1. In **Settings → Messengers → Access Control**, press **Generate Access Code**. Or ask the agent: "give me an access code for a colleague". 2. The person opens the bot and sends `/code `. 3. The code works once. After it the person is on the allowlist. The `user_id` list can be edited by hand in the same block. > [!WARNING] > Everyone you let in works with **the same workspace**: they see its files and can give the agent any task. Let in only people you trust. The bot is not meant for talking to customers. ## What you can send {#messages} - **Text** — as in the web chat. - **Voice messages** — transcribed inside the workspace and passed to the agent as text. See [Voice](https://eggent.ai/docs/voice.md). - **Files and photos** — saved to the chat's attachments; the agent sees them. A caption goes in as the message. - **Files** — an answer that made files says so at the end. Send `/files` to get them in this chat: up to three go one by one, more come as one archive. - **`@project task`** — a message that starts with `@` and a project's name hands the task to that project; its answer comes back here and you stay in the same chat. See [Projects](https://eggent.ai/docs/projects.md#ask). - **"stop"**, "cancel", "enough" — on its own, stops the current work. Any other message sent during work is taken into the current task. They reach the work at once, even if it has been going for a long time: they do not wait for it to finish. Bot commands: | Command | What it does | | --- | --- | | `/start`, `/help` | Help and connection status | | `/code ` | Get access with a code | | `/new` | Start a new conversation from scratch | | `/chats` | Recent chats, each with a command that continues it | | `/reset` | Stops an answer that seems stuck. The conversation is kept: write again to carry on | | `/files` | Sends the files the last answer made | The bot works **only in private messages**. It does not answer in groups. ## Which chat a message goes to {#which-chat} Telegram is one thread, while the workspace keeps many chats. Where your message lands: - **A reply** (Reply on a message from the bot) continues the chat that message came from: this morning's report, or an answer from last week. Telegram shows the quoted message, and the agent gets it too. - **Any other message** continues the chat that wrote to you last. When a scheduled report arrives, your next message is about the report and goes to its chat. - **When the conversation moves**, the message says where: its last line is `💬` and the chat's name. - **`/chats`** lists the recent chats. Tap the `/c_…` command under one to continue it there. `/new` starts a fresh chat. The work a project did for another chat is marked ↪️. - **Or ask the agent**: "go back to the chat about the price list", "what did yesterday's report say?". It can find, read and switch between chats. A chat keeps its project: when the conversation moves into a chat from a project, the next messages run in that project. ## The agent writes on its own {#outbound} Ask, and the agent sends a message or a file to Telegram: the result of a long task, a reminder, a scheduled report. Images go as photos with a caption, everything else as documents. A scheduled report comes from the task's own chat and says so in its last line, so answering it continues the report. See [Schedules](https://eggent.ai/docs/schedules.md#results). ## Posting to a channel {#channels} Your own bot can post to a channel: 1. Add the bot to the channel as an **administrator** allowed to post messages. 2. Ask the agent: "post this with the picture to @mychannel". This works in a schedule too: "every day at 10:00 post to @mychannel from the content plan". ## An answer that seems stuck {#stuck} While the agent works, the draft shows what it is doing. If nothing happens for a minute and a half, the draft says it is still going and how to stop it: send **`/reset`**. That stops the work, drops a question it was waiting on, and keeps the conversation and everything already done; write again to carry on. You do not have to notice: Eggent stops a turn that has gone completely quiet by itself — after about 3 minutes while it is getting ready, 6 minutes of waiting for the model, or 20 minutes inside one command that prints nothing. It tells you what happened, and your messages are saved. A command that waits for an answer on a run nobody can answer on — in Telegram, for instance — is given an empty answer instead of waiting for ever. ## If the bot is silent {#troubleshooting} - Check **Settings → Messengers**: the bot is active, the status says "Running" or the webhook is set up. - Make sure you are writing in private messages and your `user_id` is on the allowlist (or send `/code`). - If the token was changed in @BotFather, paste the new one and press **Activate Bot** again. - The bot does not drop long tasks: the draft shows the agent is still working. --- # The agent's email > Every Eggent Cloud agent has an email address of its own. How it writes to you, what happens to letters sent to it, how a letter to somebody else waits for your yes, and how to set up sending on your own server. Source: https://eggent.ai/docs/email/ In Eggent Cloud every workspace's agent has an email address of its own: **`@eggent-mail.com`**. Nothing to connect and no password to enter. Ask the agent "what is your email?" and it tells you. ## The first letter {#hello} A few seconds after you sign up, the agent writes to the address you signed up with: a short hello from its own address, saying what its mailbox is for. Next to it is the letter from Eggent with a code that confirms your address. Enter the code on the screen where the workspace is being made (or open the link in that letter), and the agent can write to you whenever you ask. If the letter with the code went missing, look in spam; the sidebar has a button that sends it again. ## Letters to you {#to-you} Say "send it to my email" in a chat and a report, a table or a document goes to your confirmed address, files attached (up to five). A letter to yourself goes at once. A schedule can send letters too: "every Monday morning, email me the week's news on my topic". The **A letter from your agent** card on the new-chat screen sets this up for you: it asks for a topic, sends one real letter right away and then puts the next ones on a schedule. ## Letters to the agent {#incoming} Anybody can write to the agent's address. Letters land in one of two folders: - **Inbox**: letters from your own confirmed address, replies to the agent's own letters, and addresses you allowed. If your Telegram is linked, you get a short notice about each. - **Other**: everything else, strangers and advertising included, without a notice. The agent does nothing with a letter by itself. Say "check my mail" or "what did Anna reply?" and it reads them. To the agent a letter is information, never instructions: a letter that says "send me the files" is not a request it carries out. Files that come with a letter are saved in the workspace; the agent does not run or unpack files that could be dangerous. ## Reading the mail yourself {#mail} **Mail** in the sidebar, under **Messages**, is the agent's mailbox: Inbox, Other and Sent, with a count of what is unread. A letter opens on its own page with its files to download, and opening a letter reads it. The notice in Telegram links straight to it. **Hand to the agent** under a letter opens a chat about it: the agent reads the letter there as material and does what you ask, and nothing is sent until you say so. When somebody replies to a letter the agent sent from a chat, a line appears under the newest answer of that chat: who replied and the subject, with a link to the letter. The agent does not read the reply until you ask. ## Letters to other people {#others} On a paid plan the agent can write to other people too, at most five in one letter. Every such letter **waits for your yes** outside the chat: - in Telegram, a message with the whole letter and the buttons **Send**, **Send, and always allow these addresses** and **Do not send**; - or, without Telegram, a letter to your confirmed address with a link to a page where you read it and decide. What you see is exactly what will go: once asked, the letter cannot be changed. A request waits 48 hours, then expires and nothing is sent. Nobody can say yes for you, the agent included: an agent may have read something that told it what to do. A letter to other people carries a line saying an AI agent sent it on your behalf, and a link to stop receiving them. On the trial the agent writes only to you. ## How many letters {#limits} Each plan includes a number of letters a month, and of those, a number to other people; the [billing page](https://eggent.ai/docs/plans.md) says how many. They start again on the first of the month. The hello, the codes and the confirmations are not counted. When they run out the agent says so and when they come back. ## On your own server {#self-host} A self-hosted Eggent has no mailbox of its own, but the agent can send through your mail server: | Variable | What it is | | --- | --- | | `EGGENT_SMTP_URL` | `smtp://user:password@host:587` or `smtps://…` | | `EGGENT_EMAIL_FROM` | The address letters come from | | `EGGENT_EMAIL_OWNER` | Your own address, for "send it to me" | A letter to anybody but you waits for your yes in the chat. Nothing is received there. The agent can read these variables, so this yes keeps an honest agent honest rather than stopping a hostile one; give it a mail account you would trust it with. --- # Google > Connect your Google account in Eggent Cloud and the agent makes real Google Docs, Sheets and Slides in your Drive. What it can reach, what waits for your yes, and how to put an event into your calendar. Source: https://eggent.ai/docs/google/ In Eggent Cloud the agent can work in your Google account: it makes real Google Docs, Sheets and Slides in your Drive and sends you the link. ## Connect {#connect} The quickest way is the **Your Google: docs, sheets, slides** card on the new-chat screen: say what you need ("a budget for the renovation", "slides about our product") and the agent asks you to connect, then makes the file. You can also connect any time: - in a chat, ask the agent to do something in Google: it shows a **Connect Google** button under its answer; - or in **Settings → General**, the Google card. Google asks you to sign in and to allow access to **the files Eggent creates**. That is the whole permission: the agent does not see the rest of your Drive, your mail or your contacts. When an account is connected, you get a notice in Telegram (if linked) and a letter to your confirmed address, with a link to disconnect it if it was not you. Disconnect any time in **Settings → General**. ## What the agent can do {#what} - **Documents**: write a new one (headings, lists, tables, bold), read it back, add to the end, replace words. - **Sheets**: make a table with formulas, read it, change cells, add rows. - **Slides**: make a presentation from a list of slides, read one. - **Drive**: list the files it made, put a file from the workspace into Drive (as it is, or converted to a Doc, Sheet or Slides), bring a Drive file into the project (as PDF, DOCX, XLSX and the like), make folders and move files into them. Every answer about a file carries its link. The agent never deletes a file, never gives a person or a group access, and never changes an owner. ## What waits for your yes {#yes} **Opening a file to anyone with its link** always waits for you, the same way a [letter to other people](https://eggent.ai/docs/email.md#others) does: a message in Telegram with **Allow** and **Decline**, or, without Telegram, a letter to your confirmed address with a link to a page where you decide. The request waits 48 hours. Nobody can say yes for you, the agent included. ## Calendar {#calendar} Every workspace, Google or not, can put an event into your calendar: ask "add tomorrow's meeting at 15:00 to my calendar" and the agent makes a calendar file (`.ics`) that opens in Apple Calendar, Google Calendar or Outlook, and a link that adds it to Google Calendar in one tap. The **Add to my calendar** card does the same. It reaches you in the chat, in Telegram or by [email](https://eggent.ai/docs/email.md#to-you). ## On your own server {#self-host} The Google connection is part of Eggent Cloud. A self-hosted Eggent makes calendar files the same way, and can reach Google through an [MCP server](https://eggent.ai/docs/mcp.md) of your choice. --- # HTTP API for integrations > How to connect Eggent to your site, CRM, bot or automation — get a token, send a message, pass a file, stream the answer and keep the conversation between calls. Source: https://eggent.ai/docs/external-api/ The **external API** lets another program give the agent a task: your site's backend, a CRM, n8n or Make, your own bot, a background job. You send a message, Eggent runs it like an ordinary chat and returns the answer. ## Base URL {#base-url} | Where Eggent runs | Base URL | | --- | --- | | Cloud | `https://name.cloud.eggent.ai` | | Your own server | the address Eggent opens at, for example `https://eggent.example.com` | ## Get a token {#token} 1. Open **Settings → API**. 2. Generate an external API token. 3. Store it in your system as a secret. The token goes in the `Authorization: Bearer ` header. Never put it in code that runs in a browser: with it anyone can give the agent any task. On your own server you can set `EXTERNAL_API_TOKEN` instead of generating one; a token from settings takes precedence. ## Send a message {#message} ```http POST /api/external/message Authorization: Bearer Content-Type: application/json ``` ```bash curl -X POST https://name.cloud.eggent.ai/api/external/message \ -H "Authorization: Bearer $EGGENT_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "crm:client-42", "projectName": "Sales", "message": "Write a short follow-up email based on the latest notes" }' ``` ### Request fields {#request} | Field | Required | What it is | | --- | --- | --- | | `sessionId` | yes | A stable conversation key. One per user, thread, customer or job | | `message` | yes | The task text, non-empty | | `projectId` | no | Project id (or an exact name, if unique) | | `projectName` | no | Exact project name | | `chatId` | no | An existing chat. Usually not needed | | `currentPath` | no | A working-folder hint for file tasks | With no project, the message goes to the orchestrator. ### Response {#response} ```json { "success": true, "sessionId": "crm:client-42", "reply": "Hi Anna! …", "context": { "activeProjectId": "sales", "activeProjectName": "Sales", "activeChatId": "0a2f…", "activeChatTitle": "Call with Anna", "currentPath": "" }, "chatChanged": false, "switchedProject": null, "createdProject": null } ``` If the agent switched or created a project during the run, you see it in `switchedProject` and `createdProject`. `chatChanged` is `true` when the conversation is now in a different chat than before this message — the agent moved it — and `activeChatTitle` names that chat. ## How sessionId works {#session} For each `sessionId`, Eggent remembers the current project, the current chat and the working folder. Reuse the same `sessionId` and the agent continues the same conversation, with its history. A new `sessionId` is a new conversation. Good keys: `telegram:`, `crm:`, `slack::`, `job:daily-report`. ## Streaming the answer {#streaming} Add `Accept: text/event-stream` and the answer comes as a stream of events (SSE) — handy for showing the text as it is written. Each event is JSON on a `data:` line: | Event | Meaning | | --- | --- | | `{"type":"text","delta":"…"}` | The next piece of the answer | | `{"type":"tool","name":"…","phase":"start"}` | The agent started or finished (`"end"`) using a tool | | `{"type":"done","result":{…}}` | Done; `result` is the same JSON as without streaming | | `{"type":"error","status":500,"payload":{…}}` | An error with the status the plain call would have returned | If the client disconnects mid-answer, the work is not interrupted: the agent finishes it and the result is saved in the chat. ## Sending a file {#files} ```http POST /api/external/media-message Authorization: Bearer Content-Type: multipart/form-data ``` The same fields as `/message`, plus `file` and `kind` (`document`, `photo`, `audio`, `video`, `voice`, `file`). The file is saved to the chat's attachments and the agent sees it. A voice note (`kind=voice`) is transcribed to text first. ```bash curl -X POST https://name.cloud.eggent.ai/api/external/media-message \ -H "Authorization: Bearer $EGGENT_API_TOKEN" \ -F "sessionId=crm:client-42" \ -F "message=List every deadline in this contract" \ -F "kind=document" \ -F "file=@./contract.pdf" ``` ## Errors {#errors} | Status | Cause | Fix | | --- | --- | --- | | `400` | Missing `sessionId` or `message` | Send both as non-empty strings | | `401` | Missing or invalid token | Check the `Authorization: Bearer …` header | | `404` | Project or chat not found | Check project ids and names | | `409` | Ambiguous project name, or a chat from another project | Use `projectId` or drop `chatId` | | `503` | No token configured | Generate one in **Settings → API** | ## Tips {#tips} - Call the API only from a server, and only over HTTPS. - Set a generous timeout: a complex task can take several minutes. Or use streaming. - One real conversation, one `sessionId`. - A message that starts with `@` and a project's name hands the task to that project, as in the app: the project works in a chat of its own and its answer is part of the reply. See [Projects](https://eggent.ai/docs/projects.md#ask). - API answers spend balance just like the chat, and always run in full mode. --- # Plans and balance > How Eggent Cloud billing works — the trial, plans, Eggent AI credits, disk space, what happens when something runs out, and where to see it all. Source: https://eggent.ai/docs/plans/ In the cloud you pay for two things: the **workspace** (a plan — a month of the workspace running plus disk space) and the **model** (Eggent AI credits for model requests). If you work on [your own key](https://eggent.ai/docs/models.md#own-provider), you do not need the second. Current prices are always on your workspace's billing page: `https://cloud.eggent.ai/billing/name`. ## Trial {#trial} - 7 days. The billing page shows the date your trial ends. - 100 MB of disk. - Eggent AI credits to get started; every model in the list is available. - Two free images. When the trial or a plan ends the workspace closes: a page with the plans opens in its place. **Files, chats and settings are kept**, and after payment everything continues from where it was. ## Plans {#plans} A plan is a monthly subscription. It keeps the workspace running, raises the disk space and (except for the base plan) adds Eggent AI credits every month. - **The base plan** is for people who work on their own model key: no credits, but a proper disk. - **Plans with credits** — the higher the plan, the more credits per month and the more disk. The middle one is marked as the most popular. - **People.** If your workspace is a [company](https://eggent.ai/docs/business.md), Pro includes 1 person besides you, Max 2 and Super 3. They all spend the plan's credits and its disk. Base and Starter are plans for one person. - **Super's power.** Where the billing page offers it, Super is a base plus steps on top. Each step adds everything Pro has: credits, disk, browser, hard pages, pictures, letters and one more person. Steps are picked with the slider on the plan's card or added later on the billing page, and given up from the next period. Up to 50 people; for more, write to us about Enterprise. The billing page says what each plan includes. You pay by card through the Tribute payment page. The subscription renews monthly by itself; you can cancel at any time and keep access until the end of the paid month. To change plans, pick another one on the billing page. The new plan replaces the current one; you will not be charged twice. ## Credits {#credits} Credits are the balance that pays for Eggent AI model requests and images. - **Plan credits** arrive every month. The unused remainder expires at renewal. - **Bought credits** can be added on the billing page while you have an active plan. They never expire. - Plan credits are spent first, then bought ones. Each request costs according to the model and the number of tokens. The model price table is on the same page. [Cheaper models](https://eggent.ai/docs/models.md) and [light chat modes](https://eggent.ai/docs/chats.md#modes) make the balance last longer. ## What else a plan includes {#tools} Besides credits and disk, every plan includes four things a month. The billing page says how many of each a plan has, and the trial has a few to try them. - **Minutes of the agent's browser**: the [browser](https://eggent.ai/docs/browser.md) the agent drives on our machine. - **Hard pages**: pages the agent could not open itself, read for it on our server. - **Images** that are not taken from the balance; past them an image is paid from credits ([more](https://eggent.ai/docs/images.md#cost)). - **Letters** from the [agent's email](https://eggent.ai/docs/email.md#limits), and on a paid plan some of them to other people. They start again on the first of every month, and what is left does not carry over. In a [company](https://eggent.ai/docs/company.md) everybody uses the administrator's, and every place bought on top adds more. The agent knows how much is left, and a meter appears in the sidebar once half is used. ## When credits run out {#out-of-credits} - At half and at three-quarters of the balance a warning appears in the sidebar. - When credits run out, the agent on Eggent AI stops answering and sends a link to the billing page. An answer already in progress gets to finish. - The workspace itself stays open: files, chats and settings are available. Work on your own key carries on as usual. ## Disk space {#storage} - Disk usage is checked regularly; at three-quarters a warning appears. - When the disk is completely full, the agent stops answering but **the workspace stays open**: delete what you do not need in the **Files** panel and everything works again from the next message. The other way out is a plan with a bigger disk. - In a [company](https://eggent.ai/docs/company.md) the disk is shared: it counts the files of every person's workspace. ## Where to see it {#where} - **The billing page** `https://cloud.eggent.ai/billing/name` — days left, disk used, credits left, the plans and model prices. Sign in with the same email and password as the workspace. - **The workspace sidebar** — warnings when something is running low. - **The agent** — ask "how much do I have left?" and it answers with exact figures. --- # Eggent Business > Eggent Business is a company in Eggent Cloud. Everyone gets an agent in a workspace of their own, while a shared balance with monthly limits, teams, folders, messages, shared files and approvals sit with the administrator. What is included, how it is paid for and how to get it. Source: https://eggent.ai/docs/business/ **Eggent Business** is a company in Eggent Cloud, on our servers. Everyone gets an agent in a workspace of their own. What is shared (money, access, folders and documents) comes together with the administrator, in one console. How to use it day to day is on the page [Working in a company](https://eggent.ai/docs/company.md). This page covers what is included, how the money works and how to get started. > [!NOTE] > Companies are opened on request. Write to aiiszdes@gmail.com or to support on Telegram, and we will make your workspace the administrator's. ## Who it is for {#who} - A team where everyone needs an agent of their own, and paying for it and watching the spend is easier from one place. - A department that passes documents around and approves them. - Anyone who wants to give their people an agent while keeping limits and access in their own hands. If everything has to run on your own servers, that is [Eggent Enterprise](https://eggent.ai/docs/enterprise.md). ## What is included {#included} | What | How it works | Details | |---|---|---| | A workspace for each person | Their own agent, projects, files, chats and memory. They sign in with a one-time link that works once, within 72 hours. | [People](https://eggent.ai/docs/company.md#people) | | The administrator's console | **Company** in the floating button: people, teams, limits, folders and this month's spend. | [People](https://eggent.ai/docs/company.md#people) | | Teams | Group people for limits and shared folders. | [People](https://eggent.ai/docs/company.md#people) | | Company folders | A shared drive for one person, a team or everyone, read-only or read-write. | [People](https://eggent.ai/docs/company.md#people) | | Messages | The administrator and each person write to each other, with files and Telegram notices. | [Messages](https://eggent.ai/docs/company.md#messages) | | Shared files | A file is opened to colleagues to view, comment on or edit. | [Shared files](https://eggent.ai/docs/company.md#shares) | | Approvals | A version of a file goes to people one after another; any change voids the approval. | [Approvals](https://eggent.ai/docs/company.md#approvals) | | The administrator's agent | Adds people, sends sign-in links, resets passwords, writes reports from people's chats. | [People](https://eggent.ai/docs/company.md#people) | ## Money and limits {#money} - **One balance.** People's work with their agents is paid from the company balance, which is the administrator's workspace balance: the credits of its plan and any bought on top. It is topped up like any other: [plans and credits](https://eggent.ai/docs/plans.md). - **One disk.** The files of every workspace in the company count against the disk of the administrator's plan. When it is full, the agents of the whole company stop until somebody deletes something; the workspaces themselves stay open. - **Monthly limits.** Each person and each team can have a monthly limit. When a limit is reached, that person's agent stops until next month or until the limit goes up. - **The company's own key.** An OpenAI or OpenRouter key can be added in the console. People's requests to that provider's models go out on the key and are paid at its prices instead of from the balance, and they count against the same monthly limits. A ChatGPT or Codex subscription cannot be used for this: it belongs to one person. - **A person buys nothing.** Their billing page shows what they spent of the company's money this month; the company pays for everything. - **No trial.** People's workspaces have no trial and no end date: they run as long as the company does. - **Spend in plain sight.** The console shows what each person and each team spent this month. ## What it costs {#price} Business has no price of its own: the company is paid for by the ordinary [plan](https://eggent.ai/docs/plans.md#plans) of the administrator's workspace. A company starts at Pro, which includes one person besides the administrator. | Plan | People besides the administrator | |---|---| | Trial | +1, to try it | | Base | — | | Starter | — | | Pro | +1 | | Max | +2 | | Super | +3, and one more with every step of power (up to 50) | Base and Starter are plans for one person: they hold no people. Everyone spends that plan's credits and fills its disk. Need more people? Take steps of power on Super where the billing page offers them (each is another Pro and one more person); past 50, write to us about Enterprise. How many teams, folders and public chats a company can have depends on the administrator's plan too. ## Getting started {#start} 1. Write to us: how many people and how you work. 2. We make your workspace the administrator's. **Company** appears in the floating button. 3. Add people in the console, or ask your agent to. Each person gets a sign-in link. 4. Set limits, teams and folders, and get to work. ## Security and access {#security} - Every workspace runs separately from the others. A person's files are seen only by the people they opened them to. - The administrator and their agent can read people's chats to write a report. Every such read is logged, and everyone's agent knows it can happen. - A person, a folder or the whole company can be deleted in the console only; the agent cannot do it. - Files that hold access keys (`.env` and the like) are never shared. - When a company is closed, people's workspaces are deleted with their data and the company folders, and the administrator's workspace stays as an ordinary one. ## Not there yet {#not-yet} - Sign-in through a corporate SSO. - A combined log of actions in the interface. - Messages between two people, and team threads: the administrator and each person write to each other. - Moving a person from one company to another. --- # Files on your computer > How to keep your cloud Eggent's projects folder on your computer as an ordinary folder, synced both ways with Syncthing. Source: https://eggent.ai/docs/file-sync/ Your cloud workspace's projects folder can live on your computer as an ordinary folder: change it here and it changes there, and the other way round. It works through **Syncthing**, a free open-source program. > [!NOTE] > If you use the [Eggent app for Mac](https://eggent.ai/docs/desktop-app.md), you do not need any of this: the app keeps files, chats and the agent's memory in step with the cloud by itself ([how](https://eggent.ai/docs/desktop-cloud.md)). What it is good for: - opening the agent's results in the programs you know: Word, Excel, Obsidian, a code editor; - dropping material into a folder on your computer instead of uploading it through the browser; - keeping a copy of all your files. ## What is synced {#what} Only the **projects folder** (`data/projects`): the orchestrator's files and every project. Chats, settings, keys and system folders (`.pi`, `node_modules`) are not synced, and neither is `.mcp.json`, since it may contain tokens. Sync works **even while the workspace is asleep**. ## Connect a computer {#setup} Open `https://cloud.eggent.ai/sync/name` and sign in with the same email and password as the workspace. Then four steps, once per device: 1. **Install Syncthing** from [syncthing.net](https://syncthing.net/downloads/) and leave it running in the background. 2. **Tell us your device id.** In Syncthing: **Actions → Show ID**; copy the long code and paste it on the page. 3. **Add the server in Syncthing.** In Syncthing press **Add Remote Device** and paste the server id from the page. Tick the box saying you have added it and press **Connect**. 4. **Accept the folder.** Within a minute Syncthing on your computer offers a folder. Accept it and choose where it goes on your disk. > [!TIP] > If you missed the folder offer, **do not create a new folder**: it would get a different id and the two sides would never meet. Add a folder by hand, paste the folder id from the sync page into **Folder ID**, and share it with the server. ## If it does not connect {#troubleshooting} - Wait a minute: devices do not find each other instantly. - If there is still no connection, open the server device's settings in Syncthing, the **Advanced** tab, and put the server address shown on the sync page into **Addresses**. - Check the status on the sync page: "In sync", "Syncing, N%", "Offline, last seen …" or "Waiting for the first connection". ## Several devices {#devices} The same page lists **Connected devices**. You can connect another computer or disconnect an old one. Files already downloaded stay on a disconnected device. ## Deleted files and the trash {#trash} Files deleted or overwritten during sync are kept for 30 days in Syncthing's trash (the `.stversions` folder). It is not shown in Eggent's file panel. ## When the plan is inactive {#inactive} If the trial or the plan has ended, sync keeps **sending** files to your computer but stops **accepting** changes from it. The sync page shows this. After payment it works both ways again. --- # Sleep and wake > Why a cloud workspace goes to sleep when it is not used, how it wakes up, how long that takes and what happens to schedules and Telegram while it sleeps. Source: https://eggent.ai/docs/sleep/ A cloud workspace that has not been used for a while **goes to sleep**: its container stops and uses no server memory. This saves resources and takes nothing away from you. ## When it sleeps {#when} After about **12 hours** without activity. Activity means your requests to the workspace: open chats, messages, file work, Telegram messages. The workspace **does not sleep** if a [scheduled task](https://eggent.ai/docs/schedules.md) is due within the next half hour. ## How it wakes {#wake} By itself, on the first request: you open the address in a browser, write in Telegram, or an [API](https://eggent.ai/docs/external-api.md) call arrives. Waking takes about **10 seconds**, after which the request runs as usual. Nothing is lost or repeated. ## Schedules {#schedules} Scheduled tasks work during sleep too: the cloud wakes the workspace a couple of minutes before a run. So a daily digest or post arrives on time even if you have not visited for a week. ## What never sleeps {#always-on} - [File sync](https://eggent.ai/docs/file-sync.md) with your computer — it works with the disk directly. - The billing page and the sync page. ## Your own server {#self-host} The open core has no sleep: Eggent runs as long as its container does. --- # Sign-in, security and support > How to sign in to a cloud workspace, change your login, password, language and theme, how data is isolated, what to do with keys and passwords, and how to reach support. Source: https://eggent.ai/docs/account/ ## Signing in {#sign-in} Open your workspace address `https://name.cloud.eggent.ai` and sign in with the email and password you gave at signup. The same email and password work on the billing and sync pages. Signed up in Telegram? Send **`/login`** to the bot: it answers with a button that opens the workspace already signed in. The button works once and for 10 minutes; `/login` sends a new one. Right after signup the workspace opens already signed in, through a one-time link. The link works once and for 10 minutes. ## Change login and password {#credentials} **Settings → General → Dashboard authentication.** Enter a new login (your email or a name) and password (at least 8 characters) and save. Every other browser signed in to the workspace is signed out; this one stays in. The new details apply to the billing and sync pages too. ## Forgot the password {#reset} Press **Forgot your password?** on the sign-in page and enter the email the workspace is registered to. A letter comes with a link for every workspace of that address; each link works once and for an hour. Set a new password there and you are signed in, while every other browser that was signed in is signed out. The page answers the same way whether or not it knows the address, so it cannot be used to find out who has a workspace. Nothing came? Look in spam, ask again in a few minutes, then write to [support](#support). ## Confirming your email {#email} Right after signup a letter comes with a 6-digit code. Type it on the signup page while the workspace starts, send it to the bot if you signed up in Telegram, or press the button in the letter (it works for two days). Until then the sidebar reminds you once in a while; nothing else waits for it. A Telegram account connected later by a link (when the agent offers to send things to Telegram) can talk to the agent at once. To also sign in with `/login`, it needs your word: the bot sends a letter to your address with a button to confirm. ## Language and theme {#language} **Settings → General**: the interface language (English or Russian) and a light or dark theme. The language also sets which language the agent answers in by default. ## How data is protected {#security} - Every workspace runs in **its own container** with its own disk. Other workspaces cannot see it. - Eggent AI models are reached through the Eggent gateway: model providers' keys never enter the workspace. - Your own providers' keys saved in settings are kept in a protected workspace file and never enter the chat history. - Files the agent builds as web pages open isolated and have no access to the workspace. ## Rules for keys and passwords {#secrets} The agent sees everything you write in the chat, and chat history is stored. So: - **Model keys** go into **Settings → Models**, not the chat. - **The Telegram bot token** goes into **Settings → Messengers**. - **MCP server tokens** go into **Settings → MCP**. - Do not give the agent passwords to your accounts: it cannot sign in to sites anyway. If a secret has already ended up in a chat, delete that chat and reissue the key with the service. ## Support {#support} - **The Help button** in the bottom right of the workspace — with links to support and to file sync. - **Telegram**: [@youriisupport](https://t.me/youriisupport). - **Email**: [aiiszdes@gmail.com](mailto:aiiszdes@gmail.com). Include your workspace address (`name.cloud.eggent.ai`) and what happened — it gets you an answer faster. ## Deleting a workspace {#delete} Write to support from the email the workspace is registered to. Before deletion, download the files you need or turn on [sync with your computer](https://eggent.ai/docs/file-sync.md): once deleted, the data cannot be recovered. --- # Eggent for Mac > The Eggent app for Mac: what it is, how to download it and open it the first time (it is not signed yet), where its files live, and how to update or remove it. Source: https://eggent.ai/docs/desktop-app/ Eggent for Mac runs the same agent as Eggent Cloud on your own computer. Your projects are ordinary files in a folder you can open in Finder, and the agent works with the programs and files on your Mac. Connect your cloud workspace and the Mac and the cloud become one agent: [the same files, chats and memory on both](https://eggent.ai/docs/desktop-cloud.md). > [!WARNING] > This is an **early build** for Apple silicon, and it is **not signed or notarized by Apple yet**. macOS will not open it the first time without your say-so ([how](#first-launch)). Use it at your own risk, keep a copy of anything you can't lose, and read [what the agent can reach](#access) before you start. ## What it is {#what} An app with the same screens as the cloud version, and the Eggent server running inside it, on your computer. The server listens only on a local address, and only the app's window can talk to it. It works in two ways, and you can switch between them at any time: - **On its own.** Everything stays on this computer. You bring the model: a provider key of your own, or a program you already have ([Working on your own subscription](https://eggent.ai/docs/desktop-programs.md)). - **With your cloud workspace.** The Mac and the workspace are one agent, and the AI included in your workspace works here too: see [The app and your cloud workspace](https://eggent.ai/docs/desktop-cloud.md). ## Download {#download} Download the current build from the [Eggent for Mac page](https://eggent.ai/mac/). The page shows the size of the file and its SHA-256 checksum. After downloading, compare it: ```bash shasum -a 256 ~/Downloads/Eggent--arm64.dmg ``` ### What you need {#requirements} - A Mac with **Apple silicon** (M1 or newer) and **macOS 13 (Ventura) or later**. Intel Macs and Windows are not supported yet. - About **1.2 GB** of disk space for the app (the download is about 360 MB), plus room for your projects. - An internet connection for the model, whether it comes from your cloud workspace or from your own provider. - Optional: **Python 3** for the terminal panel. It comes with Apple's command line tools (`xcode-select --install` in Terminal). ## Open it the first time {#first-launch} macOS opens an app without a warning only after Apple has checked it, and that needs a paid developer certificate which Eggent does not have yet. So the first time you open the app, macOS stops it. Nothing is wrong with the file: you allow it once, and macOS remembers. 1. Open the `.dmg` and drag **Eggent** into **Applications**. 2. Open Eggent from Applications. macOS says it can't verify the app is free of malware. Click **Done** (**OK** on older macOS). 3. Open **System Settings → Privacy & Security**, scroll down to **Security**, click **Open Anyway** next to Eggent, and enter your password or use Touch ID. 4. Open Eggent again and click **Open**. This is the way Apple describes for any app macOS blocked: [Safely open apps on your Mac](https://support.apple.com/en-us/102445). A new download of a newer build asks again. On macOS 13 and 14 you can also Control-click Eggent, choose **Open**, and confirm. If you prefer Terminal, remove the "downloaded from the internet" flag and open the app as usual: ```bash xattr -dr com.apple.quarantine /Applications/Eggent.app ``` > [!NOTE] > If macOS says Eggent is **damaged** and offers to move it to the Trash, check the checksum of the file you downloaded (see [Download](#download)). If it matches, the file is fine: run the Terminal command above and open the app again. If it does not match, download it again. ## The first run {#first-run} 1. **Where should Eggent live?** Pick a folder; the default is `~/Eggent`. Everything Eggent does and keeps goes inside it. A folder that already has other things in it is never filled: Eggent makes a subfolder and says so first. If Eggent is already in the folder you pick, the app connects to it and deletes nothing. 2. **Connect cloud Eggent?** Enter your workspace name, login and password to connect your cloud workspace ([how it works](https://eggent.ai/docs/desktop-cloud.md#connect)), or press **Not now** and connect later from the **Eggent menu → Cloud & Sync…**. **I don't have an account yet** opens the cloud sign-up page in your browser; come back and connect afterwards. 3. The app prepares the agent's tools, starts the server and opens the window. The first start takes longer than the later ones. You never type a password on your own computer: the app signs its own window in. Without a cloud account the app needs a model. In **Settings → Models** add a provider with your own API key, or use [a program already on your computer](https://eggent.ai/docs/desktop-programs.md). ## Where everything lives {#folder} ```text ~/Eggent/ Projects/ shortcut to data/projects: your projects and the agent's files data/ projects/ projects and the agent's files chats/ what the screen shows of each chat pi-sessions/ what the agent remembers of each chat chat-files/ attachments settings/ … keys and settings of this computer README.txt ``` **File → Show Eggent Folder in Finder** and **File → Show Projects in Finder** open them. The app's own settings are in `~/Library/Application Support/Eggent`, and **File → Show Log** shows where its log is. **File → Change Eggent Folder…** puts it somewhere else, in one of two ways. **Move** takes everything to the new place: projects, chats, the agent's memory, the sign-in and the cloud connection. **Open Another** makes Eggent work in another folder and leaves this one on disk as it is: an empty folder starts afresh, an Eggent folder opens with what is in it. With the cloud connected, that other folder is kept in step with it: what is in it goes to the cloud, and the cloud's projects and chats come to it. Wait for the agent to finish what it is doing first; the app stops for a moment and starts again. Keys and settings are this computer's own. They are never synced to the cloud. ## Models {#models} The app needs a model to answer. There are three ways to give it one, and you can mix them: - **Your cloud workspace's AI.** Once you [connect the workspace](https://eggent.ai/docs/desktop-cloud.md#connect), the included models appear in **Settings → Models** and are counted on the same balance as in the cloud. They never replace a provider you chose yourself. - **Your own provider.** **Settings → Models** takes an API key, the same as on a server you run yourself: see [Models](https://eggent.ai/docs/models.md#own-provider). - **A program already on your computer.** A project can run on Claude Code or Codex with your own subscription: [Working on your own subscription](https://eggent.ai/docs/desktop-programs.md). ## What the agent can reach {#access} In the cloud the agent works inside a computer that holds only your workspace. **On your Mac there is no such box.** The agent has a terminal and runs commands as your user, starting in the Eggent folder, so it can read and change anything your account can, just like any program you run. What keeps it in check: - Only the app's window can talk to the local server. A web page open in your browser cannot, even though the server is on your own machine. - The server gets a small, fixed set of environment variables, not the ones in your shell, so keys you exported in Terminal are not handed to it. - Keys and settings you add stay in the app's data folder and are never synced to the cloud. Treat the agent the way you would a capable assistant with a terminal on your laptop: ask for things you would be comfortable with it doing, and keep important data backed up. ## Updates {#updates} There are no automatic updates yet. To update, download the new build from the [Eggent for Mac page](https://eggent.ai/mac/), quit Eggent, drag the new Eggent into **Applications** and replace the old one, then open it. macOS asks for permission again, as the first time. Your folder and settings stay as they are. Keep the app reasonably current if you use it with the cloud: they share chat files, and versions far apart may not read each other's. ## Remove it {#remove} Quit Eggent and drag it from **Applications** to the Trash. That leaves two things behind on purpose: your `~/Eggent` folder, which holds your files and chat history, and the app's own settings in `~/Library/Application Support/Eggent`. Delete them too for a clean slate. If you used the cloud, [disconnect](https://eggent.ai/docs/desktop-cloud.md#disconnect) first. ## If something goes wrong {#troubleshooting} - **macOS will not open the app, or says it is damaged.** See [Open it the first time](#first-launch). - **"Eggent didn't start".** The screen offers **Try again** and **Show log**. The log says what happened; if you write to support, include it. - **The first start is slow.** The app prepares the agent's tools once, which takes a minute or so. Later starts are quicker. - **The terminal panel says it is not available.** It needs Python 3; install Apple's command line tools with `xcode-select --install`. Commands still run from the chat meanwhile. - **"Eggent is still working" when you quit.** The app counts the chats that are running now. If you quit, they stop; **Keep working** lets them finish. - **Sync problems.** See [The app and your cloud workspace](https://eggent.ai/docs/desktop-cloud.md#troubleshooting). ## Not here yet {#limits} - Windows and Intel Macs. - Signing and notarization, so no warning on first launch, and automatic updates. - Starting at login and a menu bar item. - The speech recognition and the Python document tools that the cloud's computer carries. The agent uses whatever you have installed. - Schedules that run while your Mac is off. A schedule made in the app runs only while the app is open; for a task that must run on time, create it in the cloud. See [What stays on each side](https://eggent.ai/docs/desktop-cloud.md#separate). --- # The app and your cloud workspace > Connect the Eggent app to your cloud workspace so the Mac and the cloud are one agent: what is kept in step, what stays on each side, and how a chat can run on either. Source: https://eggent.ai/docs/desktop-cloud/ Signed out, the [Eggent app for Mac](https://eggent.ai/docs/desktop-app.md) works on its own and everything stays on your computer. Signed in to your Eggent Cloud workspace, the computer and the workspace are **one agent**: the same files, the same chats, the same memory of each chat, the same attachments. There is no switch between a "local" and a "cloud" agent. Start a chat in the browser, carry on in the app, and the agent remembers. ## Connect {#connect} On the first screen ("Connect cloud Eggent?"), or later through **Eggent menu → Cloud & Sync… → Connect an account**, enter: - the **workspace name**: the part before `.cloud.eggent.ai` (a pasted address is shortened for you); - the **login** and **password** of the workspace, the same you use in the browser. The app uses them once, to pair this computer with the workspace, and does not keep the password. Pairing adds the computer to the workspace's sync and hands the app a key for the workspace's AI. **I don't have an account yet** opens the cloud sign-up page in your browser; signing up is not in the app yet. The sync program is part of the app, so there is nothing to install. It is separate from [Files on your computer](https://eggent.ai/docs/file-sync.md), which keeps only the projects folder in step through a program you install yourself. ## One agent {#one-agent} These are kept in step, in both directions, even while the workspace is asleep: - **Files**: the projects folder. - **Chats**: what the screen shows of each conversation. - **Agent memory**: what the agent remembers of each chat, so it carries on where it left off on the other side. - **Attachments**. - The **task board**, for a workspace that lets chats run on either side (see [Where a card runs](#board)). The window title tells where sync stands: *in sync*, *syncing 40%*, *can't reach the cloud*, *sync problem*. **Eggent menu → Cloud & Sync…** shows the same in full, with what is kept in step. Offline, files are saved here and sent as soon as the connection is back. ## What stays on each side {#separate} Never synced, by design: - **Keys and settings.** Each side has its own provider keys, login and preferences. Connecting the workspace never moves you off a provider you chose. - **Telegram connections.** - **MCP server settings** (`.mcp.json`), because they may hold tokens. - **Schedules.** A schedule is armed inside one running agent, and two computers each firing the 7 o'clock job would post twice. The cloud is on while your Mac is off, so schedules that matter live there. **A schedule made in the app runs only while the app is open.** For a task that must run on time, create it in the cloud. ## Room in your plan {#room} The cloud stops the agent when your plan's storage is full, so the app will not fill it by surprise. Files are always sent. Chats, agent memory and attachments are sent only if everything fits; if not, the app asks once, before anything goes: > Your chat history won't fit in your plan. … **Keep them here**, or **Send anyway**? Keeping them here leaves the files in sync and the history on this computer; **Cloud & Sync** says so and keeps a **Send anyway** button for later. Without the history in step, chats cannot run on the other side either (see below). Free some space or change plan, and send it. ## Two computers {#two-computers} Another Mac can be connected to the same workspace. Each keeps its own copy. If two of them write to the same chat while they are apart, the copies are **joined**, not set aside: every message from both is kept, and the agent carries on from the branch that was active last. Until a connected computer has joined them, the cloud may list such a chat twice; it settles within seconds of any connected computer being online. ## The workspace's AI {#included-model} While connected, the AI included in your workspace is available here too, on the same balance and with the same limits, in **Settings → Models**. It never replaces a provider you chose yourself. **Disconnect** removes it from this computer. ## A chat can run on either side {#where-it-runs} > [!NOTE] > This is being switched on workspace by workspace. If **Tasks from your cloud** in **Cloud & Sync** says "This isn't turned on for your workspace yet", it is not available to you yet. With the app on a computer and your cloud workspace together, every chat can run on either one, and you choose. A control in the line under the message box says where this chat runs: **Cloud** or **This computer** (in the cloud version your computer is listed by its name). Choose the other place and the chat runs there from the next message on, whichever of the two you type into. Why: on your computer the agent works with the files and programs that live on it. In the cloud it keeps working when the computer is closed. A chat started on the computer can be handed to the cloud to run for hours; a chat in the cloud version can be handed to your computer. - **You stay where you are.** The answer streams into the screen you typed on, with the stop button, steering and the agent's questions working as always. A chat that runs on the other side has a small cloud or laptop icon in the list. - **One place writes the chat.** The place that runs the chat is the only one that writes it down; the other side gets it through sync, and the screen waits for it to arrive, usually a few seconds. - **The agent has what it needs.** A chat is handed over only after the conversation, the agent's memory of it and the files attached to it have reached the place that will run it. A message sent a second after an upload waits for the file. - **If the other side is not there,** the chat says so, keeps your message, and offers **Run it here instead** (which sends that message here) or **Try again**. A chat can only be handed between your computer and your cloud, never from one computer to another. In Telegram, `/here` runs a chat on the side that is answering: for the shared bot that is the cloud, so it brings back a chat that was moved to a computer that is off. ## Letting the cloud run chats on your computer {#computer-allow} This is off until you turn it on, in **Eggent menu → Cloud & Sync… → Tasks from your cloud**: - **Don't allow** (the default). Your computer never runs anything for the cloud. - **Ask me for each chat.** The first time the cloud wants to run a chat on your computer, the app shows which chat and the start of the message, and asks. An allowed chat stays allowed while you use it and for a day after. No answer within a minute means no. - **Allow every chat.** A chat run for the cloud works with the files and tools of your computer, exactly as a chat you started there. Allow only what you would start yourself. The question is the only thing between the cloud and your computer: the agent inside your workspace can ask for a chat too, so read what the dialog shows before you say yes, and keep in mind that **Allow every chat** removes the question. The app shows the message as it will be run (and how much of it it left out), puts at most a few questions to you at a time, does not ask about a request the cloud has already given up on, and does not ask again for a few seconds about a chat you have just said no to. Allowing a chat covers the messages it sends later too. Turning this off disconnects the computer from the cloud's requests at once; chats you hand to the cloud from the computer keep working. For a project that runs on a program of your own ([Working on your own subscription](https://eggent.ai/docs/desktop-programs.md)) **Ask me for each chat** asks about it separately and names the program and how far it reaches. **Allow every chat** covers these chats too. ## Where a card runs {#board} With the app on a computer paired with your workspace, a card on the [task board](https://eggent.ai/docs/board.md) can run on the computer as well as in the cloud. The card's **Runs on** says where: **Cloud** (the default: it keeps going while the computer is off) or your computer by its name, to work with the files and programs on it. - **The cloud starts every card,** wherever it runs. A card for your computer is handed to it the way a chat is, so the app asks first unless you allowed every chat. - **A computer that is away does not fail a card.** It waits in the queue, marked "… is away", and starts when the app is back and takes tasks from the cloud. - **Its chat runs there too.** A message typed in the card's chat, on either side or from Telegram, runs where the card does. Moving the chat to the other side moves the card with it. - **A question, a stop and a refusal** work as for any card: the question waits on the card in both places, Stop works from either side, and a computer that says no leaves the card waiting for you instead of asking again. ## Disconnect {#disconnect} **Eggent menu → Cloud & Sync… → Disconnect.** Files on this computer stay, but stop updating together with the cloud's; the workspace's AI stops working here, and the app works on its own again. Disconnecting removes the pairing on this computer. It does not remove the computer from your workspace's list of devices yet; if you want that entry gone, write to support through the **Help** button in your workspace. ## If it does not connect {#troubleshooting} - **"That login or password didn't work."** Use the workspace's own login, the one you use in the browser. - **"No such workspace."** Check the name: it is the part before `.cloud.eggent.ai`. - **"Sync isn't available for this workspace."** It is not turned on for this workspace; write to support. - **"Couldn't reach the cloud."** Check your connection and try again. If the title says *can't reach the cloud* afterwards, files are saved here and sent when the connection is back. - **"Too many attempts."** Wait a minute. - **Files do not arrive.** Look at the state in **Cloud & Sync**. If it says history is held back, that is the plan's room ([see above](#room)); your files still sync. ### A chat will not run on the other side {#remote-troubleshooting} - **"… isn't available right now."** The app is closed, offline, or **Tasks from your cloud** is off. Open the app, or choose **Run it here instead**. - **"… hasn't received this chat's latest changes yet."** The files have not arrived. Wait a few seconds and send again; look at the sync state in **Cloud & Sync**. - **"… can't take this chat yet."** The computer's chat history is not synced with the cloud. - **"… declined to run this chat."** You, or the dialog's timeout, said no. Send again and allow it. - **"… can't run this chat right now. …"** The project runs on a program ([Working on your own subscription](https://eggent.ai/docs/desktop-programs.md)) and the program on that computer is not ready: signed out, not installed, or at its limit. Sort it out in the app on that computer, or run the chat here instead. - **"This chat was moved to this side a moment ago…"** You moved the chat on the other side and wrote here before the sync carried the move over. Wait a few seconds and send again. - **Moving a chat says it has not arrived yet.** Before a chat is moved, the side that moves it must hold what the other side last wrote. Wait a few seconds and try again. - **The answer stopped but the turn went on.** If the line to the other side drops mid-turn, the turn carries on there and its answer appears here when the sync brings it. - **The computer went to sleep, or lost its connection, while it was working.** The cloud notices after about a minute and says the connection was lost. The turn carries on there once the computer is back, and its answer appears here through sync. Stop works from either side. --- # Working on your own subscription > In the Eggent app for Mac a project can run on Claude Code or Codex, already installed on your computer, using your own subscription instead of an Eggent model. Experimental. Source: https://eggent.ai/docs/desktop-programs/ If **Claude Code** or **Codex** is installed on your computer, the [Eggent app for Mac](https://eggent.ai/docs/desktop-app.md) lists it in **Settings → Models**, under **On this computer**. A project, or your chats outside projects, can run on it using **your own subscription** instead of an Eggent model. Nothing is taken from your Eggent balance, and Eggent never sees your sign-in: it starts the program the way you would and reads only what the program says about itself. > [!WARNING] > This is experimental. Claude Code and Codex are other companies' programs with their own terms and limits, and Eggent cannot promise that they keep working with it. Codex is marked as an experiment in the app itself. ## What it is {#what} A model is something Eggent sends a request to. A program is different: it has its own tools and does the project's work itself, in the project's folder. Eggent hands it your message, shows what it does as it goes, and keeps the chat, so the stop button, the chat history and the files panel work as in any chat. It suits work with files and code. It is not the same agent: Eggent's own tools, skills and memory are not in play, see [what changes in a chat](#chat). ## Turn it on {#start} 1. Open **Settings → Models**. A program found on the computer is listed under **On this computer** with its version. (Nothing is shown if none is found.) 2. **Installed but not signed in?** Press **Sign in**. The program's own sign-in opens in your browser, and the screen notices when you are done. 3. Press **Use for this project** (or **Use here**, for chats outside projects). The first time, a sheet asks what this means ([below](#sheet)) and asks the program for one word to find out that it answers, before anything is moved onto it. 4. After that it is just a switch. You can also pick the program in the model list under the message box. **Use Eggent's model instead** puts the project back on a model. Nothing is lost: the chats stay, and a message that failed on the program can be sent again on a model from the button under the answer. ## What the sheet tells you {#sheet} - The program works in the project's folder **with its own tools**, not with Eggent's. - It uses the limits of your subscription. What you write and the files it reads go to the company behind it. - **Schedules, question cards, Eggent skills and Telegram do not work in this mode**, and Eggent learns nothing from these chats. - **Access** is yours to set: [see below](#access). ## Access {#access} - **Changes only in this project's folder** (the default). The program changes files only inside the folder. Claude Code cannot run commands at this level; Codex runs them in a sandbox with no network. What the program reads is sent to the company behind it. - **As in a terminal (the whole computer).** The program can read and change anything on your computer that you can, and runs commands without asking first. Choose it only when you mean it. ## What changes in a chat {#chat} A chat that runs on a program is marked by a line under the message box, which also drops the token counts, since they are not Eggent's to count. Messages after the first are sent to the same session of the program, so it remembers the chat; a chat that already had history gets a short recap on the first message. Files you attach to the chat are named to the program and their folder is opened to it. A few programs can work at a time; one that has to wait says so ("waiting for a free place"). ## When the program is not ready {#not-ready} If the program is signed out, out of date, or at the limit of your subscription, the answer says so in the program's own words and offers **Continue with Eggent's model**. - **Signed out.** **Settings → Models → Sign in**, then send again. - **Limit reached.** The answer says when it opens again, if the program tells; wait for it, or pick another model for the project. - **An API key was found.** The program would bill the key instead of your subscription, so Eggent does not start it. Remove the key from its settings or the environment. - **Too old.** Update the program. ## When the cloud hands a chat to your computer {#remote} A project that runs on a program can also be run from the cloud, if you let it: see [Letting the cloud run chats on your computer](https://eggent.ai/docs/desktop-cloud.md#computer-allow). If you chose **Ask me for each chat**, the app asks about such a chat by itself, names the program and how far it reaches ("It can change files only in the project's folder", or "It can read and change anything on this computer that you can, and runs commands without asking"), and an allowance for it covers only that program at that reach. **Allow every chat** covers these chats too. If the program on this computer is not ready, the chat says so, and **Run it here instead** puts it back where you are. --- # Installing on your own server > How to run the Eggent open core on your own machine or VPS — the one-command installer, the published Docker image, building from source and the first launch. Source: https://eggent.ai/docs/self-host-install/ The Eggent open core is the same workspace as in the cloud, on your own machine: every chat, file, memory and key lives in the `./data` folder. MIT licence, code on [GitHub](https://github.com/eggent-ai/eggent). How it differs from the cloud: no Eggent AI (you need your own model key), no quick-start skill cards, no shared Telegram bot, no Syncthing sync and no sleep. Everything else is the same. This is one workspace. Eggent for a whole company, with a workspace for each person, limits and shared files, is installed on your servers as [Eggent Enterprise](https://eggent.ai/docs/enterprise.md). ## Requirements {#requirements} - Linux, macOS, or Windows with WSL2. - **Docker** (the installer sets it up if it can) or Node.js 22 to run without Docker. - At least 2 GB of RAM and a few gigabytes of free disk for the image and data. - An API key from any model provider, or a local model with an OpenAI-compatible API. ## One-command install {#installer} ```bash curl -fsSL https://get.eggent.ai | bash ``` The installer: 1. downloads Eggent into `~/.eggent`; 2. installs Docker if it is missing; 3. builds and starts the container; 4. waits for Eggent to answer and prints the address. By default Eggent is reachable only from this machine: `http://127.0.0.1:3000`. Installer options are set with variables: ```bash EGGENT_INSTALL_DIR=/opt/eggent \ APP_PORT=3000 \ EGGENT_APP_BIND_HOST=127.0.0.1 \ bash -c "$(curl -fsSL https://get.eggent.ai)" ``` ## The published Docker image {#image} Nothing to build: the `ghcr.io/eggent-ai/eggent` image is published with every release. ```bash curl -O https://raw.githubusercontent.com/eggent-ai/eggent/main/docker-compose.ghcr.yml docker compose -f docker-compose.ghcr.yml up -d ``` `docker-compose.ghcr.yml` can also be pasted into Portainer. Better to pin a version in `.env` (`EGGENT_VERSION=0.2.9`) than to follow `latest`. ## Building from source {#source} ```bash git clone https://github.com/eggent-ai/eggent.git cd eggent cp .env.example .env # optional docker compose up -d --build ``` Data is stored in `./data`, which is `/app/data` inside the container. ## Without Docker, for development {#dev} ```bash git clone https://github.com/eggent-ai/eggent.git cd eggent npm install npm run dev ``` Needs Node.js 22. For voice, install `ffmpeg` and `whisper.cpp`. ## First launch {#first-run} 1. Open `http://127.0.0.1:3000`. 2. Sign in with the login `admin` and password `admin` — Eggent asks you to replace them with your own right away. 3. Connect a model provider: pick it and paste the key. The key does not have to go into `.env` — it is kept in `data/`. 4. Start your first chat. From here it is all as in [First steps](https://eggent.ai/docs/first-steps.md), except the quick-start cards. ## Exposing it to the internet {#public} On a VPS, the right way is to keep Eggent on `127.0.0.1` and put a reverse proxy with HTTPS in front of it (Caddy, Nginx, Traefik). Details and an example are in [Configuring your server](https://eggent.ai/docs/self-host-config.md#reverse-proxy). --- # Configuring your server > Environment variables of the Eggent open core, a reverse proxy with HTTPS for a VPS, the Telegram webhook, an egress proxy and security rules. Source: https://eggent.ai/docs/self-host-config/ Almost everything is configured in the Eggent interface, and a `.env` file is optional. Environment variables are for what must be known before start-up: the address, the port, fallback keys. ## Environment variables {#env} The full list is in `.env.example` in the repository. The main ones: | Variable | Default | What for | | --- | --- | --- | | `APP_BIND_HOST` | `127.0.0.1` | Host address Docker listens on. `0.0.0.0` only on purpose | | `APP_PORT` | `3000` | Host port | | `APP_BASE_URL` | `http://localhost:3000` | Public address — for webhooks and links | | `EGGENT_AUTH_SECRET` | generated in `data/settings/` | Session signing secret | | `EXTERNAL_API_TOKEN` | unset | Fallback token for the [external API](https://eggent.ai/docs/external-api.md) | | `TELEGRAM_BOT_TOKEN` | unset | Bot token, if you would rather not enter it in the interface | | `TELEGRAM_WEBHOOK_SECRET` | unset | Telegram webhook secret | | `TELEGRAM_DEFAULT_PROJECT_ID` | unset | Default project for Telegram | | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY` | unset | Fallback provider keys | | `EGGENT_STT_ENABLED`, `EGGENT_STT_MODEL`, `EGGENT_STT_LANGUAGE` | `1`, `base`, `auto` | [Speech recognition](https://eggent.ai/docs/voice.md#self-host) | | `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | unset | Outbound traffic through a proxy | | `EGGENT_LEARNING` | on | `off` stops the agent from keeping notes and skills from conversations (see [Memory](https://eggent.ai/docs/memory.md#learned)). What is already saved is no longer read either | | `EGGENT_LEARNING_MODEL` | the chat's model | The model for the background look-back, as `provider/id` or just the id — a cheaper one is enough | | `EGGENT_LEARNING_DAILY_CAP`, `EGGENT_LEARNING_MIN_GAP_SECONDS`, `EGGENT_LEARNING_EVERY_TURNS` | `40`, `60`, `6` | Look-backs per day, the pause between two, and how often a conversation with nothing flagged is looked at | | `EGGENT_TURN_WATCHDOG` | on | `off` switches off the check that stops a turn which has gone quiet (see [Chats](https://eggent.ai/docs/chats.md#while-working)). Worth doing if you run a slow local model that can think for longer than the limits below | | `EGGENT_TURN_SILENCE_SOFT_SECONDS`, `EGGENT_TURN_SILENCE_START_SECONDS`, `EGGENT_TURN_SILENCE_MODEL_SECONDS`, `EGGENT_TURN_SILENCE_TOOL_SECONDS` | `90`, `180`, `360`, `1200` | How long a turn may say nothing before the chat tells you it is still going, and before it is stopped: while it starts, while the model has not answered, while a command runs. A command that is running next to another one keeps its full allowance | | `EGGENT_TURN_QUESTION_WAIT_SECONDS` | `86400` | How long a question to you may wait for an answer before the turn is stopped (see [Chats](https://eggent.ai/docs/chats.md#questions)). `0` or `off` lets a question wait for ever | | `EGGENT_VISITS_MAX`, `EGGENT_VISIT_TIMEOUT_MINUTES`, `EGGENT_VISIT_STOP_GRACE_SECONDS` | `2`, `10`, `20` | [Asking a project with `@`](https://eggent.ai/docs/projects.md#ask): how many may run at once, how long one may take, and how long one that was told to stop is given before it is let go of | | `EGGENT_BOARD` | on | `off` stops the [task board](https://eggent.ai/docs/board.md) from starting cards; the board and its cards stay | | `EGGENT_BOARD_MAX_RUNNING`, `EGGENT_BOARD_MAX_PER_PROJECT` | `3`, `1` | How many cards work at once across the board, and in one project. Cards of one project share its folder | | `EGGENT_BOARD_RETRY_SECONDS` | `60` | How long a failed card waits before its one automatic retry | | `EGGENT_ZIP_MAX_MB`, `EGGENT_ZIP_MAX_FILES`, `EGGENT_ZIP_IDLE_SECONDS` | `1024`, `10000`, `120` | The size and file count of one [archive](https://eggent.ai/docs/files.md#zip), and how long one may stand still, with nobody taking it, before it is dropped | | `EGGENT_VERSIONS` | on | `off` stops keeping [versions of files](https://eggent.ai/docs/files.md#history); what is already kept can still be looked at | | `EGGENT_VERSIONS_KEEP_DAYS`, `EGGENT_VERSIONS_DAILY_DAYS`, `EGGENT_VERSIONS_MAX_PER_FILE`, `EGGENT_VERSIONS_MAX_FILE_MB` | `30`, `90`, `200`, `10` | How long every version is kept after it was replaced, until when one a day is kept, how many one file keeps, and the size above which a file gets no history | | `EGGENT_VERSIONS_SCAN_SECONDS` | `120` | How often files that have a history are looked at for changes made elsewhere: the sync, the terminal, another program | | `EGGENT_VERSIONS_MAX_TOTAL_MB`, `EGGENT_VERSIONS_DISK_SHARE` | `1024`, `0.25` | The most the whole history may take, and the share of the disk it may take when the deployment reports one; past it the versions replaced longest ago go first | | `EGGENT_WEB_SEARCH_DEFAULTS` | on | `off` stops Eggent from writing the order of free search engines into `data/pi-agent/web-search.json` at start (see [Agent tools](https://eggent.ai/docs/agent-tools.md#web)) | | `EGGENT_CLOUD_PROMO` | on | `0` takes away the short card about Eggent Cloud at the bottom of **Settings → Models** | | `EGGENT_VERSION` | `latest` | Image tag for `docker-compose.ghcr.yml` | After changing `.env`, recreate the container: ```bash docker compose up -d --force-recreate ``` ## Reverse proxy and HTTPS {#reverse-proxy} On a VPS, keep Eggent on `127.0.0.1` and put a proxy with HTTPS in front of it. HTTPS is not only about security: without it the browser will not allow the microphone, and Telegram will not accept a webhook. **Caddy** (gets the certificate by itself): ```text eggent.example.com { request_body { max_size 100MB } reverse_proxy 127.0.0.1:3000 } ``` **Nginx**: ```nginx server { server_name eggent.example.com; client_max_body_size 100m; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_read_timeout 600s; } } ``` > [!WARNING] > The proxy caps the request size, and its cap is usually lower than Eggent's: Nginx defaults to 1 MB, so uploading a large file fails with `413`. Raise it to 100 MB as in the examples. `proxy_buffering off` and a long `proxy_read_timeout` let the agent's answers stream and keep long tasks from being cut off. Once the proxy is set up, put the public address into `APP_BASE_URL`. ## Telegram on your own server {#telegram} Connect the bot in **Settings → Messengers**, as described in [Telegram](https://eggent.ai/docs/telegram.md#own-bot). Modes: - **Long Polling** — works without a public address. Good for a home machine. Messages are handled one after another, so something you send while the agent is busy — including `/reset` or "stop" — is read when that turn ends; a turn that has gone quiet is ended by the limits under `EGGENT_TURN_SILENCE_*` above. - **Webhook** — needs a public HTTPS address (`APP_BASE_URL`). Faster and more reliable on a VPS. **Auto** picks the webhook once a public HTTPS address is set. ## Egress proxy {#egress-proxy} If the server reaches the internet only through a proxy, set `HTTPS_PROXY` (and `HTTP_PROXY`, `NO_PROXY` if needed). Needs Node.js 22.23 or newer; the Docker image already has it. ## Security {#security} - Do not expose Eggent's port to the internet without HTTPS. By default it listens only on `127.0.0.1` — keep it that way behind a proxy. - Change the default login and password straight away. - Treat the external API token like a password and never use it in browser code. - Protect and back up the `data/` folder: it holds chats, files, memory, settings and keys. - The agent has a terminal inside the container. Do not mount folders into the container that the agent does not need. --- # Upgrades and backups > How to upgrade the Eggent open core, back up the data folder, check the server's health, read logs and move Eggent to another machine. Source: https://eggent.ai/docs/self-host-maintenance/ ## Checking that it works {#health} ```bash curl -fsS http://127.0.0.1:3000/api/health ``` The answer contains the status and the Eggent version. The same check works for monitoring. The `docker compose` commands below run in the install folder (`~/.eggent` if you used the installer). Container logs: ```bash docker compose logs -f --tail=200 ``` ## Upgrading {#upgrade} Make a [backup](https://eggent.ai/docs/self-host-maintenance.md#backup) before upgrading. **Installed with the installer** — just run it again; it updates the code and rebuilds the container: ```bash curl -fsSL https://get.eggent.ai | bash ``` **The published image** — change `EGGENT_VERSION` in `.env` to the new version and run: ```bash docker compose -f docker-compose.ghcr.yml pull docker compose -f docker-compose.ghcr.yml up -d ``` **From source**: ```bash git pull docker compose up -d --build ``` What changed in each version is in the [GitHub releases](https://github.com/eggent-ai/eggent/releases). ## Backups {#backup} All of Eggent's state is the `data/` folder. To back it up, archive it: ```bash docker compose stop tar czf eggent-data-$(date +%F).tgz data docker compose start ``` Stopping keeps files from changing during the copy. Keep backups off the server: `data/` holds keys and tokens, so treat the archive as a secret. ## Moving to another machine {#migrate} 1. Install Eggent on the new machine the same way. 2. Stop it and replace its `data/` folder with the copy from the old machine. 3. Start it again. Chats, projects, settings, keys, schedules and the Telegram bot all move with the folder. If the public address changes, update `APP_BASE_URL` and press **Activate Bot** again in **Settings → Messengers** so Telegram learns the new webhook address. ## Restarts and schedules {#restart} On start-up Eggent re-arms every saved [schedule](https://eggent.ai/docs/schedules.md). Runs missed while the server was off are not repeated: the task runs at its next scheduled time. One-off tasks whose time has passed are removed. ## The speech recognition model {#whisper} The `whisper.cpp` model is downloaded on the first transcription into `data/models/whisper/`. For a more accurate one, set `EGGENT_STT_MODEL=small` (or `medium`) and recreate the container; the new model downloads by itself. Without internet access, put the `ggml-.bin` file in that folder by hand. --- # Eggent Enterprise > Eggent Enterprise is all of Eggent on your own servers. People's workspaces, the company console, the model gateway, file sync and a Telegram bot inside your infrastructure. What we install, what you need and how it differs from the free install. Source: https://eggent.ai/docs/enterprise/ **Eggent Enterprise** is the stack that runs Eggent Cloud, installed in your infrastructure. Everything described in [Eggent Business](https://eggent.ai/docs/business.md) and on the page [Working in a company](https://eggent.ai/docs/company.md) works the same way, but files, chats and the agents' memory are stored on your servers. > [!NOTE] > Enterprise is installed under a contract. Write to aiiszdes@gmail.com or to support on Telegram: how many people, where the data has to live and which models you use. ## What we install {#stack} - **Workspaces.** Each person gets a workspace with an agent: files, chats, memory, schedules, skills. An idle workspace goes to sleep and uses no memory, and wakes on the first request with nothing lost. - **The control panel.** Creating workspaces, sign-in, the company console and administration. - **The model gateway.** Workspaces reach models through it: the provider keys live in the gateway, and a workspace only gets its own pass to it. Spend is counted per person and per team, with monthly limits. - **File sync.** People's folders sync with their computers ([File sync](https://eggent.ai/docs/file-sync.md)). - **A Telegram bot.** Your own: people create workspaces through it, talk to their agent and get the company's notices. - **Domains and certificates.** Workspaces live on subdomains of your domain, and certificates are issued automatically. ## Data {#data} - Files, chats, history and the agents' memory are stored on your servers. - What leaves is the requests to the models you connected, and whatever the agent does on the internet for a task, such as searching or opening a site. If the model runs with you too, people's data does not leave your perimeter. - The Eggent core is open source under the MIT licence ([github.com/eggent-ai/eggent](https://github.com/eggent-ai/eggent)), so the agent's code can be read before it is installed. The control panel and the gateway are installed from our images. ## Models {#models} - **Through the gateway**, on an OpenAI or OpenRouter key. Everyone then has one list of models, and spend is counted per person and per team. - **In a workspace**, on any provider's key: OpenAI, Anthropic, Google, OpenRouter, DeepSeek, or a model of your own behind an OpenAI-compatible API, on your own server if you like ([Your own provider](https://eggent.ai/docs/models.md#own-provider)). ## How it differs from the free install {#vs-self-host} | | Free install | Enterprise | |---|---|---| | What it is | One workspace: one agent with its projects | A workspace for each person, and a company | | Installation | One command, done yourself ([Installation](https://eggent.ai/docs/self-host-install.md)) | We install it | | Models | Your key or your own model | A gateway that counts spend, plus your own key in any workspace | | Company | — | People, teams, limits, folders, messages, shared files, approvals | | Sleeping workspaces, file sync, Telegram bot | — | Included | | Updates | Yourself ([Maintenance](https://eggent.ai/docs/self-host-maintenance.md)) | Us, under the contract | | Price | Free, MIT licence | Under contract | ## What you need {#requirements} - A Linux server with Docker, your own or in your cloud. Everything runs in containers. - A domain and DNS records: the panel's address and a wildcard record for the workspaces (`*.your-domain`). Certificates are issued automatically. - Open ports: 80 and 443 for the sites, 22000 for file sync. - For scale: on our own server, 6 cores and 12 GB of memory keep about 30 workspaces running at once while the rest sleep. - Model keys, or a model of your own. ## How we start {#start} 1. **A conversation.** How many people, where it should run, which models and internal systems it needs. 2. **Installation.** We install the stack on your server, connect the domain and add the first people. 3. **Connections.** Your models, your Telegram bot, your internal systems over [MCP](https://eggent.ai/docs/mcp.md) or the [API](https://eggent.ai/docs/external-api.md). 4. **Looking after it.** Updates and support under the contract. ## Not there yet {#not-yet} - Sign-in through a corporate SSO. - A combined log of actions in the interface. --- # Agent tools > The full reference of tools an Eggent agent has — what each is for, its main parameters and the requests that lead to it. Useful to people and to the agent itself. Source: https://eggent.ai/docs/agent-tools/ A tool is an action the agent can take by itself. Below are all the workspace's tools in full chat mode. In ["chat + files"](https://eggent.ai/docs/chats.md#modes) mode only reading files and switching projects remain; "plain chat" has no tools. ## Files and commands {#files} The runtime's basic tools. They work in the current project's (or the orchestrator's) folder. | Tool | What it does | | --- | --- | | `read` | Reads a file: text, code, an image (for models that can see) | | `write` | Creates or overwrites a file | | `edit` | Makes targeted edits to a file | | `bash` | Runs a terminal command: Python and Node.js, `git`, `curl`, file conversion | | `ls` | Lists a folder (in "chat + files" mode) | ## The web {#web} | Tool | What it does | | --- | --- | | `web_search` | Searches the web for a query | | `fetch_content` | Loads a page from a link and extracts its text | | `get_search_content` | Retrieves the full text of search results | Search needs no key: when one free search engine refuses, the next is tried, three in turn. To use a search service of your own, put its key in `data/pi-agent/web-search.json` — a file that names a service or a key is left exactly as you wrote it. ## Helpers and schedules {#subagents} | Tool | What it does | | --- | --- | | `Agent` | Starts a helper — a separate agent for part of the work — and waits for its result. Several calls in one message run at the same time, up to six. With a schedule value it creates a [scheduled task](https://eggent.ai/docs/schedules.md) instead | | `get_subagent_result` | Collects a helper's result | | `steer_subagent` | Sends a running helper a correction | | `eggent_manage_schedules` | Lists, changes or cancels existing schedules. Actions: `list`, `update` (new timing `schedule`, new task `prompt` and/or `enabled` to pause or resume), `clear`. A scheduled run's own report may only `list`. Scope: `current` or `all` | Schedule time formats: cron with 5 or 6 fields (with 6, the first is seconds), an interval (`5m`, `1h`), a delay (`+10m`) or an ISO date. Schedule files must not be edited directly — only through this tool. ## Projects and the workspace {#workspace} | Tool | What it does | | --- | --- | | `list_projects` | Lists projects | | `create_project` | Creates a project: `name`, `description`, `instructions` | | `switch_project` | Switches to a project or to the orchestrator (`project_id: "none"`) | | `eggent_ask_project` | Hands a task to another project and waits for its answer. Works only for a project you named with `@` at the start of your message in this turn: the agent cannot start it on its own. See [Projects](https://eggent.ai/docs/projects.md#ask) | | `eggent_manage_chats` | Other chats: `list`, `search`, `read`; `switch` moves the conversation to another chat and `new` to a fresh one — in Telegram from the next message, in the browser as a link | | `create_skill` | Creates a [skill](https://eggent.ai/docs/skills.md): `skill_name`, `description`, `body` | | `upsert_mcp_server` | Adds or changes an [MCP server](https://eggent.ai/docs/mcp.md): `stdio` (`command`, `args`, `env`) or `http` (`url`, `headers`) | | `delete_mcp_server` | Removes an MCP server | | `mcp` | Calls the tools of connected MCP servers | ## Memory {#memory} | Tool | What it does | | --- | --- | | `eggent_memory_save` | Saves an entry to the current project's or orchestrator's [memory](https://eggent.ai/docs/memory.md) | | `eggent_memory_search` | Searches memory | | `eggent_memory_delete` | Deletes matching entries | ## Talking to the person {#communication} | Tool | What it does | | --- | --- | | `eggent_ask_user` | Shows a question card: options (`options`), yes/no (`confirm`) or a free answer (`free_text`). A field for a typed answer is always there beside the buttons | | `telegram_send_message` | Sends text to Telegram: to your own chat or to a channel (`chat`: `@channel`, a `t.me` link or a numeric id) | | `telegram_send_file` | Sends a file. An image goes as a photo with a caption, anything else as a document; `as_file` sends an image as a file | | `eggent_manage_telegram` | Manages your own bot: `status`, `connect`, `disconnect`, `allow_user`, `access_code`; in the cloud, `link_shared` links your Telegram to the shared bot | | `eggent_email` | The agent's [email](https://eggent.ai/docs/email.md): `send_email`, `list_emails`, `read_email`, `email_status`, `my_address` | | `eggent_google` | In the cloud, your [Google](https://eggent.ai/docs/google.md): `status`, `connect`, documents, sheets, slides, Drive files and folders, `share_link` (waits for your yes) | | `eggent_calendar_file` | Makes a calendar file (`.ics`) for an event, that opens in any calendar | ## Models and images {#models} | Tool | What it does | | --- | --- | | `eggent_manage_models` | `status` — the current model and providers; `add_provider` — connect an OpenAI-compatible provider (`provider_id`, `base_url`, `models`); `use_provider` — make a connected provider the default | | `eggent_generate_image` | Draws or edits an image: `prompt`, `reference_image_paths`, `aspect_ratio`, `size`, `quality`, `background`, `n` | | `eggent_usage_status` | Cloud only: remaining credits, days and disk, the current plan | ## Task board {#board} | Tool | What it does | | --- | --- | | `eggent_board` | The [task board](https://eggent.ai/docs/board.md): `list` and `get` read it; `create` writes cards (title, task, project, `after` — cards it waits for, `#1` being an earlier card of the same list) into the Inbox; `update` and `remove` change only cards still in the Inbox. The agent never starts a card: the person does | ## Working with colleagues {#company} Only in a workspace that belongs to a [company](https://eggent.ai/docs/company.md). | Tool | What it does | | --- | --- | | `eggent_messages` | [Messages](https://eggent.ai/docs/company.md#messages) with the company's people: `contacts`, `inbox`, `read`, `send` (marked as written by the agent), `describe` (remembers what a person does) | | `eggent_shares` | [Shared files](https://eggent.ai/docs/company.md#shares): `people`, `list`, `read` (the text of a shared file), `comments`, `comment` (in the person's name, on a quoted piece if given), `share` (adds people in a role - view, comment or edit - and never takes a file away). It cannot change a colleague's file | | `eggent_approvals` | [Approvals](https://eggent.ai/docs/company.md#approvals): `people`, `waiting`, `sent`, `read`, `text` (a version's text), `send` (a file to people in order), `withdraw`. It cannot approve or return a version: that is the person's | ## Skills as commands {#skill-commands} Any installed skill can be called explicitly: `/skill:` at the start of a message. The installed skills are listed in **Settings → Skills**. --- # HTTP API reference > Every Eggent HTTP address — which are open to integrations with a token, which need a web sign-in, and what they accept and return. Source: https://eggent.ai/docs/http-api/ Eggent has two kinds of HTTP addresses: - **The external API** (`/api/external/*`) — for integrations. Authorised with a token: `Authorization: Bearer `. In detail in [HTTP API for integrations](https://eggent.ai/docs/external-api.md). - **The web app API** — everything else. Needs a sign-in: the session cookie set by `/api/auth/login`. The interface itself uses these addresses; for automation, prefer the external API. Base URL: `https://name.cloud.eggent.ai` in the cloud, or your server's address. ## External API {#external} | Method and path | What it does | | --- | --- | | `POST /api/external/message` | Send a message, get an answer (JSON or an SSE stream) | | `POST /api/external/media-message` | The same with a file, `multipart/form-data` | | `POST /api/external/telegram/sent` | For a Telegram bot that sends the answers itself: `{"telegramChatId","messageIds","chatId"}` — which messages carried an answer from which chat, so a reply to them continues that chat | | `GET /api/external/token`, `POST /api/external/token` | See or issue the token (needs a sign-in) | ## Service {#service} | Method and path | What it does | | --- | --- | | `GET /api/health` | Health check: `{"status":"ok","timestamp":"…","version":"0.2.9"}`. No auth | | `POST /api/auth/login` | Sign in: `{"username":"…","password":"…"}` → session cookie | ## Projects {#projects} | Method and path | What it does | | --- | --- | | `GET /api/projects` | List projects | | `POST /api/projects` | Create: `{"name","description","instructions"}` | | `GET`, `PUT`, `DELETE /api/projects/:id` | Read, change, delete a project | | `GET`, `PUT /api/projects/:id/context` | The project's context (`context.md`) | | `GET`, `PUT /api/projects/:id/memory` | The project's memory (`memory.md`) | | `GET`, `PUT /api/projects/:id/model` | The project's model (`model.json`) | | `GET`, `DELETE /api/projects/:id/skills` | The project's skills. `DELETE` takes `{"name"}` and removes that skill, with the earlier versions kept when it was replaced | | `POST /api/projects/:id/skills/upload` | Upload one skill as a file (a multipart form: `file`, and `replace=1` to replace an installed one) | | `GET`, `PUT /api/projects/:id/mcp` | The project's MCP servers (`.mcp.json`) | For context, memory, skills and MCP, use `none` for `:id` to address the orchestrator. The orchestrator has no model of its own: it answers with the workspace model. ## What the agent has learned {#learning} | Method and path | What it does | | --- | --- | | `GET /api/learning` | The notes, the skills the agent wrote, and whether learning is on | | `POST /api/learning` | `{"enabled":true\|false}`, or add or remove one note: `{"action":"add","target":"user\|notes","content":"…"}`, `{"action":"remove","target":"user\|notes","text":"…"}` | ## Chats {#chats} | Method and path | What it does | | --- | --- | | `POST /api/chat` | Send a message from the interface (streaming) | | `GET /api/chat/history` | The chat list, or one chat's history | | `GET /api/chat/:id/stream` | Attach to an answer that is still being written | | `POST /api/chat/:id/stop` | Stop the work in a chat | | `GET`, `POST`, `DELETE /api/chat/files` | Chat attachments | ## Project files {#files} | Method and path | What it does | | --- | --- | | `GET /api/files` | Folder contents | | `GET /api/files/content` | A file's text | | `GET /api/files/download` | Download a file. With `inline=1`, open it in the browser, isolated | | `GET /api/files/zip` | A folder (`path=`) or several files (repeat `path=`) as one `.zip`; `check=1` answers what it would hold. Refused with 413 above the limits | | `GET /api/files/stat` | Which of the listed paths still exist | | `GET`, `POST /api/files/telegram` | Whether Telegram can be reached; send one file to your own chat | | `POST /api/files/upload` | Upload files and folders, `multipart/form-data` | | `DELETE /api/files` | Delete a file or folder | | `GET`, `DELETE /api/files/versions` | A file's [history](https://eggent.ai/docs/files.md#history) (`project`, `path`), or delete it | | `GET /api/files/versions/content` | The text of version `n` | | `GET /api/files/versions/download` | Version `n` as a file | | `POST /api/files/versions/restore` | `{ project, path, n, force? }` — restore version `n` as a new version | | `GET`, `POST /api/files/versions/usage` | How much the history takes; `{ "action": "clear", "olderThanDays" }` clears it | | `GET /api/files/page-link` | Where a [page](https://eggent.ai/docs/files.md#pages) is shown (`project`, `path`, `mode=edit\|print`), for a while | | `GET /api/files/page-element` | The block picked on a page: label, lines, source (`sha`, `el`) | | `POST /api/files/page-edit` | `{ project, path, sha, edits }` — words changed on a page, written where they came from | | `GET /api/files/page-print` | A file made ready to [save as PDF](https://eggent.ai/docs/files.md#pdf) | Upload parameters: `project`, `path`, `files` (repeatable), `relativePaths` (where each file goes, by position), `directories` (empty folders), `conflict` — `skip` (default), `overwrite` or `rename`. One request carries at most 100 MB, otherwise the answer is `413`. ```bash curl -X POST https://name.cloud.eggent.ai/api/files/upload \ -b cookies.txt \ -F "project=my-project" \ -F "path=." \ -F "conflict=rename" \ -F "files=@./notes.md" ``` ## Task board {#board} Writes need a session from the same site and a JSON body, like the terminal's routes. | Method and path | What it does | | --- | --- | | `GET /api/board` | Every card, whether the board is paused, which cards are being worked on; `?archived=1` includes cards put away | | `GET /api/board/summary` | How many cards wait for you, run and are queued | | `POST /api/board/cards` | A new card: `title`, `body`, `projectId`, `after`, `review`, `start` | | `GET`, `PATCH`, `DELETE /api/board/cards/:id` | One card; `PATCH` edits it or moves it with `{ "move": { "to": "inbox" \| "queued" \| "done" \| "archived" \| "unarchived", "position" } }` | | `POST /api/board/cards/:id/answer` | `{ "text" }` — the answer to the card's question | | `POST /api/board/cards/:id/stop` | Stop it; a queued card goes back to the Inbox | | `POST /api/board/start-all` | Every Inbox card (of `projectId`, when given) into the queue | | `POST /api/board/resume` | Let the board go on after the model service refused | ## Company {#company} Only in a workspace that belongs to a [company](https://eggent.ai/docs/company.md). Writes need a session from the same site and a JSON body. | Method and path | What it does | | --- | --- | | `GET /api/mail/contacts` | The company's people and unread messages | | `GET /api/mail/thread` | The thread with a person (`with`, `before`, `limit`) | | `POST /api/mail/send` | `{ to, text, files?, replyTo? }` | | `POST /api/mail/read` | `{ with, upTo }` — mark read | | `POST /api/mail/assign` | `{ messageId }` — open a chat with the agent about a message | | `GET /api/mail/attachments/:id` | A file from a thread | | `GET /api/shares` | Files shared with you and files you shared | | `GET /api/shares/people` | Who a file can be shared with | | `GET /api/shares/file` | One of your files and who it is shared with (`project`, `path`) | | `POST /api/shares/share` | `{ project, path, people: [{ id, role }] }` — the list given is everybody who has it | | `GET /api/shares/:id`, `GET /api/shares/:id/text` | A shared file: who has it, and what it holds | | `GET`, `POST /api/shares/:id/content` | The file; `{ baseSha, text }` changes its text onto that version | | `POST /api/shares/:id/page-edit` | `{ sha, edits }` — words changed on a shared page | | `GET`, `POST /api/shares/:id/comments` | Comments; `{ body, quote?, anchor?, replyTo? }` | | `POST /api/shares/:id/comments/:comment/resolve`, `/delete` | Resolve (`{ resolved }`) or delete a comment | | `POST /api/shares/:id/stop` | Stop sharing | | `GET /api/approvals` | Approvals: `box=waiting\|sent\|involved` | | `GET /api/approvals/file` | One of your files and its approval (`project`, `path`) | | `POST /api/approvals/send` | `{ project, path, approvers, note? }` — the version the file holds now | | `GET /api/approvals/:id` | One approval with its rounds | | `POST /api/approvals/:id/decide` | `{ round, decision: "approve" \| "reject", comment? }` | | `POST /api/approvals/:id/cancel` | Withdraw | | `GET /api/approvals/:id/rounds/:round/file`, `/text` | A round's version, as a file or as text | ## Schedules {#schedules} | Method and path | What it does | | --- | --- | | `GET /api/pi-schedules` | Every scheduled task across the projects and the orchestrator, with whether and why one is paused | | `POST /api/pi-schedules` | Change one task: `{"action": "pause" \| "resume" \| "retime" \| "delete", "jobId": "…"}` (`retime` also takes `schedule`) | --- # Workspace layout > The folders and files an Eggent workspace is made of — projects, the orchestrator, chats, attachments, settings, schedules — and which of them you may edit by hand. Source: https://eggent.ai/docs/workspace-layout/ All of a workspace's state is ordinary files in the `data/` folder. In the cloud it lives on the server; on your own server, next to the installation. The agent works inside `data/projects/`. ## Overview {#overview} ```text data/ ├── projects/ # the orchestrator's files and every project ├── chats/ # chat history ├── chat-files/ # chat attachments, one folder per chat ├── settings/ # settings, the API token, the sign-in secret ├── board/ # the task board: one file per card ├── versions/ # versions of files: what each held before every change ├── memory/ # memory's internal data ├── learning/ # internal: counters and a journal of what the agent learned ├── models/whisper/ # the speech recognition model └── pi-agent/ # the runtime: keys, models, packages ``` ## The orchestrator and projects {#projects} ```text data/projects/ ├── context.md # the orchestrator's context ├── memory.md # the orchestrator's memory ├── learned.md # short notes the agent keeps about you and the work ├── skills/ # the orchestrator's skills, including ones the agent wrote │ └── .archive/ # learned skills nobody has used for a long time ├── .mcp.json # the orchestrator's MCP servers ├── Messages/ # in a company: files from each thread, one folder per person ├── .shared/ # in a company: company folders given to you (not in the history) │ └── / ├── project.json # the project's name and description ├── context.md # the project's context ├── memory.md # the project's memory ├── model.json # the project's own model (if set) ├── skills/ # the project's skills ├── .mcp.json # the project's MCP servers ├── .pi/ # internal: schedules and state ├── generated-images/# images the agent drew └── … # the project's files ``` A project's folder is its working folder: the agent reads and writes files here, and the **Files** panel shows the same folder. ## What you may edit by hand {#editable} | File | OK? | Best done via | | --- | --- | --- | | `context.md`, `memory.md` | Yes | **Settings → Context / Memory**, or ask the agent | | `learned.md` | Yes | **Settings → Memory → What the agent has learned**: one note per line, starting with `- ` | | `skills//SKILL.md` | Yes | Any editor, the agent or the **Files** panel | | `.mcp.json` | Yes | **Settings → MCP** | | `model.json` | Yes | **Settings → Models**, scope set to the project | | `.pi/subagent-schedules/*` | **No** | Only through the agent: "move the task…". Editing by hand breaks a running schedule | | `data/settings/*`, `data/pi-agent/auth.json` | No | Through the settings interface | ## Where secrets live {#secrets} - Model provider keys — `data/pi-agent/auth.json`. - The external API token and the sign-in secret — `data/settings/`. - MCP server tokens — in the project's or orchestrator's `.mcp.json`. - The Telegram bot token — `data/settings/telegram-integration.json`. Credentials that were pasted into a chat or printed by a tool are masked in the stored chats under `data/chats/`; `data/secrets-sweep.json` records that the one-time cleanup of older chats has run. The runtime's own session files under `data/pi-sessions/` are the agent's memory and are not changed. When backing up or moving a workspace, treat the whole `data/` folder as a secret. --- # Common problems > What to do when the agent does not answer, cannot see a file, uses the wrong model, the Telegram bot is silent, a schedule did not run, an upload fails or the first message is slow. Source: https://eggent.ai/docs/troubleshooting/ ## The agent does not answer {#no-answer} - **Credits have run out.** The agent sends a message with a link to billing. Check the balance on the billing page, or ask "how much do I have left". See [Plans and balance](https://eggent.ai/docs/plans.md#out-of-credits). - **The disk is full.** Delete what you do not need in the **Files** panel — work resumes from the next message. See [Disk space](https://eggent.ai/docs/plans.md#storage). - **The trial or plan has ended.** A page with the plans opens in place of the workspace. Your data is kept. - **A provider error on your own key.** Eggent shows exactly what is wrong: the address does not answer, the key was rejected or there is no such model. Check the key in **Settings → Models** or [switch back to Eggent AI](https://eggent.ai/docs/models.md#back). ## The first message takes 10 seconds {#slow-first} The workspace was [asleep](https://eggent.ai/docs/sleep.md) and is waking up. This is normal and only happens after a long break. ## The agent cannot see a file {#file-not-visible} - The file must be **in the current project** or attached to **this chat**. The agent sees another project's files only after switching there. - Check which project the chat is in: the project's name is highlighted in the sidebar. - Say it explicitly: "read `reports/q3.xlsx`". ## The wrong model answers {#wrong-model} - The line left of the send button shows which model will answer **the next** message. - A project can have its own model. Check **Settings → Models** with the scope set to the project. - If the saved model is unavailable (its provider is disconnected, or the model is locked on the current plan), the default model answers. ## The agent cannot press a button on a site or sign in {#no-browser} The agent has no browser with a screen: it reads pages as text and works with APIs. If the service has an API or an MCP server, connect it. See [What the agent can do](https://eggent.ai/docs/capabilities.md#limits). ## The Telegram bot is silent {#telegram-silent} - The bot answers only in **private messages**. - For your own bot, your `user_id` must be on the allowlist — send the bot `/code ` with a code from **Settings → Messengers**. - Check that the bot is active in **Settings → Messengers**. If the token changed, paste the new one and press **Activate Bot**. See [Telegram](https://eggent.ai/docs/telegram.md#troubleshooting). ## A schedule did not run {#schedule-missed} - Check the next run time in **Settings → Schedules**: time follows the server clock (usually UTC). - Missed runs are not repeated: if the server was off at that moment, the task runs next time. - If credits have run out, the run cannot go through - and after three refusals in a row the task is paused. See [A task that cannot run](https://eggent.ai/docs/schedules.md#paused). - Look at the chat where the schedule was created: results and errors arrive there. ## The Telegram answer hangs {#telegram-stuck} Send `/reset`: it stops the answer that seems stuck and keeps the conversation. See [An answer that seems stuck](https://eggent.ai/docs/telegram.md#stuck). ## `@project` was answered as an ordinary message {#ask-project} The name after `@` matches no project, or the message has nothing after the name. Check the spelling against the project list — capitals, hyphens and ё/е do not matter. It also does not work in a [light chat](https://eggent.ai/docs/chats.md#modes) or a shared public chat. If the project did the work but is missing something it should have, such as a connected service, open the project's own chat once and approve the service there. See [Asking a project](https://eggent.ai/docs/projects.md#ask). ## A file upload fails {#upload-fails} - One file is at most 100 MB. - Check the disk space. - On your own server behind a proxy: raise the proxy's request body limit to 100 MB. See [Reverse proxy](https://eggent.ai/docs/self-host-config.md#reverse-proxy). ## The microphone does not work {#microphone} Browsers allow the microphone only over `https://` or on `localhost`. Check the microphone permission in the browser's site settings. ## Forgot the password {#password} Press **Forgot your password?** on the sign-in page and enter the email the workspace is registered to: a letter brings a link for each workspace of that address, good once and for an hour. Signed up in Telegram? `/login` in the bot signs you in without a password. Nothing came? Look in spam, then write to [support](https://eggent.ai/docs/account.md#support). See [Forgot the password](https://eggent.ai/docs/account.md#reset). ## Nothing helped {#support} Write to support: Telegram [@youriisupport](https://t.me/youriisupport) or [aiiszdes@gmail.com](mailto:aiiszdes@gmail.com). Include the workspace address, what you did and what you saw — a screenshot speeds up the answer a lot. --- # For agents > How a language model or an agent should read these docs — machine-readable pages, llms.txt, stable addresses, and which pages answer which questions about Eggent. Source: https://eggent.ai/docs/for-agents/ These docs are written to be read by agents as well as people — including Eggent itself, when it needs to learn more about itself. ## Machine-readable versions {#machine-readable} | What | Address | | --- | --- | | Every page with its description | [`/docs/llms.txt`](/docs/llms.txt) | | The whole documentation in one file | [`/docs/llms-full.txt`](/docs/llms-full.txt) | | One page as Markdown | `/docs/.md`, for example [`/docs/schedules.md`](/docs/schedules.md) | | The same in Russian | [`/r/docs/llms.txt`](/r/docs/llms.txt), `/r/docs/.md` | | Index of both languages | [`/llms.txt`](/llms.txt) | Every HTML page has a `` in its `` pointing at its Markdown version. ## Stable addresses {#stable-urls} - A page's address is the same in both languages: `/docs//` and `/r/docs//`. - Sections within a page have permanent Latin anchors, the same in both languages: `/docs/chats/#modes` and `/r/docs/chats/#modes`. - Links inside the Markdown versions point to the Markdown versions of other pages. ## Which page answers which question {#map} | Question | Page | | --- | --- | | What a project, the orchestrator, a skill, memory are | [concepts](https://eggent.ai/docs/concepts.md) | | The agent's tools and their parameters | [agent-tools](https://eggent.ai/docs/agent-tools.md) | | What the agent can and cannot do | [capabilities](https://eggent.ai/docs/capabilities.md) | | Chat modes, stopping, steering mid-task | [chats](https://eggent.ai/docs/chats.md) | | Creating or changing a schedule, time formats | [schedules](https://eggent.ai/docs/schedules.md) | | Connecting Telegram, channels, access codes | [telegram](https://eggent.ai/docs/telegram.md) | | Models, your own key, a project's model | [models](https://eggent.ai/docs/models.md) | | Ready-made skills and cards | [skill-catalog](https://eggent.ai/docs/skill-catalog.md) | | Writing skills | [skills](https://eggent.ai/docs/skills.md) | | Where things are on disk | [workspace-layout](https://eggent.ai/docs/workspace-layout.md) | | Plans, credits, disk | [plans](https://eggent.ai/docs/plans.md) | | The external API and streaming | [external-api](https://eggent.ai/docs/external-api.md) | | Common problems and fixes | [troubleshooting](https://eggent.ai/docs/troubleshooting.md) | ## Advice for the Eggent agent {#for-eggent} - When a person asks how something works in Eggent, read the relevant page first rather than guessing. - When answering, rely on your own tools: their exact names and parameters are in your tool list, and their descriptions in the [reference](https://eggent.ai/docs/agent-tools.md). - Take screen and button names from the docs: they match the interface in the person's language. - The docs cover both the cloud and the open core. If the workspace is self-hosted (no Eggent AI, no shared bot), the cloud sections do not apply to it.