Pumaï — User Guide

A getting-started guide to the web interface, written for the user, with no technical prerequisites. Application state verified on 1 August 2026.

Pumaï is not a chatbot. It is an assistant that can not only answer, but act: browse the web, handle a mailbox, produce files, generate images, administer a server, publish content, call an API, or run a mission autonomously while you do something else.

What it can do depends entirely on what you give it: tools, access, instructions and a control framework. This guide explains how to go from a concrete need to a reliable automation, using only the web interface. The API is presented at the end as a complementary way in.

How to read this guide. If Pumaï is new to you, read chapters 1, 2 and 3 in order: that is the shortest path to a first automation that actually works. Chapters 4 to 6 are reference material, to consult as needed. Chapters 7 to 12 are recipes, writing advice and troubleshooting.

Contents

1. Understanding Pumaï in five minutes
2. First setup, step by step
3. Chat, scheduled task, Pulsar or batch?
4. Profiles and data sharing
5. Tools, skills, connectors and channels
6. The interface, page by page
7. Automation recipes
8. Writing a good instruction
9. Controlling actions and costs
10. Using Pumaï through the API
11. Troubleshooting
12. Glossary

1. Understanding Pumaï in five minutes

1.1 The simplest mental model

Imagine hiring a small team. Before it can work, you have to give it an identity, the means to act, instructions and a framework. Pumaï works exactly the same way:

• a profile defines who works: personality, memory, rights;
• a tool gives it a way to act: send an email, search the web, create a PDF;
• a skill tells it how to go about a recurring type of task;
• a trigger decides when it works: your message, a time of day, a monitoring round, or a production queue;
• action control decides whether an action must wait for your approval;
• Activity, Logs and the Cabinet let you verify what was done.

So the usual path is:

Need → Profile → Tools and skills → Trigger → Optional approval → Result → Verification

A concrete example. "Check my server's health every morning" becomes:

Profile "Supervision"
  + an authorised SSH connection, restricted to read-only commands
  + a scheduled task at 08:00
  + a precise diagnostic instruction
  + delivery by email
  + verification in Activity and Logs

Remember this sentence: Pumaï does not guess your access. Until you have configured a mailbox, it cannot read your messages, however politely it tells you it will take care of it. Chapter 2 exists precisely to give it those means.

1.2 What Pumaï actually does when you give it a task

Depending on the request, Pumaï picks one of these paths on its own:

1. answer directly, when no action is needed;
2. go and check something read-only, then answer;
3. build a plan and split the work between several specialised agents working in parallel;
4. use the tools you have authorised;
5. produce a result, a file, an image or an external action;
6. pause a sensitive action to ask for your approval.

You do not have to choose: the orchestrator decides, based on the meaning of your request. What you set is the effort level: the higher it is, the more Pumaï can break the work down, delegate and proofread itself — but the longer and more expensive the task becomes.

1.3 The areas of the interface

The top menu groups the pages into six families.

Three further pages are worth knowing early: Mail (the assistant's mailbox), Cabinet (durable documents) and To approve (actions waiting for your decision).

1.4 The global automation switch

At the top of the interface, an ON/OFF switch suspends or resumes all automations at once:

• scheduled tasks;
• Pulsar missions;
• running batches.

Use it before maintenance, during a configuration phase, or as an emergency brake if an automation misbehaves. It does not disable tasks individually, and it does not prevent you from using the Chat manually — it is an emergency brake, not a master switch for the application.

1.5 The four ways to put Pumaï to work

This is the most important point in the guide, and the one that causes the most mistakes. There are four ways to trigger work, and they are not interchangeable.

Chapter 3 covers each in detail. If you remember only one thing: the Pulsar remembers from one round to the next, the scheduled task starts from a blank page every time, and the batch waits for no clock — it runs straight through.

2. First setup, step by step

This is the longest chapter, and rightly so: nearly every difficulty in getting started comes from an incomplete configuration. Follow the order below; it avoids the dead ends.

2.0 What to prepare before you start

Set aside half an hour and have the following at hand:

1. An email address dedicated to the assistant. Not yours: one of its own. See 2.4 — this is the step that needs the most preparation, because the address must be created at a mail provider before you can enter it here.
2. An account with an AI model provider, unless your instance already comes with credits. This is what lets Pumaï think. Depending on your plan this may already be handled for you: check the Credits page.
3. A web search key, if you want the assistant to be able to search the internet. See 2.5.
4. Your login details for the interface, provided when the instance was created.

You do not need all of this on day one. An assistant with no mailbox and no web access already works very well for conversation, for analysing a document you upload, and for producing files. You can add access as you go.

2.1 Step 1 — The owner record

Open Memory & Profile → Profiles. At the very top of the page, before you select a profile, there is an Instance owner card. Fill in:

• your name;
• your email address;
• your role or job title;
• your phone number, if useful.

This record describes the person Pumaï serves. It is shared by every profile, and it has two very concrete effects: it is the address notifications meant for you are sent to, and it is what stops the assistant from mistaking you for a customer.

Do not confuse this record with a directory entry: the directory lists your contacts; the owner record is you.

2.2 Step 2 — The assistant and its business context

Open Memory & Profile → Assistant. Here you describe the general framework the assistant works in:

• its display name;
• its main role;
• its overall mission, in a few sentences;
• three to six priority objectives;
• its communication style;
• its guardrails — what it must never do;
• your company directory, if you need one.

Write these fields the way you would for a new hire. "You are the assistant of a six-person architecture practice; you reply in English, politely but without flattery; you never promise a deadline or a price that is not in our documents" is far more useful than three keywords.

This page describes the general framework. The operational settings specific to each agent (model, temperature, allowed tools) live in Profiles.

2.3 Step 3 — Profiles

A profile is a complete working identity, with its own memory and rights. Do not create a profile for every small task: create one when an activity needs at least one of these:

• a different personality;
• a separate memory;
• a particular set of tools;
• a different level of autonomy;
• a clearly distinct job or channel.

A starting structure that works well:

• Main assistant — Conversation type, the one you talk to in the Chat;
• Office — Autonomous type, for mail and case follow-up;
• Watch — Autonomous type, for monitoring and reports.

Chapter 4 covers profiles and, above all, what they do and do not share.

2.4 Step 4 — Giving the assistant a mailbox

This is the most structuring step, and the one that needs the most explanation. Take your time.

Why its own address, and not yours

An assistant that handles mail needs its own address, for three reasons:

1. Traceability. You must be able to tell at a glance what you wrote from what the assistant wrote. With a shared address that is impossible.
2. Security. You are entrusting it with a mailbox password. If that is your personal mailbox, you are handing over all your private correspondence, your password resets and your personal documents.
3. Reversibility. The day you want to stop, you close one address. You do not have to change the password to your digital life.

Good practice: an address in the assistant's name on your own domain, such as assistant@ your-domain, or a dedicated free address if you do not have a domain.

Creating the address and collecting its settings

Create the address with the mail provider of your choice — the one hosting your domain name, or a consumer service. Then, in that mailbox's settings, check two things.

1. That IMAP access is enabled. IMAP is the protocol that lets an outside program read a mailbox. Some providers disable it by default; you then have to turn it on, usually under a section called "external access", "mail clients" or "POP/IMAP".

2. That an app password is available. Most serious providers no longer accept the account password for external access: they ask you to generate an app password, a secondary password reserved for one specific program. That is the one you will give to Pumaï. The benefit matters: it gives no access to the account settings, and you can revoke it without changing your main password.

Then note the four technical settings your provider publishes in its help pages, usually under "IMAP and SMTP settings":

Do not try to understand these values: copy the ones your provider gives. If its help offers several options, always choose the encrypted variant (SSL or TLS), never the "insecure" one.

Entering these details in Pumaï

Open System → Tools. Tools are grouped by family; find the mail family and open the corresponding bundle. A tool card shows a clear badge: ✔ Configured or ⚠ Not configured.

Expand the configuration section and fill in:

• the incoming server and port (IMAP);
• the outgoing server and port (SMTP);
• the account username — usually the full email address;
• the app password obtained in the previous step;
• the sending address, i.e. the address that will appear as the sender.

Save, then enable the tool with its switch.

Deciding what it is allowed to send

Two settings, on the same card, govern sending. They are the most important of the whole setup, because they are what stops an AI from writing to just anyone.

The list of authorised recipients. This is a right to send, not merely a filter: an address on this list can receive a message; an address that is absent cannot. Start with your own address and nothing else. You can widen it later.

The sending policy, which takes two values:

• Draft — the assistant can never send anything itself. Everything it writes is placed in the mailbox's drafts, and you decide. This is the recommended setting to begin with.
• Direct send — a message to an authorised address is really sent; a message to any other address automatically becomes a draft, and the assistant tells you plainly that it did not send.

There is no configuration in which Pumaï writes to an address you have not authorised. If you empty the list, nothing goes out.

Checking that it works

Open the Mail page. If the configuration is correct, you will see the mailbox's real folders and messages. If the page stays empty or shows an error, go to chapter 11, "No email shows up".

Then try it from the Chat: "Summarise the last three messages I received." If it summarises them, reading works. Then: "Draft a reply to the last message, do not send it." The draft should appear on the Mail page.

2.5 Step 5 — Giving it web access

By default the assistant cannot search the internet. There are two ways, and they are not equivalent.

Search-engine search. It queries a real search engine and returns a list of results. It requires an API key from the engine's provider — the search tool shipped with Pumaï uses the Brave Search API. The principle is always the same:

1. create an account on the search provider's website;
2. subscribe to its API offering (there is usually a free tier that is more than enough for an assistant);
3. copy the key it gives you — a long string of characters;
4. in System → Tools, open the web search tool's card, paste the key into the field provided, save, enable.

Page reading. The tool that fetches the contents of a specific web address needs no key at all. If you do not need search but only need to follow pages you already know, it is enough.

What is an API key? A password meant for a program rather than a human. The provider generates it, you paste it into Pumaï, and it identifies your account when the service is called. Like any password, it is not shared, not put in a message, and revoked if it leaks.

2.6 Step 6 — Other tools: the principle is always the same

You have just configured two tools. Every other tool follows exactly the same logic, which makes the rest much quicker.

On the System → Tools page:

1. find the tool — tools are grouped by family: mail, web, files, memory, notifications, images, system, directory…;
2. read its description — it says what it really does, which prevents a lot of misunderstandings;
3. fill in its configuration, if it needs one. A badge shows ✔ Configured or ⚠ Not configured;
4. enable it — a disabled tool is not offered to the assistant at all; it can neither use it nor even know it exists;
5. decide whether it must ask for your approval — the "Ask for my approval" switch pauses every use of that tool until you decide;
6. if needed, restrict it to certain profiles from Profiles → Settings.

Some examples of needs and the matching tool:

One principle to remember: enable only what you need. Every enabled tool is described to the assistant, which takes up room in its reasoning and offers it one more temptation. An assistant with six well-chosen tools works better than one with forty.

2.7 Step 7 — Choosing the level of control

Open the To approve page. At the top is the global mode:

• Supervised mode — the tools on which you enabled "Ask for my approval" stop before acting and file a proposal you must accept or reject;
• Autonomous mode — everything runs without going through that queue, but everything is still logged.

For a first deployment, stay in supervised mode, and put under approval anything that affects the outside world: sending mail, publishing, changing something on a remote server, deleting, calling an API that commits you to something.

You will relax this control gradually, tool by tool, after seeing several correct runs. It is safer, and above all more instructive: the proposals you reject show you exactly where your instruction was ambiguous.

2.8 Step 8 — Test in the Chat before automating

Never schedule an automation you have not first run by hand. Open the Chat, select the profile the automation will use, and give it exactly the same instruction. Check:

• that the required tool is available;
• that the credentials work;
• that the result has the right format;
• that the right recipient, target or folder is used;
• that approval requests appear as expected.

A test in the Chat costs two minutes. A badly configured scheduled task can get it wrong every night for a week before you notice.

2.9 Step 9 — Automate, then verify

Now create the scheduled task, the Pulsar or the batch (chapter 3), trigger a first manual run, then check:

• Activity for the business result;
• the history of the task, mission or batch;
• To approve for suspended actions;
• Mail if a message was meant to go out;
• Cabinet if a file was meant to be kept;
• Logs if something went wrong technically.

2.10 The first-hour checklist

• [ ] Owner record filled in
• [ ] Assistant described: role, mission, style, guardrails
• [ ] At least one profile created
• [ ] Dedicated mailbox created at a provider, IMAP enabled, app password generated
• [ ] Mail bundle configured and tested from the Mail page
• [ ] Authorised recipients limited to your address only
• [ ] Sending policy set to Draft
• [ ] Web search configured if needed
• [ ] Supervised mode on, approval required for external actions
• [ ] One successful round trip in the Chat
• [ ] A first automation created, run manually, and verified

3. Chat, scheduled task, Pulsar or batch?

3.1 The four modes in one sentence each

• The Chat is a conversation. You ask, it acts, you watch, you correct.
• The scheduled task is an appointment. At a given time, a given instruction runs — and it starts from a blank page every time.
• The Pulsar is a patrol. At regular intervals it goes and looks, compares with what it saw last time, and only disturbs you if there is something new.
• The batch is a production queue. You give it a list, it works through it end to end without waiting for any clock, and stops when the list is empty.

3.2 The decision tree

Do I want the result now, in front of me?
   └── yes → CHAT

No. Is it a list of items to produce?
   └── yes → BATCH

No. Do I only want to be told if something changes?
   └── yes → PULSAR
   └── no  → SCHEDULED TASK

3.3 The scheduled task in detail

This is the easiest mode to understand: one instruction, one schedule, one result.

Use the Scheduler for:

• a report every morning;
• a reminder on a given date;
• a publication every Monday;
• a routine operation every two hours;
• a one-off action in the future.

Three ways to set the trigger:

• Cron — a fixed time, optionally on certain days only. "Every day at 8 am", "every Monday at 9:30";
• Interval — every X hours, minutes or seconds;
• Single date — one run, at a precise date and time.

The key point: a scheduled task has no memory of its past runs. It starts fresh every time. If you ask it to "report new messages", it has no way of knowing what was already there yesterday: it will report them all, every day. That need is exactly why the Pulsar exists.

3.4 The Pulsar in detail

A Pulsar is a mission that lives over time. On each pass — called a tick — it does its job, then writes itself a short summary of what it observed: that is its state. On the next pass it re-reads that state, compares it with what it sees, and decides whether there is anything worth telling you.

That memory between passes makes all the difference. It allows instructions like: "tell me only if a new competitor appears", "follow this incident until it is resolved", "alert me when this price drops below a threshold".

The three mission types:

• Permanent — it continues as long as you leave it active;
• Conditional — it ends by itself when a condition has held long enough;
• Time-limited — it is archived on an expiry date.

The mission's nature, set by the Mission nature field:

• Watch — monitor and report (the default). The protocol requires a fresh collection, a comparison with the previous state, and a notification when something is detected.
• Production — make artefacts. This protocol suits a mission that produces something on each pass — a sheet, an image, a document — working through a list. Collection and comparison make no sense there and are not imposed, and there is no notification every time.

Mind the effort level of a production mission. At Low effort the assistant works alone and without tools: it will therefore be unable to make anything. For a mission that must actually call tools, choose Medium at minimum.

What a mission card shows: the last pass, the verdict, a summary, and cumulative consumption. The Logs button shows the history; the State button shows what the mission remembers between passes — that is the first place to look when a mission behaves oddly.

Two buttons worth knowing:

• ⚡ Run now — runs this mission immediately, without waiting for its next due time. It bypasses the cadence and the cool-down after an error, but it respects the stops you asked for: if automations are paused, or if the mission is paused, it refuses and tells you why.
• 🏗 To batch — appears only on a Production mission. It copies the mission's settings into a batch form; it creates nothing by itself. See 3.6.

A ⌛ badge on a card means the mission will not run on the next wake-up, and the card says why (it is paused, its cadence is not due, or it is waiting after an error).

3.5 The batch in detail

A batch produces a series of items in one go. You give it a production instruction and a list; it makes item after item until the list is empty.

What really distinguishes it from a production Pulsar is that it waits for no clock. A Pulsar makes one item per round; if your instance patrols every three hours, 36 items take four and a half days. The same work given to a batch runs straight through.

The second difference is less visible but just as important: the list lives in the batch, not in the instruction. The software keeps track of what is done and what remains — not the assistant, which could forget or get it wrong. That is what makes it possible to show a "12 / 36" bar, to re-run precisely item number 7 that failed, and to know with certainty that the batch is finished.

The two batch modes:

• List — you enumerate the items to produce, one per line. The batch knows the total, shows exact progress, and stops on its own when the list is exhausted. Use this mode whenever you can write the list.
• Open — you give no list, only a number of iterations. The content is invented along the way. The batch stops at the requested number, or earlier if the assistant declares there is nothing left to produce.

The production instruction and the {{item}} placeholder. You write a single instruction, valid for every item, and you place {{item}} where the item should appear:

MISSION — produce a colouring page of {{item}}.
Black inked line art, light background, A4 portrait.
File the result in the Cabinet with the tag "colouring".

You can also use {{rank}} for the item's number. If you forget {{item}} it is not a problem: the item is appended to the instruction in a dedicated block.

The guardrails. A batch commits real spending, in series. Three settings bound it:

• the cost cap — the batch stops as soon as spending reaches that amount;
• the token cap — the same idea, counted in units of work rather than money. Useful because some model providers do not publish their prices, in which case the displayed cost stays at zero and a money cap would be useless;
• the number of consecutive failures tolerated — beyond it, the batch stops instead of persisting.

A fourth setting, the pause between items, helps when your provider rate-limits calls.

A batch does not start on its own. You review the list and the estimate, then click Start. Likewise, after a server restart a running batch is paused and waits for you: nobody wants a machine to resume thirty paid generations by itself.

When it stops, it always says why: queue empty, the agent declared it finished, cost cap reached, token cap reached, too many consecutive failures, quota exhausted, stop requested, automations paused, or server restart. A batch stopped by a cap keeps its remaining items pending: raise the cap and restart, nothing is lost.

3.6 The most common mistake

You want thirty illustrations, or forty product sheets, or a series of documents. The natural reflex is to create a production Pulsar and let it run. Do not:

• it only makes one item per round, and the round cadence is shared with all your other missions — you cannot speed it up without speeding everything up;
• nothing stops it: when the list is finished it keeps waking up, thinking, and concluding there is nothing to do — each time at a real cost;
• the assistant has to remember what it has already produced, and it can get that wrong.

The batch was designed for exactly this case. If you already have a production mission running, the 🏗 To batch button on its card copies its settings into a batch form: all you have to do is paste the list.

Conversely, do not put a watch into a batch: monitoring has no list and never ends — that is a Pulsar.

3.7 Frequencies and cadences

The general round cadence is set in System → Dev → Pulsar cadence. It is the rhythm at which Pumaï wakes up to look at its missions.

Each mission can then refine it:

• Every tick — on every general round;
• Hourly or Daily — an extra filter;
• Custom interval, in minutes, which takes priority. For example 360 for six hours, 1440 for a day, 10080 for a week.

Avoid very short frequencies for information that rarely moves: every pass consumes credits and calls external services. A competitor watch running every five minutes learns nothing more than a daily one, and costs 288 times as much.

3.8 The effort level

Effort sets the depth of the work: how many agents can be involved, how many back-and-forths they allow themselves, and whether they proofread.

Two classic traps:

• Low is perfect for a watch that looks and concludes, but it forbids all delegation: work that must call tools to make something will not manage it. Use Medium at minimum.
• Very high on a frequent task costs a great deal for often no benefit. Keep it for one-off, important productions.

3.9 Quality control before delivery

All three forms — scheduled task, Pulsar and batch — offer a Check consistency before delivery checkbox (called Quality control before delivery on batches).

When it is ticked, the agent that has just produced the deliverable re-reads it before concluding: it looks for inconsistencies — dates that contradict each other, figures that do not add up, promises that go beyond the instruction — and fixes the offending passages. It does not rewrite everything; it corrects.

Use it whenever a deliverable is going to leave your organisation: a report sent to a client, a published document, a sheet handed over. It is pointless for a watch that only produces one line of verdict.

This setting is independent of the effort level: you can have quality control at Medium effort, without paying for the depth of High.

3.10 Choosing delivery

A scheduled task can deliver its result by email, by Telegram, in the web interface, or nowhere — in which case the result remains readable in the logs.

The channel must be configured before the first run. Choosing "Telegram" in the form does not create the bot; choosing "email" does not create the mailbox. The form lets you select a channel that does not exist yet, and the error will only surface at run time.

4. Profiles and data sharing

4.1 What is a profile?

A profile is a complete working identity. It has:

• a type, Conversation or Autonomous;
• an identity and a personality;
• a "soul", meaning its voice and stance;
• a durable memory of its own;
• daily notes and nightly consolidations;
• a directory;
• open cases and an internal inbox;
• a model, a temperature and a time zone;
• a list of allowed tools;
• an approval mode;
• read rights on other profiles' data.

4.2 Conversation profile and Autonomous profile

A Conversation profile is for direct exchanges. In the interface you choose it from the Chat. For Telegram or Discord, the channel relays to a chat session which itself carries a profile.

An Autonomous profile is for scheduled tasks, Pulsars and batches: office assistant, watcher, analyst, technical supervisor.

The type helps organise usage; the exact profile is still chosen explicitly in the Chat, the Scheduler, the Pulsar, the batch or the phone configuration.

4.3 A profile's tabs

4.4 The sharing rule between profiles

By default, profile memories are isolated. In the Sharing tab you authorise the selected profile to read another profile's durable memory and recent notes.

Sharing is one-way:

A is allowed to read B   ≠   B is allowed to read A

If "Office" must consult "Main assistant"'s memory, open Office → Sharing and tick "Main assistant". Only tick the other direction if the need genuinely exists.

Personality, soul and the consolidation journal always stay private to the profile.

4.5 Shared data

Some data deliberately escapes that isolation:

• the owner record is shared by the whole instance;
• the Cabinet is a central document space shared by all profiles;
• documents on the Cabinet's Reference shelf can be consulted by every agent;
• the Archive shelf keeps files without making them searchable;
• the main directory can serve as cross-cutting business context for autonomous profiles.

Practical consequence: do not put a confidential document in the Cabinet of an instance used by several activities that must stay separate. Put it in the relevant profile's memory, or use a separate instance if the boundary has to be strict.

4.6 Allowed tools per profile

In Profiles → Settings → Allowed tools:

• an empty list means "all globally enabled tools";
• a filled list becomes a strict allowlist.

A watch profile only needs the web, memory, files and notifications. It has no reason to hold a deletion or system administration tool.

4.7 Approval mode per profile

Each profile can inherit the global setting, be supervised, or be autonomous. Keep new or risky activities supervised, and increase their autonomy after checking several correct runs.

5. Tools, skills, connectors and channels

5.1 The four notions

These four words answer four different questions, and confusing them is a frequent source of error.

5.2 Tools

A tool is an executable function. The Tools page lets you see what it is for, enable or disable it, check whether it is configured, require approval before each use, see its risk level, and restrict it per profile.

Tools are grouped into families (or bundles): mail, web, files, memory, notifications, images, system, directory, scheduling, monitoring.

Two tools deserve a special mention, because they are recent and change the way you work:

Image generation. The assistant can create an image from a description. Three things to know: the model used is chosen in System → Dev, and its price is shown in the selector; the number of images produced per run is capped, to avoid unpleasant surprises; and to obtain a consistent series — the same style from one drawing to the next — you must give it a reference image, by providing the identifier of a Cabinet document. The random seed, on the other hand, is for replaying an image identically, not for making two different images consistent with each other.

File editing. The assistant can replace a specific passage in a document it produced, rather than rewriting the whole thing. That is what makes quality control (3.9) realistic: fixing two inconsistent dates costs two edits, not a full regeneration of the document — which would risk breaking elsewhere what it repairs.

5.3 Skills

A skill is a reusable procedure: the right way to carry out a type of task, written once and for all. It can define when to use it, the steps to follow, the tools required, the effort level, the expected format and the success criteria.

A skill grants no access: the tools it mentions must still be enabled and allowed for the profile concerned.

You can let the orchestrator pick the skill that fits the meaning of the request, or impose one on a mission, a task or a batch. In the input fields that support it, type # to insert a skill and / to insert a tool: the name is inserted as a coloured chip. It is a hint to the orchestrator, not a guarantee.

5.4 Ticket and project tracking (Renkany bundle)

Pumaï can connect to Renkany, a ticket and project management tool, to read the real state of the work and act on it. This integration comes as a dedicated tool bundle, and it is shipped disabled: it does nothing until you have configured and enabled it. If you do not use Renkany, skip this section — the integration then has no effect and costs nothing.

What it allows

Reading — the assistant can consult:

• tickets, filtered by status, priority, assignee, due date, project;
• a ticket's detail, with its comment thread and attachments;
• the list of projects and the directory of people;
• workload per person;
• service-level compliance;
• time spent;
• the activity log.

Writing — it can:

• create a ticket in a project;
• change a ticket's status, which is how a ticket is moved to "resolved";
• reassign it to someone else;
• add a comment to it;
• attach a file to it.

What it deliberately does not allow: no deletion is exposed — not tickets, projects, comments or attachments — and the assistant can neither create a project nor replace a project's member list. Those remain human actions.

Configuring it

Open System → Tools, find the matching family, and fill in:

• your tracking instance's API address;
• the access token — the equivalent of an API key, obtained from your tracking tool;
• the write policy (see below).

Then enable the bundle.

Use a token with company-admin rights. A more restricted token answers partially — it returns only the tickets it may see — without saying so. You would then get wrong counts, with no error message at all.

The write policy

Three values, to be chosen deliberately:

• No writing (the default) — read-only. Enabling the bundle from the Tools page therefore gives you consultation and nothing else: writing requires a separate, deliberate action.
• Comments only — the assistant can annotate, not modify.
• Full write — it can create, change status, reassign, comment, attach.

Creating a ticket sends an email to the people assigned and consumes quota. It is never a test operation: try read-only first.

Two points to watch

Internal notes. When the assistant adds a comment, it writes an internal note by default, visible to your team only — not to the client. This is the opposite of the usual behaviour of such tools, and it is deliberate: an agent writes a working note; it does not send text to a client unless asked. For a comment genuinely visible to the client, you must ask explicitly.

When reading, internal notes are flagged as such, each on its own line, with a warning. This is the number one risk of the integration: a client brief that copied an internal note would be an unrecoverable incident.

Scope. The company concerned is determined by the token, never by a request from the assistant: one Pumaï instance corresponds to one client, hence one company. An important consequence to keep in mind when reading a result: an empty count may mean "outside my scope", not "nothing to report". The assistant reminds you of this on every count.

5.5 MCP connectors

MCP is a standard that lets an external server expose its own tools. Plugging in an MCP connector adds, in one go, a set of tools Pumaï did not have.

The safe path:

1. add the server;
2. leave it disabled while you check its origin and configuration — that is how it arrives, and the safeguard is deliberate;
3. fill in its variables or its authorisation;
4. enable the server;
5. discover the tools it exposes;
6. enable only the ones you need;
7. set their approval requirement and per-profile access.

A local server executes code on Pumaï's machine. Only enable servers you trust, and keep MCP tools that write or act externally under approval during the first runs.

5.6 Gateways

A gateway is a conversational way in, to talk to Pumaï other than through the web interface:

• Telegram — a bot, a list of authorised users, an associated session;
• Discord — a bot, authorised users, optionally a channel, a session;
• Phone (Twilio) — a real phone number. See below.

A gateway does not replace a business tool: chatting with Pumaï on Telegram does not configure email sending.

The phone, in detail

This is the most impressive and the most misunderstood capability: your assistant can pick up the phone, and it can call out. It is not an answering machine — it is a real-time voice conversation, held by the same assistant you meet in the Chat, with its memory and its tools.

The provider is Twilio, and there is no other: Pumaï relies on their real-time voice service for inbound calls, and on their API for outbound ones. So you need to open a Twilio account and buy a number there. It is a paid service, billed per minute and independent of your AI credits: you will pay for two things, telephony at Twilio and reasoning at your model provider.

What you need to gather:

The step that trips people up most often: the public address. Twilio is an outside service; to put a call through to you, it must be able to reach your instance from the internet. An instance only reachable on your local network will never receive a call. If your instance is hosted and already has a public address, use it; otherwise you have to expose your machine temporarily through a tunnel.

The two directions do not require the same work:

• Receiving a call needs the whole configuration above, public address included, plus one setting on Twilio's side: in your number's settings, the Voice webhook must point to the address shown on the Gateways page, ending in /v1/voice/incoming. Copy it verbatim.
• Placing a call only needs the account, the token and the number. It is simpler, and it is often the better place to start in order to validate your credentials.

Two tools, not to be confused, which you enable like any other from the Tools page:

• place_call — starts the call and returns immediately. The assistant does not know what was said; it only knows the call went out. For "let them know", "confirm it to them".
• call_and_wait — starts the call and waits for it to end in order to report what was said. This is the one you want when you expect an answer: "call them and ask whether Thursday's appointment still stands". A call lasts tens of seconds: this tool is slow by nature, and the engine accounts for that in its time limits.

Both take a number in international format, a one-sentence objective and optionally some context. Write the objective the way you would tell someone you are handing the phone to: "find out whether Tuesday's delivery is confirmed" beats "call the supplier".

A phone call is irreversible. Unlike an email draft, a placed call cannot be taken back. Keep both tools under approval until you have seen several calls go correctly, and only then open up autonomy.

5.7 SSH connections

The SSH page registers the remote servers the assistant may use. Each target has an alias, a host, a port, a user, key or password authentication, an optional privilege-escalation permission, and a list of allowed commands.

Predefined profiles — Health, Security, Maintenance, Logs, Containers — let you start from a sensible list. Always prefer a minimal allowlist over "all commands".

6. The interface, page by page

6.0 What appears on every page

The top bar lets you suspend or resume all automations, change the interface language, switch between light and dark theme, return to the Dashboard, and log out.

Several pages show a collapsible help banner explaining the page in a few lines: read it the first time, it often saves a question. A Support button at the bottom of the interface lets you send feedback; describe the page, the time and the expected result, so the corresponding run can be found in the Logs.

6.1 Dashboard

An overview: actions awaiting approval, saved conversations, active scheduled tasks, active missions, knowledge sources, open cases. It is an orientation page, not an audit log.

6.2 Activity

This is the best page to answer "what has my assistant done?". It brings together:

• mailbox activity;
• the actions, reports, answers and files produced;
• actual consumption;
• an estimate, clearly labelled as such, of the human time saved;
• a mission timeline, presented as a narrative: objective → what happened → result;
• the state of each profile;
• pending proposals;
• open cases.

You can change the period, and filter by profile or by origin — Chat, scheduled task, mission, batch. Click a row to expand the detail.

6.3 Mail

The mailbox used by the assistant: received, sent, drafts. It depends on the mail bundle configured in chapter 2.4.

It is a read-only control view. There is exactly one write action: when a draft prepared by the assistant is shown, a button lets you actually send it, after you have read it. This explicit human approval is not subject to the authorised-recipient list — you are the sender.

Correspondents are labelled automatically: Management, Team, Client, Supplier, Assistant or External, and the direction of a message (received or sent) is determined by the addresses, not by the folder name.

6.4 Cabinet

The Cabinet centralises the instance's durable files: documents you upload, reports and deliverables filed by the assistant, items to be sent, archives.

Two shelves:

• Reference — the document is indexed; the assistant can find it and cite it in an answer;
• Archive — the file is kept, but does not feed search.

What a document's card tells you:

• its origin — where it really came from: a conversation, a named watch mission, a scheduled task, a batch, an email send, or you. It is reliable classification that neither you nor the assistant has to type in; a filter lets you show one origin only;
• whether it is indexed or not. Watch this one: a document filed under Reference whose text could not be extracted — an image, a scanned PDF — is indexed nowhere, and no mission can find it. The page now says so explicitly;
• its identifier, displayed and copyable in one click. This is the value you paste into a mission to designate a reference image;
• its tags, editable from the expanded card;
• its provenance (you or the assistant), its intended recipient and its status: to send, sent, superseded.

Visual documents show a thumbnail.

The Cabinet is durable; a run's workspace is temporary. If a produced file must remain available after the conversation, explicitly ask for it to be filed in the Cabinet.

6.5 Showcase

The Showcase turns the instance's real journal into a presentable page: actions, output, watches, decisions, files, cases handled.

It is private by default. The Publish button creates a public link containing a token: anyone with that link can view the page without a password. Identities and email addresses are masked there, and files are not downloadable publicly — the page attests that they exist without handing over their contents. Still, review the page before sharing it.

You can write the public introduction, publish, copy the link, go private again, or regenerate the link to invalidate the old one.

6.6 Chat

The Chat is for asking a question, requesting an action, attaching a document or an image, following the reasoning and the tools used, retrieving deliverables, interrupting a running job, and returning to an earlier conversation.

Before sending: choose the profile, choose the effort, attach the files, and describe the expected result and its destination. Changing profile starts a new session, to avoid mixing contexts.

A few commands:

• /task <instruction> — force handling as a complex task;
• /new — new session;
• /profile — show the user profile;
• /remember <text> — ask for something to be memorised.

Type / to insert a tool or # to insert a skill.

Images and documents you paste into the Chat can be reused by the assistant: it can analyse them, attach them to a send, or use them as a reference for generating an image.

6.7 To approve

Every action suspended before execution. For each one you can Approve, Reject, choose Later, mark I'll handle it, correct some arguments before approving, or add a note.

Check the recipient, the target, the attachments and the parameters of an irreversible action first.

A selector lets you see proposals from all profiles, and a button clears expired proposals — that operation is reversible, nothing is deleted.

6.8 Scheduler

To create a task:

1. click New task;
2. give it a readable name;
3. write the complete instruction;
4. choose the category: reminder, appointment or mission;
5. choose Cron, Interval or Single date;
6. set the schedule;
7. choose delivery;
8. select the profile — this is required;
9. choose the effort;
10. tick Check consistency before delivery if the result leaves your organisation;
11. create, then trigger a first manual run.

From the list you can run, edit, disable, re-enable, delete and view the history.

The Calendar subscription section provides ICS addresses for reminders and appointments. Do not share them: they expose your schedule. Regenerating the token invalidates every previous subscription.

6.9 Pulsar

To create a mission:

1. click New mission;
2. give it a name;
3. choose Permanent, Conditional or Time-limited;
4. write what to observe, compare and report;
5. set the frequency, or a custom interval in minutes;
6. choose the nature: Watch or Production;
7. choose the effort — Low for a simple watch, Medium at minimum for production;
8. optionally impose a skill;
9. tick quality control if needed;
10. select the profile;
11. save;
12. click ⚡ Run now for a first trial.

Each card shows the last pass, the verdict, a summary and cumulative consumption. The Logs and State buttons show the history and the memory kept between passes.

The Wake the heartbeat button at the top of the page wakes the general mechanism: it does not force cadences. A mission that is not due will still not run — and the page tells you, mission by mission, what will actually be executed. To run one mission off-cadence, use its ⚡ Run now button.

A well-written Pulsar clearly distinguishes what existed on the previous pass, what is new, what has disappeared, what justifies an alert, and when it should stay silent.

6.10 Batches

The third entry in the Automation menu. The first two are clocks; this one is a work queue.

Creating a batch — the New batch button:

1. a name;
2. the nature: List or Open (see 3.5);
3. the production instruction, with {{item}} where the item should appear;
4. depending on the nature, the list of items (one per line) or the number of iterations;
5. the profile;
6. the effort — Medium at minimum if the items must call tools;
7. a skill, if you have a suitable one;
8. the cost cap and/or the token cap;
9. the number of consecutive failures tolerated;
10. the pause between items, if your provider rate-limits calls;
11. quality control before delivery, if the result must be flawless.

Save. The batch does not start on its own: review the list and the estimate, then click Start.

Following a batch. Its card shows a progress bar such as "12 / 36", the actual spending, an estimate of what remains to produce, an approximate finish time, the item in progress, the number of failed items, and — if it has stopped — the exact reason.

The estimate of what remains is computed from the items already done. Until something has been produced, nothing is shown: an invented figure would be worse than no figure.

Acting. The Items and Log buttons expand the detail: each item with its state, the files it produced, and a Retry button to re-run precisely the one that failed. A retried item reproduces exactly the same item, never "the next one". The Pause and Stop buttons suspend production; remaining items are kept pending.

Finished batches are grouped in a collapsed section at the bottom of the page.

6.11 Assistant

Two uses:

1. the general business configuration: identity, mission, objectives, style, constraints, directory;
2. the mission plans: objective, audience, horizon, resources, channels, indicators, phases and checkpoints.

A mission plan is not a scheduled task: it describes an objective in several phases and steers activity over time. It can be inactive, active, paused or archived.

The page also shows open cases. A case tracks a matter through to closure; on its own it triggers nothing.

6.12 Memory

This page manages a profile's persistent knowledge: select the profile, add a text or a file, classify the source, test a search, manage conversation segments and explore the knowledge graph.

It is organised in three tabs:

• Memories — the list of what is memorised, conversations and documents, with their state (memorised or set aside). The "See the facts" button shows the elements that are actually retrievable, which are the unit of search — not the whole conversation. A test bar lets you try a search and see the score obtained.
• Knowledge graph — the entities and links the assistant has extracted. Clicking an entity opens its card.
• Maintenance — the housekeeping operations. Each states what it does and what it costs, because some trigger one model call per conversation.

The three levels of memory, so you know what you are handling: the immediate conversation history, summaries of older exchanges, and long-term memory queried by similarity of meaning.

If you are not comfortable with these notions, stick to adding sources and testing search: those are the only two operations you need day to day.

6.13 Profiles

The place where roles and data are separated (chapter 4). Start with the owner record at the top, then create or select a profile and go through its tabs.

When creating one: a readable name, a stable lowercase identifier, the right type, long-term memory enabled if the profile must search its memories, and the time zone matching its working hours.

In Settings, a low temperature suits factual work, a higher one creative work. The global model remains the best choice until a specific need justifies an exception.

6.14 Tools

The native, custom and MCP capabilities, grouped by family. Filters let you search by family, type, exposure, risk, approval and state.

For everyday use: open a tool's card, read its description, configure it, enable it, choose its approval setting. The code and file-tree sections are for advanced users; to create a tool without writing code, use the Studio.

6.15 Gateways

For Telegram or Discord: create the bot on the platform, get its token, list the authorised users, choose an existing session, create the gateway, test it, check that it is connected.

For the phone, choose the Phone (Twilio) type, then:

1. open a Twilio account and buy a number there;
2. note the Account SID (it starts with AC…) and the Auth Token from their dashboard;
3. enter them here, together with the number in international format (+1…);
4. fill in your instance's public HTTPS URL — the one Twilio will reach it on from the internet;
5. choose the profile that answers incoming calls;
6. create the gateway. The interface then shows the Voice webhook to copy on Twilio's side, into your number's settings: it is your public URL followed by /v1/voice/incoming;
7. test an outbound call first — it does not depend on the webhook, and it validates your credentials without depending on your instance being reachable.

If outbound calls work but inbound ones do not, the cause is nearly always the same: your instance is not reachable from the internet, or the webhook was not pasted on Twilio's side.

6.16 SSH

To add a server: New connection, an unambiguous alias, the host, port and user, key or password authentication, privilege escalation only if necessary, a command profile, then remove the commands you do not need. Save, and first test a read-only command from the Chat.

The page configures the connection; the task itself is then created in the Chat, the Scheduler or a Pulsar.

6.17 Credits

The balance, consumption and history, when your instance runs on supplied credits. If that mode is not active, the page tells you so.

6.18 Studio

The Studio creates a custom tool from a guided interview: describe the purpose, the inputs and the output; answer the questions; review the generated code; declare the sensitive capabilities needed; provide test arguments; test in a sandbox; save first as a trial version; only promote to stable after validation.

A tool that uses the shell, the network or sensitive writes should stay under approval. Earlier versions can be restored.

6.19 Skills

A library, an editor, guided creation, a comparative "with / without" sandbox, and a global switch.

For a skill to be useful, pay particular attention to: a clear trigger ("when the user asks…"), an ordered procedure, the tools required, the expected input and output, and verifiable success criteria.

The sandbox really runs two variants of the same task and therefore consumes credits. Use a representative task, then compare quality, number of steps and cost.

6.20 API access

The main key, named secondary keys, revocation, examples and access to the interactive documentation.

A secondary key is shown in clear only when it is created: copy it immediately into a password manager. Renewing the main key cuts off every integration using the old one.

6.21 MCP connectors

Several ways to add one: official catalogue, search in a public registry, import, manual command, remote server with a key or delegated authorisation. Servers arrive disabled. After enabling one, review each discovered tool, here and then in Tools.

6.22 Dev

The technical settings console: providers and models, agent limits, effort levels, memory, Pulsar cadence, Showcase, and various advanced options.

Three things to know:

• the model selectors show each model's price. This is not a detail: changing model can triple the cost of a production run with nothing else in the interface changing;
• some fields are read-only, with a badge explaining what drives them. Those are the ones the effort level imposes: changing them here would have no effect, and the page says so rather than letting you believe otherwise;
• this page rewrites the instance's configuration. If you do not know exactly what a setting does, do not change it.

6.23 Logs

The technical diagnostic view: runs, their origin, status, duration and consumption; agents and sub-agents; tool inputs and outputs; model calls made outside a run; phone calls; sessions and authentication events.

A run that came from the Chat carries a 💬 icon that opens the matching conversation. A running job can be interrupted from this page.

Simple rule: Activity to check the work, Logs to understand an error, a slowdown or a cost.

6.24 Cases

Cases — also called open loops — are the matters not to be forgotten: a client request, a pending quote, an incident, a follow-up, an action to finish.

A case has a title, a description, a contact, a priority, a status, a last action and notes. It can be updated, closed or cancelled. Closing records the resolution; deletion should stay exceptional, because it erases the trace of the follow-up.

7. Automation recipes

7.1 Triaging urgent emails

Goal: watch the mailbox, classify messages, alert only when necessary.

1. Configure the mail bundle (2.4).
2. Define the authorised recipients.
3. Create an autonomous profile called "Office".
4. Limit its tools to mail, memory, cases and notifications.
5. Create a permanent Pulsar, nature Watch.
6. Choose an interval of 15 or 30 minutes.
7. Effort Low.
8. Run it once by hand, then check Mail, Activity and Logs.

Goal: spot the messages that need a quick reaction.
Scope: the inbox, unread messages from the last 24 h.
Treat as urgent: an outage, a quote request, a client chasing us,
  a message from a directory contact marked as priority.
On each pass: compare with what you retained last time.
Only report what is NEW since the previous pass.
If there is nothing new: stay silent, send no notification.
Remember: the identifiers of the messages already reported.

7.2 Sending a daily summary

Scheduled task, Cron at 6 pm, "Office" profile, effort Medium, delivery by email, quality control ticked.

Goal: a recap of the day just ended.
Scope: messages received and sent since 00:00, cases modified today.
Produce: a summary of at most 10 lines, then a list of pending items.
Never ask again for an action already handled: if a case is closed, do not raise it.
If nothing happened, say so plainly — do not invent activity.
Deliver: by email to the owner.

That last instruction matters: without it, a report can invent a "quiet day" where it simply failed to read the data.

7.3 Publishing weekly

Scheduled task, Cron on Monday at 9 am, a dedicated profile, effort High, quality control ticked, publishing tool under approval at first.

7.4 Checking a server's health

An SSH connection limited to read-only commands, a "Supervision" profile, a scheduled task at 8 am, effort Medium, delivery by email or Telegram.

Goal: detect a problem before it becomes an incident.
Scope: the server named <connection alias>.
Check: disk space, load, memory, expected services, recent log errors.
Alert if: disk above 85 %, an expected service is stopped, or errors repeat.
Produce: a 5-line status, then detail only if something is wrong.
Run no command that modifies anything.

7.5 Producing a report, filing it, sending it

In the Chat, effort High:

Goal: a monthly activity report.
Scope: the month just ended.
Produce: a structured document, then convert it to PDF.
File the PDF in the Cabinet, Reference shelf, tags "report, monthly".
Then send it to the owner as an attachment.

Note the order: produce, file, then send. Asking for the send first often yields an email with no attachment.

7.6 Chatting from Telegram

Create the bot on Telegram, get its token, create the gateway with the list of authorised users, associate a session carrying the right profile, test.

7.7 Watching a price until a threshold

A Conditional Pulsar, nature Watch, effort Low, 6-hour interval.

Goal: tell me when the price of <product> drops below <amount>.
Source: <page address>.
On each pass: re-read the page, extract the price, compare it with the remembered price.
Report: only if the price has dropped below the threshold, or fallen by more than 10 %.
Remember: the last observed price and its date.
Stay silent in every other case.
The mission is complete once the threshold alert has been sent.

7.8 Producing a consistent image series

This is the textbook case for a batch.

1. Put an image in the Cabinet to serve as the style reference, and copy its identifier from its card.
2. Create a batch, nature List.
3. Paste the list of subjects, one per line.
4. Write the instruction with {{item}} and the reference image's identifier.
5. Effort Medium, a sensible cost cap, 3 failures tolerated.
6. Save, review, Start.

MISSION — produce an illustration of {{item}}.
Style: match exactly the style of reference image <Cabinet identifier>.
Format: square, light background.
File the produced file in the Cabinet, Archive shelf, tag "series".

Watch the first three items before walking away: if the style is wrong, pause, fix the instruction, and restart. That is far cheaper than discovering thirty-six failed images.

7.9 Reviewing tickets every week

Scheduled task, Cron on Friday at 5 pm, a dedicated profile, effort Medium, quality control ticked, ticket-tracking bundle in read-only.

Goal: a weekly review of the state of the work.
Scope: all projects, the week just ended.
Produce: resolved tickets, open tickets by priority, those past their due date,
  and workload per person.
Remember that scope depends on permissions: an empty count may mean
  "outside my scope", not "nothing to report".
Never copy the content of an internal note.
Deliver: by email to the owner.

7.10 Placing a phone call

First configure the Phone (Twilio) gateway (5.6), then enable call_and_wait on the Tools page, under approval for the first trials.

From the Chat:

Call +1XXXXXXXXXX.
Objective: find out whether the delivery scheduled for Tuesday is confirmed, and at what time.
Context: order no. 1234, placed on the 12th, contact is in the shipping department.
Report back what was said, without interpreting it.

The action will appear in To approve before going out. Check the number — unlike an email, a call cannot be taken back. Once the call ends, the assistant reports what was said; the detail is also in the Logs, in the phone calls section.

For a simple message with no answer expected, place_call is enough and returns immediately.

7.11 Plugging in an external service

Add the matching MCP server, leave it disabled, check its origin, fill in its access details, enable it, then enable only the useful tools, under approval at first.

7.12 Integrating an API with no tool or connector

Use the Studio: describe the API, its inputs and its output, and let the guided interview produce the tool. Test it in the sandbox before saving it.

8. Writing a good instruction

8.1 The structure that works

A good instruction contains six elements:

1. Goal — what must be obtained;
2. Scope — sources, period, account, server, folder;
3. Rules — what is allowed, what is forbidden;
4. Criteria — thresholds, quality, success conditions;
5. Output — format, length, structure;
6. Destination — screen, email, Cabinet, publication, or nothing.

Goal: …
Scope and sources: …
You may: …
You must never: …
Consider the task successful if: …
Produce: …
Deliver the result: …
If there is nothing to report: …

8.2 For an automation that runs without you

An automation cannot ask you a question at the right moment. Remove the ambiguities before scheduling it:

• name the recipients;
• name the accounts and connections;
• give numeric thresholds;
• say what to do if information is missing;
• say whether to stop, stay silent, or produce a partial report;
• say whether an action should be proposed or executed.

8.3 For a Pulsar

Always add: what counts as new, what counts as an alert, what to remember from one pass to the next, how to avoid reporting the same thing twice, when to stay silent, and when the mission is complete.

8.4 For a batch

A batch's instruction is the same for every item. So write it in the singular, placing {{item}} where the item should appear, and never refer to what came before: no "the next one", no "like the previous one", no "continue the series". Each item must be producible on its own, and reproducible identically if it fails.

Also specify where to file the result. An item produced and not filed ends up in a temporary workspace.

8.5 For an action that leaves your organisation

Explicitly write the recipient or target, whether you want a draft, a proposal or a real send, the attachments, the account to use, and what to do if the target is not authorised.

"Draft an email" does not mean "send it". "Publish" asks for a real action and may trigger an approval request.

9. Controlling actions and costs

9.1 A cautious start

1. test in the Chat;
2. put external tools under approval;
3. choose a moderate frequency;
4. stay at Low or Medium effort;
5. trigger a first manual run;
6. check the result;
7. increase autonomy gradually.

9.2 Where to look

9.3 Avoiding unnecessary spending

• do not run a round every five minutes for a daily signal;
• use Low effort for simple checks;
• impose a proven skill: it reduces trial and error;
• limit each profile's tools;
• give clear stopping criteria;
• pause failing missions rather than letting them retry;
• disable advanced features you do not use;
• use the global switch during maintenance;
• look at the price shown in the model selector before changing model.

9.4 A batch's caps

A batch is the only mode that commits spending in series while you are away from the screen. Always give it at least one cap:

• a cost cap if your provider publishes its prices;
• a token cap in all cases — it works even when the displayed cost stays at zero because no price is published;
• a number of consecutive failures tolerated, so that a recurring problem stops production instead of repeating it.

A batch stopped by a cap has lost nothing: raise the cap and restart.

9.5 Keeping secrets safe

• never put a key, a token or a password in a message, a memory or the Cabinet;
• use only the configuration fields provided in Tools, MCP, Gateway or SSH;
• create one secondary API key per integration, never a single shared key;
• revoke the key of an integration you remove;
• regenerate a public Showcase link if it has spread too widely;
• limit the authorised users on Telegram and Discord;
• limit the email recipients;
• always grant the minimum permissions.

10. Using Pumaï through the API

Everything configurable in the interface has an API representation, and the main actions can be triggered from another application.

10.1 Creating a key

System → API access → New key. Name it after the integration that will use it, and copy the displayed secret immediately: it will never be shown in clear again.

Then send the key in your request headers:

Authorization: Bearer YOUR_KEY

10.2 Common uses

Send a message and receive the answer; open a progressive response stream; manage sessions; choose a profile and an effort; manage scheduled tasks; manage profiles; query memory; list tools; handle pending proposals; use the endpoint compatible with existing OpenAI clients.

The API access page provides examples already adapted to your instance's address, and a button opens the full interactive documentation.

10.3 Good practice

One key per application and per environment; never a key in public source code or in a browser; an explicit profile in every call; a session identifier kept when you want to maintain context; a fresh context for a different user or a different line of business; handling of timeouts and long-running jobs; immediate revocation if a key is compromised.

The interface remains the best way in for configuring profiles, tools, security and connections. The API is then how you drive Pumaï from a CRM, a client portal, a script or a business application.

11. Troubleshooting

"The assistant says it cannot use a tool"

Check in this order: does the tool exist in Tools? is it enabled? is it configured? does the profile allow it? is the connector that provides it active? is an approval pending?

A disabled tool is not merely blocked: it is not offered to the assistant at all.

"The scheduled task does not run"

Check the global switch, then that the task is active, then the schedule, the days and the profile's time zone. Click Run for an immediate test, then open its history and the Logs.

"The Pulsar reports nothing"

Click ⚡ Run now — not the general wake button, which does not force cadences. Open State and Logs. Check the frequency, the custom interval, that the mission is active and not expired, and that the instruction actually defines what counts as an alert.

A silent verdict is often normal: a good Pulsar does not repeat information that has not changed.

"The Pulsar consumes too much"

Low effort, longer interval, a more precise skill, a narrower scope, an explicit silence rule and a completion criterion. Pause the mission while you investigate.

If the mission makes something in series, it is not a setting that needs changing: it is a batch that needs creating (3.6).

"The batch does not start"

A newly created batch waits for you to click Start — that is deliberate. Then check that automations are not paused, and that items are still pending. After a server restart, a running batch is paused: restart it yourself.

"The batch stopped on its own"

Its card always shows the reason: queue empty, cost cap, token cap, too many failures, quota exhausted, stop requested, automations paused, restart. In the case of a cap, raise it and restart: the remaining items are kept.

"No email shows up"

Is the mail bundle configured and enabled? Are the incoming settings the ones your provider publishes? Is IMAP access actually enabled at the provider? Is the password you used an app password, rather than the account password? Test, then check the Logs, which give the mail server's exact error message.

"The email is not sent"

First check that it is not simply a draft — that is the most frequent case, and it is the expected behaviour if the sending policy is Draft or if the recipient is not on the authorised list. Then look at To approve, then at the outgoing settings.

Finally, check your instruction: "draft an email" does not ask for a send.

"The file has disappeared"

A file left in a run's workspace is temporary. To keep it, explicitly ask for it to be filed in the Cabinet.

"The assistant cannot find a document"

In the Cabinet, check that it is on the Reference shelf and that it is marked indexed — a scanned PDF or an image is not, and therefore stays unfindable. In Memory, check the profile, the source's state and its indexing. Try a search with words close to the content. Finally, check that long-term memory is enabled for that profile, and sharing if the source belongs to another profile.

"Telegram or Discord does not answer"

Test the gateway, check its connection state, its token, the authorised user or channel identifier, and the associated session. Check the Logs.

"An SSH connection fails"

Check the host, port, user, key or password, then that the requested command is on the allowed list. Test a simple read-only command first.

"An automation is misbehaving"

1. switch the global control to OFF;
2. interrupt the running job from the Logs;
3. disable the task, mission, batch or tool responsible;
4. put the profile back into supervised mode;
5. inspect Activity and Logs to understand;
6. fix the instruction, retest in the Chat, then resume.

12. Glossary

Agent — A working instance that reasons and uses tools. One request may involve several.

API key — A password meant for a program rather than a human.

App password — A secondary password, generated by your mail provider for one specific program, revocable independently of the account password.

Authorised recipient list — The assistant's right to send. An address not on the list cannot receive a message.

Batch — A production queue that works through a list of items without waiting for any clock, and stops when the list is empty.

Cabinet — The instance's durable, central document space, shared by all profiles.

Bundle — A coherent family of tools: mail, web, files, images…

Case (open loop) — A matter to follow through to resolution.

Effort — The level of depth, delegation and proofreading applied to a run.

Gateway — An external channel through which a human converses with Pumaï: Telegram, Discord or the phone.

Phone gateway (Twilio) — The gateway that gives the assistant a real phone number. It answers incoming calls and can place calls itself. Twilio is the only supported provider, and its per-minute billing comes on top of the AI cost.

Item — One unit of production in a batch.

Long-term memory — Search by similarity of meaning across indexed conversations and documents.

MCP — A standard that lets an external server expose its tools to Pumaï.

Profile — A working identity, with its own personality, memory, tools and autonomy.

Pulsar — An autonomous mission that wakes at regular intervals and remembers what it saw on the previous pass.

Quality control — A re-read of the deliverable by the agent that has just produced it, before delivery.

Run — The complete handling of a request or an automation, from start to delivery.

Scheduled task — An action executed on a schedule, an interval or a date, with no memory of previous runs.

Session — A conversation thread that keeps its context and its profile.

Showcase — A publishable page presenting the instance's real activity and output.

State (of a Pulsar) — What the mission retains from one pass to the next. It is what lets it say "that was not there last time".

Tick — One pass of a Pulsar mission.

Token — The unit in which an AI model's work, and therefore its cost, is counted.

Tool — An executable function that lets the agent read, produce or act.

Workspace — A run's temporary space. Anything that must last goes into the Cabinet.