Agent Settings
Configure agent identity, computer persistence, working hours, model, caching, context memory, actions, queue, mail, and more — all from a single Settings page.
Tip: Your agent can update its own settings. Ask it — "Change your name to DataBot", "Set your timeout to 30 minutes", or "What are your current settings?"
Overview
The Settings page is the centralized hub for all agent configuration. Click the Settings button in the agent header to open it.
Settings is organized into sections via a sidebar navigation. On desktop, the sidebar appears on the left; on mobile, it's a horizontal scrollable bar at the top.
| Section | What It Configures |
|---|---|
| General | Agent title, persona name, description, and timezone |
| Computer | Computer persistence mode — persistent (default) vs. on-demand |
| Working Hours | Days and hours the agent is allowed to operate |
| Chat | Default AI model, prompt caching, and context memory |
| Roles & Permissions | How the agent treats each sender tier — and the rules Communa enforces |
| Actions | Auto-save toggle and action history management |
| Queue | Processing interval, max items per run, and auto-queue |
| Outbound email whitelist | |
| Danger Zone | Delete the agent permanently |
General
Title
The agent's display name — shown in the sidebar, headers, agent list, and everywhere the agent is referenced.
Agent Name (Persona)
An optional persona name the agent uses for itself. During onboarding, the agent often picks its own name (e.g., "ResearchBot" or "DataBot"). This is how the agent refers to itself in conversations.
Description
An optional description of what the agent does. Helps team members understand the agent's purpose at a glance.
Timezone
Set the timezone your agent operates in. It defaults to your current location, so most people don't need to change it.
If you're setting up the agent for someone in another country, open the dropdown and pick their city — it's organized by region (Africa, America, Asia, Europe, Pacific) with the current local time shown next to each option, so you can see at a glance whether you've got the right one.
The agent uses this timezone everywhere it matters — when reasoning about "today" or "this morning" in chat, when checking working hours, and as the default for scheduled jobs — so everything stays aligned.
Computer
Note on terminology: Throughout the docs we use computer to mean the agent's isolated Linux desktop environment. The underlying technology is sometimes called a sandbox — they refer to the same thing.
Computer Persistence
Choose how the agent's computer behaves when idle or put to sleep. Select a mode by clicking the corresponding card — the change takes effect the next time the computer starts.
Comparing the Two Modes
| On-Demand | Persistent (default) | |
|---|---|---|
| When agent sleeps | Computer is destroyed — clean slate next time | Computer is paused — frozen in place |
| When agent wakes | Fresh computer started (~10-15s) | Resumes from frozen state (~1s) |
| Browser sessions | Lost — websites logged out, tabs closed | Preserved — stays logged in, tabs still open |
| Installed packages | Gone — must reinstall on next wake | Preserved — pip, npm, apt packages remain |
| Running processes | Terminated | Frozen and resumed automatically |
| Files on the computer | Deleted (unless synced to stored files) | Preserved in place |
| Compute cost while idle | None | None (paused computers use no compute) |
When to Use Each Mode
Persistent (default, recommended) is ideal for agents that build up state over time or need to pick up exactly where they left off:
- Agents that log into websites (CRMs, dashboards, admin panels) — sessions and cookies survive across pauses, so the agent doesn't re-authenticate every time
- Agents with heavy environment setup — Python/Node packages, databases, compiled tools that take minutes to install
- Agents running background services — local servers, watchers, or daemons that should keep running
- Long-running workflows where context continuity matters — open browser tabs, partially completed forms, in-progress downloads
On-Demand is an alternative for agents that do stateless, self-contained tasks — each run is independent and doesn't rely on anything from the previous session:
- Email triage and summarization
- Web research and data scraping
- Quick file conversions or one-off scripts
- Tasks where a clean environment is actually preferred
Tip: Persistent mode is the default because most agents benefit from state continuity. Only switch to on-demand if your agent truly doesn't need anything from previous sessions.
What Changes in the UI
When Persistent mode is active:
- The Sleep button becomes Pause — the confirmation dialog reassures you that all state is preserved instead of warning about data loss
- Timeout pauses instead of killing — if the computer times out, it pauses automatically rather than being destroyed
- Resume replaces Wake — clicking "Resume Agent" reconnects in ~1 second instead of starting a fresh computer
- Scheduled runs and channel messages auto-resume a paused computer seamlessly
Working Hours
Configure the days and hours during which the agent is allowed to operate. Outside working hours, scheduled runs and queue processing are paused.
Working hours are displayed in the agent header as a visual indicator showing whether the agent is currently within its operating window.
The timezone shown here is the agent's overall timezone, set in General settings — change it there and working hours will follow.
Chat
Default Model
Override the system default AI model for this specific agent. Useful when different agents have different cost/performance needs — a quick-task agent can use a lighter model while a research agent uses the most capable one.
Select System Default to follow the platform-wide model setting.
Cache Strategy
Control prompt caching behavior to reduce costs on repeated interactions:
| Strategy | Description |
|---|---|
| No Cache | Every request is processed fresh — highest cost, best for volatile prompts |
| 5 Minutes | Recommended — caches the system prompt for 5 minutes, good balance of freshness and savings |
| 1 Hour | Maximum savings — caches for 1 hour, best for agents with stable system prompts |
Context Memory
Controls how much conversation history the AI sees when generating responses. Choose from three presets:
| Preset | Text Messages | Tool Calls | Best For |
|---|---|---|---|
| Minimal | 20 | 10 | Short tasks, quick automations, lowest cost |
| Balanced | 50 | 30 | Most agents — recommended default |
| Extended | 150 | 80 | Complex multi-step workflows, long conversations |
- Text Messages — User, assistant, and system messages loaded from conversation history
- Tool Calls — Tool call/result pairs (computer actions, web searches, file reads, etc.)
Advanced Context Settings
For fine-grained control, expand Advanced Context Settings inside the Context Memory section to customize each value individually:
| Setting | Range | Default | Description |
|---|---|---|---|
| Text Messages | 10 – 200 | 50 | Max user + assistant messages loaded from history |
| Tool Interactions | 5 – 100 | 30 | Max tool call/result pairs kept in context |
Changing any slider automatically switches the preset to Custom. Pick a preset button to reset all values.
Tip: Start with Balanced. Only increase if your agent loses track of earlier context in long sessions. Reduce to Minimal for simple, repetitive tasks to save on token costs.
Roles & Permissions
The Roles & Permissions section controls how your agent treats each person who messages it, based on their trust tier. When someone sends a message, the agent knows which tier they belong to and reads tier-specific guidance before responding.
There are four tiers:
| Tier | Who They Are |
|---|---|
| Owner | You — the workspace creator, with full authority |
| Admin | Trusted teammates with broad permissions |
| Member | Regular workspace teammates |
| External | Anyone messaging via Telegram, WhatsApp, Voice, or Email who isn't a workspace member |
What Each Tier Shows
Selecting a tier reveals two things:
- Can / Cannot — The hard rules. The Cannot rules are enforced by Communa server-side, not just suggested to the agent. If a Member or External sender asks the agent to do something on this list, the underlying tool call is blocked and returns a permission error — so the agent declines instead of trying.
- The prompt — The customizable text the agent reads about how to treat this sender. Edit it to make the agent friendlier, stricter, or more specific to your use case.
What's enforced per tier
| Action | Owner | Admin | Member | External |
|---|---|---|---|---|
Change agent settings (settings_manager) | ✅ | ✅ | ❌ | ❌ |
| Create / edit / delete skills | ✅ | ✅ | ❌ | ❌ |
| Run tasks, search, read files, use tools | ✅ | ✅ | ✅ | ✅ (scoped) |
Note: Credentials are never agent-mutable for any tier. The agent can only use a stored credential at runtime (its value stays hidden); it has no tool to create, read, or edit raw credential values. Credential management happens in the dashboard UI and is gated by workspace role, not sender tier.
Customizing a Tier's Prompt
Each tier ships with a sensible default — cooperative and broad for Owners, helpful but careful for Members, careful and scoped for External senders. Edit the prompt text and save to override it.
The External tier prompt supports placeholders that are filled in at runtime so the same prompt works across every channel:
| Placeholder | Resolves To |
|---|---|
{{channelLabel}} | The channel the person is using (e.g. "Telegram", "WhatsApp") |
{{participant}} | The sender's name or identifier |
{{idLine}} | A short line identifying the sender's contact details |
Click Reset to default on any tier to restore the original prompt. Every change is recorded in the Change Log and can be reverted.
Tip: Start with the defaults — they cover most situations. Customize a tier when you want specific behavior, e.g. "For External senders, always offer to escalate to a human if they sound frustrated." For deeper background on roles, people, and what's enforced vs. guided, see People & Permissions.
Actions
Auto-Save Actions
Toggle whether AI actions are automatically saved to the action history. When enabled, every action the agent performs during a chat session is captured in the Actions tab in real time. When disabled (default), actions appear in chat with an "Add" button so you can pick exactly which actions to keep in your sequence.
Clear Action History
Permanently delete all saved actions from this agent. This shows a confirmation dialog — cleared actions cannot be recovered.
Queue
Processing Interval
How often the system checks for and processes pending queue items. Options range from every 5 minutes to every 24 hours.
Max Items Per Run
The maximum number of queue items processed in a single scheduled run. Prevents runaway processing on large queues.
Auto-Queue Incoming Emails
When enabled, every incoming email is automatically added to the agent's queue as a task item. Combined with a processing schedule, this creates a fully autonomous email-processing agent.
Whitelist
For security, agents can only send emails to whitelisted addresses:
- Team members — Always allowed (automatically whitelisted)
- The agent's own address — Always allowed
- Custom addresses — Add specific email addresses the agent is permitted to send to
Enforce whitelist — A switch at the top of the Mail settings. On by default. Turning it off requires acknowledging the risks in a confirmation dialog, after which the agent can send to any recipient. See Mail → Disabling the Whitelist for details.
The whitelist applies to outbound emails only. Anyone can send emails to the agent regardless of the whitelist.
Danger Zone
Delete Agent
Permanently delete the agent and all associated data — chat history, files, datasets, credentials, skills, email, queue items, scheduled jobs, and runs. This action cannot be undone.
Editing Settings
Settings can be changed two ways:
Through the UI
Click the Settings button in the agent header to open the Settings page. Navigate between sections using the sidebar and make changes directly.
Through Conversation
The agent can update its own settings using the settings_manager tool. Just tell it:
- "Change your name to ResearchBot"
- "Update your description to 'Handles daily email triage and reporting'"
This chat-first approach means you rarely need to visit the Settings page — your agent is its own settings panel.
Audit trail: Every change made here — whether by you in the UI or by the agent via chat — is automatically recorded in the Change Log with full before/after values, actor attribution, and timestamps.
Tips & Best Practices
- Use descriptions — A clear description helps team members understand what each agent is for
- Let the agent self-configure — During onboarding, the agent sets its own name, persona, and settings through conversation
- Match context to the task — Simple agents (e.g., email triage) work well with Minimal context; research or multi-step agents benefit from Extended
- Monitor token costs — If an agent's per-message cost is higher than expected, try reducing context memory
- Persistent computer is the default — Your agent preserves browser sessions, installed packages, and all state across pauses. Switch to on-demand only if you prefer a clean environment each time
What's Next?
- Agent Overview — Return to the agent overview for a high-level perspective
- Chat & Computer — Learn about the primary workspace
- Context & Configuration — Configure skills, instructions, and tools