AI Assistant
Ask Gatana how the product works, and let it act in your organization
Introduction
The AI assistant is a chat panel in the Gatana dashboard. Open it with the Ask Gatana button in the header, or with ⌘J (Ctrl+J on Windows and Linux). Some pages also show an Ask AI button, which opens the panel with the question already written.
The panel opens over the page. The pin button at the top docks it beside the page instead: the dashboard makes room for it, you keep navigating with the conversation on screen, and you can drag its left edge to resize it. The pin and the width are remembered between visits.
The assistant does two kinds of work:
- It answers questions about Gatana. It searches the documentation and reads the page you are on, so it can answer "why is this server greyed out" as well as "how do I share one credential with a team".
- It acts in your organization. It can list, create and change the same things you can in the dashboard — servers, profiles, teams, credentials and the rest — through the Gatana Public API.
Three rules hold for everything it does:
- It acts with your permissions. It cannot reach anything you could not reach yourself.
- Anything that would change your organization is shown to you for approval before it runs.
- Every action is audit-logged, exactly like an action you take by hand.
The assistant's own tools
Four tools are the assistant's own. They are always there, and no profile grants or withholds them:
| Tool | What it does |
|---|---|
search_docs | Searches this documentation. It is how the assistant answers "how does X work" with the current answer instead of a remembered one. |
read_current_page | Asks your browser what the page you are on is showing. Your browser answers it, not the server. |
ask_user_question | Puts a question to you, with the answers as buttons, and waits. The assistant uses it when it needs a decision that is yours — most often to offer to do a thing it has just described. Pick an answer, type one of your own, or ignore the card and keep writing. |
search_tools and execute_code | Code Mode, when the profile grants it. |
| * | Any other tools you promote in its profile. |
Profile
What the assistant may use is an ordinary profile. Your organization owns it, and it is listed, edited and assigned like any other profile. The servers on that profile are the servers the assistant can reach; its tool restrictions apply as they would to any client.
The profile is created the first time somebody uses the assistant. It is named AI Assistant, and it starts with the two built-in servers the assistant needs to work on your organization:
| Server | What it gives the assistant |
|---|---|
codemode | Code Mode: search_tools to find tools, and execute_code to call them |
gatana-api | The Gatana Public API, which is how it acts on your organization |
To change what the assistant can reach, open the profile from Profiles in the side menu, or from the settings button at the top of the assistant panel. Add a server to let the assistant use it; remove one to take it away. If you delete the profile, the next conversation creates a fresh default.
Keep the assistant's profile unassigned and closed
A profile gives member-level permission on every server assigned to it, to every session that
applies the profile. The assistant's profile is an ordinary profile, so a server you add to it
becomes reachable by anyone the profile is applied to — through direct assignment, a team, a claim
mapping, the p= parameter, or the Open to All Users flag. It is created unassigned and
closed. Leave it that way, and check it before you add a sensitive server to it.
An assistant turn is a different case. It runs on the permissions of the person using the panel, which the profile does not raise: the profile says which servers the assistant may use and which of their tools, and the user's own permissions decide what may actually run. So a server on the profile that you cannot reach yourself stays out of reach in the panel. The warning above is about everyone else the profile might be applied to, not about the panel.
Code Mode and the long tail
Most of what the assistant can do goes through Code Mode. Rather than putting hundreds
of tools in front of the model, Gatana gives it search_tools to find the right tool and
execute_code to call it. That is why the codemode server is on the profile by default.
Code Mode alone gives the assistant nothing to act on. It needs at least one other server on the
profile — gatanaApi, or one of your own — before search_tools has anything to find.
Promoted tools
A promoted tool is offered to the assistant directly, by name, instead of
being reached through execute_code. This is useful to get ahead of discovery. The assistant will always be aware of the tool. For example, see the web below.
To promote a tool for the assistant:
- Open the AI Assistant profile
- In the servers table, click Edit on the server row
- Turn on Promote for the tool
- Click Save Changes
What promotion changes:
| Through Code Mode | Promoted | |
|---|---|---|
| How the model reaches it | Finds it with search_tools, calls it in execute_code | Calls it by name, directly |
| Context cost | Only when it searches | On every turn, whether used or not |
| Best for | The long tail: hundreds of tools, used rarely | A handful of tools, used often |
Because a promoted tool spends context on every turn, at most 30 of them are put in front of the model. Anything above that stays reachable through Code Mode.
A tool that says it only reads runs straight away. A tool that can change something asks you first, on every call — see Approvals.
Promoted names are per profile
A promoted tool is offered under its exposed name. The assistant reduces a name that a model provider would refuse to letters, digits, hyphens and underscores. If two tools end up with the same name, the second one is numbered.
Letting the assistant use the web
To enable searching the web or fetching a web page/URL: simply add these tools to the assistants profile
| Job | Promoted name | What it does |
|---|---|---|
| Search the web | search-web | A search API, such as Brave or Tavily |
| Read a web page | fetch-web | A fetcher that returns the content of one address |
Any tool of any server you have connected can do either job. The name is what tells the assistant
which tool does what, so promote the tool under exactly search-web or fetch-web.
The quickest way is the settings button at the top of the assistant panel: pick a tool for each job and Gatana writes the promotion for you, adding the server to the profile if it is not there yet. You can do the same by hand on the profile page.
Who can do it: an organization owner, or a maintainer of the assistant's profile. Everyone else sees the panel without the settings button.
Approvals
Reading runs immediately. Anything that creates, changes or deletes is put to you first, in the conversation, as a card that shows exactly what will run:
- For code, the program the assistant wrote, and the tools in it that can change something.
- For a promoted tool, the tool and the arguments it would be called with.
You then choose:
| Choice | What happens |
|---|---|
| Run it | It runs once, with these exact arguments. |
Always allow tool | It runs, and you are not asked about that tool again. |
| Cancel | Nothing runs. The assistant is told you said no. |
An approval is bound to the exact code or arguments you saw. If the assistant changes either one, it has to ask again. Approvals expire, so a card you come back to hours later asks the assistant to request approval anew.
Always allow is yours alone — it is not granted for your colleagues, and it removes the question and nothing else. Whether you may use the tool is still decided at every call by your permissions, the profile and the tool firewall. Take a standing approval back under Tools you always allow in the assistant's settings.
What the assistant sees of your screen
Every question carries the address of the page you are on and the identifiers on it, so that "this server" and "the second one" mean something. When the answer needs more — which rows are listed, what is filtered, what you have typed but not saved — the assistant asks your browser for an outline of the page. Secrets are removed before it is sent.
The assistant treats everything that comes back as data, never as instructions. It confirms anything it is about to act on with the API first, because a page can be stale.
Enabling the assistant
The assistant is off until an organization owner turns it on. The first time the panel is opened it offers the opt-in: an owner can turn the assistant on right there, and everyone else is told that an owner has to. An owner can also turn it on — and off again at any time — under Settings → Features → AI assistant, which is also where the model is chosen.
On Gatana's model, one more thing is asked of an owner: that Gatana's model provider may process your conversations. Conversations — including what the assistant reads from your organization while answering — are sent to OpenRouter under a zero-data-retention policy: prompts and answers are not stored once the reply is served. OpenRouter is listed as a sub-processor in the Data Processing Agreement, and agreeing is your organization's instruction to process conversations this way. It is recorded with the time and the owner who gave it, and can be withdrawn under Settings.
That question is asked only when the conversations would go there. An organization bringing its own model is not asked it, because nothing reaches that provider. It is asked if such an organization later moves to Gatana's model — the instruction covers the processing, not the switch, so it is not read into a decision made about something else.
Each user keeps their own conversation history, reachable from the History button in the panel.
Sharing conversations to improve the assistant
On Gatana Cloud, Gatana can keep a reduced copy of assistant conversations to find and fix the assistant's own gaps. Whether it does depends on your plan:
- Free plan: sharing is a term of the plan. It is always on and cannot be turned off.
- Paid plan: sharing is off until an organization owner turns it on. The choice is offered when the assistant is turned on, and an owner can change it at any time in the assistant's settings or under Settings → Features → AI assistant. The agreement is recorded with the time and the owner who gave it.
- On-premise: nothing is collected, and the choice is not shown.
An organization that moves from the free plan to a paid one stops sharing at that moment, and stays that way until an owner chooses otherwise.
The copy keeps the conversation's text and structure, with the values taken out:
- Tool arguments are reduced to their shape:
{ slug: 'github' }becomes{ slug: '<string:6>' }. - Tool results are dropped. Error messages are kept.
- Any tool call whose name suggests a credential or a secret is dropped entirely, and secrets are scrubbed from everything that remains.
A conversation is copied only after it has been quiet for a few hours, so none is taken mid-way. The copy is stored encrypted and is deleted after 90 days.
Turning sharing off deletes every copy Gatana still holds, not only future ones.
Bringing your own model
An organization can point the assistant at a model account of its own instead. Conversations then go to that endpoint, on your inference budget, and Gatana sends nothing to OpenRouter — the sub-processor entry above stops applying to the assistant. Choose BYOK under Settings → Features → AI assistant, where the daily token limit also appears, since the spend becomes yours to cap.
Three kinds of endpoint are supported. They differ in how a request is authorized rather than in what is asked of the model:
| Provider | What to enter |
|---|---|
| OpenAI-compatible endpoint | Base URL, model, API key. Anything that speaks the OpenAI chat completions protocol: vLLM, DeepSeek, Together, OpenRouter under your own key, or a gateway of your own |
| AWS Bedrock | Region, model or inference profile ID, and either a Bedrock API key or an IAM access key pair (with a session token, if the pair is temporary) |
| Azure OpenAI Service | Resource name, deployment name, API key, and optionally an API version to pin |
Credentials are encrypted with your organization's key and are never sent back to the dashboard. To change a model, a region or a deployment later, leave the credential boxes empty and the stored credential is kept; type a new one to rotate it.
If the endpoint cannot be used — no credential, an incomplete one — the assistant stops and says so rather than falling back to Gatana's provider, so nothing leaves your account unnoticed. Switching back to Gatana-provided leaves the credentials stored, so switching to your own account again does not mean entering them a second time.