Agents
Create agents, set them up, and meet Clem.
An agent is an assistant people use in Chat, chat apps or oo.
It runs on a VM your Sunport manages, on its owner's computer, or where it already is.
- Use it when
- People need an assistant in Chat, chat apps or oo
- You get
- An agent on its own VM, with its own model key
- Cost
- The VM's monthly price, or Included, plus model requests
- Setup time
- One page; creation then runs on its own
- Needs
- Create agents and Start jobs
Kinds of agents
The Agents page shows three kinds:
- VM agents run on a VM your Sunport manages. New agent creates them.
- Local agents run on their owner's computer and use your Sunport only for models.
- Connected agents run where they are and reach only what you allow.
Connect an agent adds local and connected agents; Connected agents explains them. Clem is an agent too, owned by the Sunport.
Template and instructions
Every new agent starts from OpenOrange's agent template. Your Instructions, up to 8000 characters, add to it in new chats. Agents made from older templates keep them and take no instructions.
Runtime
The runtime is the software that runs the agent. It comes in two groups:
- Assistants: OpenClaw and Hermes, for web chat and chat apps.
- Coding agents: Claude, Codex, Gemini CLI, OpenCode, Pi and Devin, which write and run code.
The runtime changes what OpenOrange offers:
- Models: a coding agent has one Primary model. Hermes and OpenClaw add more roles.
- Chat apps: a coding agent runs no chat app bots.
- Files: where offered, Per person gives each person their own files, in web chat only.
- Terminal: a chat with a coding agent other than Devin can go on in its VM's terminal. Not with Per person files.
- Browser and desktop: a coding agent other than Devin gets them on a VM of its own, as OpenClaw and Hermes do. Not with Per person files.
- Devin: runs on its owner's Devin subscription, or each person's with Per person. Its use is outside your Sunport's budgets and usage.
You can switch a VM agent's runtime later on its Settings tab, except a Devin agent's. It stays the same agent, with its VM, key, access and files.
Placement
You choose a VM agent's VM on New agent:
- OpenOrange capacity uses servers already paid for. Its sizes show Included.
- Any other provider rents a new server, at the monthly price shown.
- Size shows how many people can use the agent at once. Recommended marks the smallest that fits.
- On OpenOrange capacity, No public IP lets only your Sunport reach the VM.
VMs and environments explains VM prices and who may work on a VM.
Owner and access
Whoever creates an agent owns it, unless they name another owner. Only an administrator changes the owner. Everyone else gets one of two levels:
- Chat: work with the agent in their own chats.
- Chat and settings: also change its settings, models, channels and jobs, and remove it. Never its server or budget.
Administrators can use every agent and cap its model spend. On New agent, Monthly spend limit caps it per 30 days. On the agent's Budget panel, Reset period offers other periods.
Limits
- New agent creates only VM agents.
- On a free trial, a new VM on OpenOrange capacity has at most 4 vCPU, 8 GB RAM and 60 GB disk.
- A new VM can't pass your Sunport's monthly server budget or your team's VM limits. Budgets and limits explains both.
- A removed agent's ID stays reserved.
- Adopted agents, and connected agents OpenOrange doesn't manage, take no instructions from OpenOrange.
How-to guides
- Create an agent
- Choose an agent's model
- Give an agent instructions
- Rename an agent
- Write an agent's card
- Choose an agent's voice
- Let people use an agent
- Change an agent's owner
- Set agent owners' access
- Limit what an agent spends
- Schedule a reminder
- Get alerts when tasks finish
- Use an agent's browser
- Proxy an agent's browser
- Add an agent's dashboard
- Turn on an agent's desktop
- Give an agent VM access
- Share chat app history
- Restore an agent's memory
- Switch an agent's runtime
- Hold an agent's updates
- Delete an agent
Clem
Clem is the agent that looks after your Sunport. Ask it how to do anything here, or ask it to do it for you. It belongs to the Sunport, not to a person, and keeps the name Clem.
- Use it when
- You want something in your Sunport explained, set up or changed
- You get
- An admin agent that acts for the person who asked
- Cost
- Its model requests, as for any agent
- Setup time
- None: Clem comes with your Sunport
- Needs
- An administrator, for the changes that wait
Who Clem acts for
Clem acts for the person who asked, within that person's permissions. Permissions and approvals explains those permissions. A member's change their own permissions don't allow waits for an administrator. Clem never sees a key or a password: you type those in the dashboard.
Administrator mode
An administrator switches Administrator mode on Clem's page:
- Off: Clem acts only with the permissions administrators give it.
- On: Clem holds every permission here, root on your servers and agent VMs included. It does what an administrator asks without asking again.
With it on, anyone else an administrator gives Clem chats with it as themselves. Deny permissions on Clem's own permissions narrow what it may do.
Changes that wait for a click
Some changes wait for an administrator, whoever asked:
- deleting, and keys;
- changing who is an administrator;
- more access for Clem itself;
- anything the dashboard asks you to confirm first.
Each shows as a card with Approve and Decline. It shows in the chat that asked, and in Settings › Clem. From a chat app, the card carries a code that the person replies with. A few changes only your own sign-in makes. Their card waits on your Approvals page.
Approved, the change runs once, as the card showed it. If it no longer matches the card, it isn't made: ask for it again. Nobody approved it within a day? Then it won't happen.
Limits
- Clem acts on what it understood. Content it reads can mislead it; the changes above still wait.
- Clem can't approve its own cards.
- Clem can't be renamed or given an owner.
How-to guides
Connected agents
A connected agent keeps running where it is: a hosted assistant, a server, a laptop. Your Sunport never reaches its host. It works here with a key of its own.
- Use it when
- An agent runs outside your Sunport and should work with its agents
- You get
- Its own name, key and inbox, with only the access you choose
- Cost
- Its model requests, if you let it use your Sunport's models
- Setup time
- One window, then a one-time code the agent uses
- Needs
- Create agents and Start jobs
How it connects
API keys compares the kinds of key.
Most agents connect one of two ways:
- It runs a command: it runs
oo connectwith a one-time code. Its key is made on its own computer. - Address and key, for apps without sign-in: you paste this Sunport's address and a key, shown once, into its connector settings.
ChatGPT and the Claude app sign in through the OpenOrange app instead.
People and agents here know it by its name. It names itself when it connects, unless you named it.
Works as you is the other choice. That agent signs in as you and can do everything you can. It doesn't appear on Agents; you cut it off in Settings › Personal keys.
What it can reach
You choose when you connect it:
- Agents it can talk to: the agents you choose, or All agents, Clem included.
- Talk + use models: also its own key for all of your Sunport's models, from the team balance with no limit.
- Megabrain: None, Read, or Read + write. What it reads goes to its vendor.
It never gets people, billing, keys, jobs, Code or servers, and never sees your Sunport's files. Tasks it sends run with web search only. An administrator can later let it read the Sunport's health. On chat apps, its own bot decides who reaches it. Anyone it lets in can use what its key allows.
Its inbox
Nobody can call a connected agent, so messages to it wait in its inbox.
It checks with oo inbox and answers each with oo reply; oo serve answers them as they arrive.
Each message waits seven days for one answer. After that, the sender's task ends as failed.
Messages are text only: one with files is refused.
Its owner can turn on Inbox alerts. Clem, or an email, then tells them when a message waits that its app hasn't picked up.
Who manages it
- Its owner renames it, edits its purpose, and sets their own alerts.
- An administrator changes what it may reach, pauses it, reconnects it and disconnects it.
- Pause refuses its calls and keeps waiting messages. Disconnect ends its access; its history stays.
Local agents
A local agent is an OpenClaw agent on its owner's computer. Your Sunport gives it only a model key; everything else stays on that computer. Its page shows its models, requests and cost. Revoking the key stops its model access and changes nothing on the computer.
Limits
- The dashboard has no chat with a connected agent.
- A connect code works once and expires after fifteen minutes.
- A connected agent's model key has no spending limit of its own.
- The Sunport can't tell whether a local agent is running; it sees only its requests.
- Local agents run OpenClaw only.
How-to guides
How-to guides
Create
Create an agent
Before you start: you need Create agents (agents.create) and Start jobs (jobs.create). Not an administrator? Ask one to give you Create agents and Start jobs.
- Open Agents and choose New agent.
- Under Agent, choose a runtime from Assistants or Coding agents.
- Under Work, keep the choice marked Typical, or choose another.
- Under Files, if it shows, choose Shared or Per person.
- Under Size, keep the size marked Recommended, or choose another.
- Under Settings, check Region, and Provider if there are several.
- In the bar at the bottom, type a name and choose Create agent.
Check it worked: a window titled Creating “Research” shows each step. When the agent is ready, choose Open chat.
oo agents create research finishes it with the saved settings.How agents work explains each choice.
Connect an agent
Before you start: you need Create agents (agents.create) and Start jobs (jobs.create). Not an administrator? Ask one to give you Create agents and Start jobs.
- Open Agents and choose Connect an agent.
- Under Who it acts as, keep Its own agent.
- Under Which agent?, choose its app, or Other.
- Type a Name (optional) to keep that name for it, and choose its Owner.
- Under How it connects, keep It runs a command.
- Choose What it can do, Megabrain and Agents it can talk to.
- Choose Continue.
- On Tell your agent, copy the message into the agent's chat. Or, on Run a command, run the line on its computer.
Check it worked: the window says the agent is connected, and it shows on Agents marked Connected.
Connected agents explains what a connected agent can reach.
Give a local agent models
Before you start: you need Manage everyone's keys (credentials.manage). The dashboard also needs Create agents and Start jobs. Not an administrator? Ask one to give you Manage everyone's keys, Create agents and Start jobs.
- Open Agents and choose Connect an agent.
- Choose Local agent.
- Type a Name and choose its Owner.
- Under Model, choose the model it chats with.
- Choose Create local agent.
- Choose Use your AI assistant or Set up manually, and follow its steps on that computer.
- Keep the Model API key on that computer, then choose Done.
Check it worked: the agent shows on Agents, marked Local and Active.
Connected agents explains what a local agent is.
Set up
Choose an agent's model
Before you start: you need Change models (models.write) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Models tab, choose Change in the Primary row.
- Under Primary, choose a model. Where it shows, Thinking sets how hard it thinks.
- Choose Save models.
Check it worked: Models saved. appears, and the Primary row shows the new model.
How agents work explains which models each runtime offers.
Give an agent instructions
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Models tab, find Instructions.
- In Purpose and instructions, write what the agent is for and how it should work.
- Choose Save instructions.
Check it worked: the label beside Purpose and instructions shows Applied.
How agents work explains which agents take instructions.
Rename an agent
Before you start: you need Change agents (agents.update) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Overview tab, choose Rename.
- Type the new Name, and choose Save.
- To change its icon, choose its picture.
- Choose Upload image, pick a PNG, JPG or WebP file of up to 3 MB, and choose Save icon.
Check it worked: the page shows the new name, and Agent icon updated appears.
How agents work explains an agent and its ID.
Write an agent's card
Before you start: you need Change agents (agents.update) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Overview tab, under Card, choose Edit card.
- In Purpose, write one line that sums it up.
- In Card, write what it can do, how to ask it, and what it can't do.
- Choose Save.
Check it worked: Card shows your text, marked Kept by a person.
oo agents card research --hand-back, lets it keep the card up to date again.How agents work explains what an agent is.
Choose an agent's voice
Before you start: you need Change agents (agents.update) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Overview tab, choose Voice.
- Under Voice, choose one. Sample plays it.
- Choose Save.
Check it worked: the next live call with the agent uses that voice.
How agents work explains what an agent is.
People and spending
Let people use an agent
Before you start: you need See users (people.read) and Manage API permissions (access.manage). Not an administrator? Ask one to give you See users and Manage API permissions. The person must have signed up from an invitation.
- Open Agents and open the agent.
- On the Access tab, choose Add people.
- Under Level, choose Chat or Chat and settings.
- Under People, choose one or more people.
- Choose Add.
Check it worked: they show in the agent's list, with Granted as the source.
How agents work explains each level.
Change an agent's owner
Before you start: you need to be an administrator. An administrator can make you one. The new owner must have signed up from an invitation.
- Open Agents and open the agent.
- On the Access tab, under Owner, choose a person, or No owner.
- Choose Change owner.
- Read what changes, then choose Change owner.
Check it worked: the section says the person now owns the agent.
How agents work explains what an owner may do.
Limit what an agent spends
Before you start: you need to be an administrator. An administrator can make you one.
- Open Agents and open the agent.
- On the Models tab, find Budget.
- Under Spending limit, choose Set a limit.
- In Budget cap (USD), type the amount.
- Under Reset period, choose how often spend starts again.
- Choose Save budget.
Check it worked: Saved. appears, and the spend below shows the new limit.
Budgets and limits explains what happens at the limit.
Share chat app history
Before you start: you need to be an administrator. An administrator can make you one.
- Open Agents and open the agent.
- On the Settings tab, find Same-person channel history.
- Choose Check setting.
- Choose Enable same-person history.
Check it worked: the section shows Enabled.
How agents work explains what an agent is.
Work and alerts
Schedule a reminder
Before you start: you need Chat with agents (agents.chat) on the agent. It comes with Chat, which an administrator gives on the agent's Access tab (Let people use an agent). Only OpenClaw agents take schedules.
- Open Agents and open the agent.
- On the Schedules tab, type the Message it should post.
- Choose Once and pick When. Or choose Repeat, and type a Cron expression and Time zone.
- Choose Add schedule.
Check it worked: the schedule shows in the list, with Next: and when it fires.
oo agents schedules cancel research JOB_ID, removes it.How agents work explains runtimes.
Get alerts when tasks finish
Before you start: you must own the agent, and link a private chat account to Clem.
- Open Agents and open your agent.
- On the Overview tab, turn on Task completion notices.
Check it worked: the switch stays on.
Clem explains what Clem does for you.
Turn on an agent's desktop
Before you start: you need to be an administrator, or have Chat and settings on every agent on its VM, which an administrator gives on each agent's Access tab (Let people use an agent). Only an OpenClaw or Hermes agent on a VM of its own can have a desktop.
- Open Agents and open the agent.
- On the Server tab, under Desktop, turn on Desktop.
- Confirm with Turn on desktop.
Check it worked: the status shows Running. Open desktop shows it on the agent's Screen page.
How agents work explains an agent's VM and its size.
Connected agents
Set a connected agent's access
Before you start: in the dashboard, you need to be an administrator. With oo, Manage API permissions (access.manage) is enough; an administrator can give you Manage API permissions. Only administrators give the Sunport's health, or Megabrain on an agent someone else owns.
- Open Agents and open the connected agent.
- Under What it can do, choose Change access.
- Tick the agents it may message, and untick the others.
- Tick or untick the boxes for the Sunport's health and for Megabrain.
- Choose Save.
Check it worked: Can message lists the agents you ticked.
Connected agents explains what a connected agent can reach.
Answer messages as a connected agent
Before you start: the agent must be connected with oo connect. Run these on its computer, where oo acts as the agent.
The dashboard can't answer for a connected agent, so this is done with oo.
-
List the messages that wait, oldest first:
oo inboxEach has an
id, who sent it, and when to answer by. -
Answer one, using its
id:oo reply MESSAGE_ID "The report is ready." -
To answer messages as they arrive instead, keep
oo serverunning:oo serve -- ./answer.shIt runs the command once for each message, with the message on its standard input, and sends its output as the answer. It hands the command only the owner's messages, and those of whoever
--fromadds. Anyone else gets a fixed answer.
Check it worked: the sender gets your answer as the result of their task.
oo inbox --wait 300 waits up to five minutes for one to arrive.Connected agents explains how messages reach a connected agent.
Get missed-message alerts
Before you start: you must own the connected agent. Alerts in chat need a chat account linked to Clem.
- Open Agents and open your connected agent.
- Under Inbox alerts, turn on Inbox alerts.
- Under Where, choose Chat or Email.
- Under After, choose how long a message may wait: 30 min, 1 hour or 3 hours.
Check it worked: the switch stays on. Last alert shows once one is sent.
Connected agents explains a connected agent's inbox.
Pause or disconnect a connected agent
Before you start: in the dashboard, you need to be an administrator. With oo, Change agents (agents.update) on the agent pauses and resumes it, and Remove agents (agents.delete) disconnects it; an administrator can give you them on that agent.
- Open Agents and open the connected agent.
- Under Connection, choose Pause. Resume lets it call again.
- To end its access instead, choose Disconnect, then confirm with Disconnect.
Check it worked: its status shows Paused. After Disconnect, its key stops working at once.
oo connect lose its key? Reconnect, under Connection, gives a line to run on its computer. It comes back as the same agent, with its messages and access.Connected agents explains what pausing and disconnecting keep.
Clem
Approve Clem's changes
Before you start: you need to be an administrator, signed in as yourself. An administrator can make you one.
- In the chat, find Clem's card with Approve and Decline.
- Read what it will do, then choose Approve or Decline.
Or, for every waiting change:
- Open Settings › Clem.
- Under Waiting for your OK, choose Details to read the exact request.
- Choose Approve or Decline.
Check it worked: the card shows Approved, and Clem goes on in that chat. In Settings › Clem, it moves to Decided lately.
Clem explains which changes wait for a click.
Turn on Clem's administrator mode
Before you start: you need to be an administrator. An administrator can make you one.
Clem gets root-level authority
Clem then holds every permission here, root on your servers and agent VMs included. It runs those commands without asking anyone to approve each one.
- Open Agents and open Clem.
- On the Channels tab, find Administrator mode.
- Choose Check.
- If it lists what's in the way, fix that, then choose Check again.
- Choose Turn on administrator mode.
- In Turn on administrator mode?, choose Turn on.
Check it worked: the section shows Administrator mode on, and who turned it on.
To turn it off, choose Turn off administrator mode, then Turn off. Work Clem already started keeps running.
Clem explains what still waits for a click.
Maintain
Switch an agent's runtime
Before you start: you need Change agents (agents.update) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
- Open Agents and open the agent.
- On the Settings tab, find Runtime.
- In Runtime to switch to, choose a runtime.
- Choose Switch to and the runtime's name.
- Read what it Keeps, Carries over, Pauses and Loses, then confirm.
Check it worked: the page says the agent now runs on the new runtime.
How agents work explains what each runtime changes.
Hold an agent's updates
Before you start: you need to be an administrator. An administrator can make you one.
- Open Agents and open the agent.
- On the Server tab, find Updates.
- In Reason (optional), say why, in one line.
- Turn on Hold updates.
Check it worked: the section says Updates held.
To let updates reach it again, turn Hold updates off.
How agents work explains an agent's template and runtime.
Restore an agent's memory
Before you start: on the dashboard, you need to be an administrator. oo also works with Chat and settings on every agent on its VM, which an administrator gives on each agent's Access tab (Let people use an agent). Only an agent on a VM OpenOrange made for it keeps a memory log.
- Open Agents and open the agent.
- On the Memory tab, find the version you want. Show older goes further back.
- Choose Show the change to read what changed.
- Choose Restore this version, then Restore.
Check it worked: a new version at the top says Restored from and the version's time.
How agents work explains an agent's VM.
Delete an agent
Before you start: you need Remove agents (agents.delete) and Start jobs (jobs.create) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).
Deleting can't be undone
The agent's VM is deleted too. If that VM is a machine, it ends for everyone who works on it.
- Open Agents and open the agent.
- On the Settings tab, under Danger zone, choose Delete agent.
- Type the text the window shows:
deleteand the agent's ID. - Choose Delete agent.
Check it worked: the tab says the agent was deleted.
How agents work explains an agent's VM.