Skip to Content

Services and tools

Browsers, machines, accounts, secrets and apps for your agents.

Services are what agents can use besides models: web search, a browser, apps, your computers. Some come with your Sunport. An administrator adds the rest.

Use it when
Agents need more than a model: web search, a browser, an app, your computers
You get
Tools for every agent, and apps at addresses under your Sunport
Cost
No extra cost, a price per use, or a VM of its own
Setup time
None for what comes with your Sunport; minutes for the rest
Needs
An administrator, to add a service

What comes with your Sunport

These need nothing added:

  • Web search: every agent's web search, with links to its sources. It runs on Brave, Exa, You.com or DuckDuckGo.
  • Browser: each OpenClaw or Hermes agent's own browser, on its own VM. It opens sites, clicks, types and takes screenshots. Its Screen page shows it live.
  • Email: sends your Sunport's invitations. Agents can't send email with it.

What an administrator adds

New service on Services adds these:

  • OpenClaw 2.0 dashboard: an OpenClaw agent's own control panel, at its own address under your Sunport.
  • Machine (OpenClaw node): lets chosen OpenClaw agents run commands on your own computers. Machines explains it.
  • Forgejo for git hosting, and Mattermost for team chat: hosted apps, each with its own address and sign-in.

The catalog on Services also offers these, each on its own card:

  • Shared browser: one browser that agents and people use together. People watch its screen or browse in their own tab.
  • Edge gateway: a small server in front of your Sunport that takes its web and model calls.

What it costs

Every service is paid for in one of three ways:

  • No extra cost: it runs on something already paid for. A dashboard and an agent's browser run on the agent's VM. Machines run on your own computers.
  • Per use: web search per search, email per email, billed through OpenOrange. DuckDuckGo is free.
  • A VM of its own: a shared browser or a hosted app, billed as compute. Its cost names the cheapest VM size that fits.

A VM with no price shows Included. A hosted app on Hetzner Cloud adds 20% for daily backups.

Prices show to administrators, and to a key that may read billing. Everyone else sees how a service is paid, never how much.

Each service's page shows this month's calls, by day and by agent, its list price and its health. Services are free while they are tested. shows while OpenOrange charges nothing for services.

Who adds a service

  • Services is for administrators. A person given a shared browser sees their shared browsers there instead.
  • Clem adds a dashboard, a shared browser or a hosted app when an administrator asks.
  • Any agent reads the catalog with oo services catalog, and suggests a service with its cost.

Web search engines

Every agent searches with one engine, which an administrator switches:

  • DuckDuckGo: free, with no account. It reads DuckDuckGo's results page, not an official API.
  • Brave, Exa and You.com: charged per search, at list price with no markup.

Exa may use your search queries to train its models by default.

Limits

  • Email sends only invitations.
  • An agent's own browser is that agent's alone. Where several agents share one login, use a shared browser.
  • A dashboard opens one OpenClaw agent on a VM of its own. Each agent gets one.
  • A new address shows only once it answers.
  • A search engine switch reaches Clem and OpenClaw agents on VMs. Other agents keep their own search.
  • OpenOrange Code has no web search on DuckDuckGo.
  • VMs and domains aren't services: they're on Compute. Publish an app gives your own app an address.

How-to guides

Connections and secrets

A connection lets you, or one agent, use your Google account. A secret is a key or password an agent's tools use, kept out of every chat.

Use it when
An agent needs your Google account, or a key its tools use
You get
Access you approve with Google, and secrets kept out of every chat
Cost
No extra cost
Setup time
One approval with Google, or one pasted value
Needs
Your own sign-in; Manage agents' keys for a secret the whole agent uses

Connections

A connection gives you, or one agent, access to a Google account. You approve each permission with Google.

  • Who can use this connection: Only you, or one agent you can chat with.
  • OpenOrange's Google app offers Gmail labels and Drive files you choose.
  • Your organization's Google app, which an administrator sets up, can ask for any permission Google allows it. That includes Gmail, Calendar, Docs, Sheets, Contacts and Tasks.

A connection keeps its permissions until you disconnect it. An agent can ask for one: it sends you a link, and you approve with Google.

Some actions wait for you. An agent deletes data, sends messages, invites people or shares access only after you approve that exact action in Settings › Approvals.

When other people also use the agent, it asks before using your connection in your chat app direct message. Your yes lasts 30 minutes, in that direct message only.

Google content an agent reads can enter its conversation. Its model's provider then processes it.

Secrets

A secret is an API key, token, password or file an agent's tools use. Your Sunport keeps it encrypted and puts it on the agent's own VM. The agent's commands read it as an environment variable of its name, from their next run. A file's variable holds the file's path.

Nobody sees a value again, in the dashboard or in a chat. The agent itself can read it.

A secret is for one of two audiences:

  • Whole bot: the agent uses it everywhere. Whoever manages the agent's secrets sets it: administrators, owners where owners manage their agents, and anyone given Manage agents' keys.
  • Just for me: anyone who may chat with the agent sets their own. The agent uses it only in their own chats with it, never in a group or a schedule.

Someone who may only chat with the agent can Offer a secret for the whole agent. The agent gets it once someone who manages it approves.

Only a person sets a value. An agent, or Clem, never passes one on.

When an agent asks

An agent that needs a secret asks the person it's talking with:

  • In web chat, a field appears in the chat.
  • Elsewhere, they get a private link. It opens one field and Save, and works once, for 15 minutes.
  • Secrets lists the request under Needs attention for the people who manage the agent.

The value goes straight to the agent, never into the chat. A request made with oo secrets request waits in the person's Settings › Approvals instead.

From 1Password

A secret can come from your own 1Password instead of a typed value. You connect a 1Password service account once, under Settings › Connections. Your Sunport reads the value at every delivery and once a day, so a change in 1Password reaches the agent.

Limits

  • Secrets reach agents on a VM of their own, and Clem. An agent that runs elsewhere takes none.
  • A text secret holds up to 32 KiB; a file up to 64 KB.
  • Only an administrator manages Clem's secrets. Clem asks nobody for a secret.
  • Just for me is a rule for use, not a wall: the agent can still read it.
  • 1Password service accounts can't read Private or Personal vaults.
  • Disconnecting Google stops future access. Content already in conversations stays.
  • With a personal Google account, your organization's Google app left in testing works for up to 100 test users. Google ends its connections after 7 days.

How-to guides

Machines

A machine is a computer that people and agents work on together. It is your own laptop or server, or a VM your team shares.

Use it when
An agent needs your computer's files or tools, or a team shares one VM
You get
Agents that run commands on your computers, and VMs with a shared terminal and files
Cost
No extra cost: commands run on your own computers, or on VMs you already run
Setup time
A minute to add the Machines service, then a few minutes for each computer
Needs
An administrator, and OpenClaw agents on VMs of their own

Two kinds of machine

A machine comes in two kinds:

  • A computer: your laptop or server, connected through the Machines service. Chosen agents run commands there.
  • A VM machine: a service VM or an agent's VM. People work on it together, from its own page.

Your main Sunport VM is never a machine. A Sunport has at most 10 machines, of both kinds together.

Computers

The Machines service lists the agents a computer may be given. Only OpenClaw agents on a VM of their own qualify.

Adding a computer gives you one line to run on it. Run it as the user the agents should work as. Its code works once, for 15 minutes.

The line prints three match words. Approve the computer only when the dashboard shows the same three. Each computer takes up to four agents. Linux, macOS and Windows computers can join.

What an agent may run

Each agent on a machine has one level:

  • Run allowed commands: only the programs on its allowlist, by full path, up to 64.
  • Full access: any program, as the machine's user. Allowing a shell or an interpreter amounts to this.
  • Find commands only: checks whether a program exists, and runs none.

On an agent's Works on, the same levels are called Run, Full and Read.

Whoever can message an agent can direct what it runs on a machine. Give machines to agents with a narrow audience.

When you add a computer, two choices protect it:

  • Ends on (optional) ends every agent's access on a date within a year.
  • Owner lock keeps the rules on the computer itself. Nothing in the Sunport changes them.

VM machines

Whoever manages a VM can make it a machine. They become its first admin. Only a VM the Sunport can sign in to can be one: one made with Clem managing it, or an agent's VM.

Its admins add people and teams, each as Member or Admin. Only admins change who works on it.

Everyone on a machine works as one Linux account. So everyone can read and change what is on it:

  • On a service VM, the account is chosen when it becomes a machine: root, or the user machine without sudo.
  • On an agent's VM, it is the agent's own account.

Sunport administrators can also work as root. On an agent's VM, so can the agent's owner.

People open its terminal and files as themselves, and the Sunport's audit names them. Someone taken off a machine is refused at their next request, and their open terminal ends within a minute. What they made there stays.

Agents on a VM machine

A managed OpenClaw agent on a VM of its own can work on a VM machine too, at a level, as on a computer. A person who manages the agent and is an admin of the machine adds it. The Sunport then installs the agent's node there.

An agent runs every chat's commands in one place: its own VM, or one machine it works on. Runs commands on chooses where, for every chat, whoever writes. While that machine isn't ready, the agent's chats run no commands. They never run them elsewhere instead.

On another agent's VM, that agent can read and change what the added agent does there.

Machine setup

The machine setup is what every VM machine starts with: Debian packages, Node with pnpm, Python with uv, and a setup script. The Sunport installs it one step at a time when a VM becomes a machine. Each step skips what the machine already has. The setup script runs as root each time, so it must be safe to run again.

Changing the setup leaves existing machines alone, until one of their admins applies it again. After that, what a machine has is its own. People change it in its terminal, or ask an agent that works there.

Limits

  • Only people add, approve, change and remove machines. Agents, Clem included, at most read them.
  • A Sunport has at most 10 machines, and a machine at most four agents.
  • The Machines service is added and removed in the dashboard only. It goes only once its computers are removed and no agent works on a VM machine.
  • A Windows computer, and a machine whose account is root, take only full access or find commands only.
  • Moving an agent to or from find commands only means removing it and adding it again.
  • On a computer, a removed agent comes back only when you remove the computer and add it again.
  • Hermes, container and connected agents can't work on a machine.
  • Removing a VM machine leaves the VM, with its files. A machine ends with its VM.
  • A service VM machine's account can't change. Remove the machine and make it again.

How-to guides

How-to guides

Services

Check a service's cost

Before you start: in the dashboard, you need to be an administrator. With oo, See services (services.read) is enough, and See billing (billing.read) adds what it costs; an administrator can give you See services and See billing.

  1. Open Services.
  2. Find the service with Search services, or choose a Category.
  3. Read its card's This month and Cost.
  4. Open the service.
  5. Under Price and billing, read How it's billed and List price.

Check it worked: Calls by day and By agent show this month's use, and Health says whether it works.

Use and cost are this month's, in UTC. The charges themselves are on Billing.

Services explains how each service is paid.

Switch the web search engine

Before you start: in the dashboard, you need to be an administrator. With oo, Change services (services.write) on web search is enough; an administrator can give you Change services.

  1. Open Services and open Web search.
  2. Under Search providers, find the engine you want.
  3. Choose Switch beside it.

Check it worked: the engine shows In use.

The dashboard stays up while Clem restarts on the new engine. OpenClaw agents on VMs follow. An agent the switch didn't reach is named under the engine.

Services compares the engines.

Add an agent's dashboard

Before you start: in the dashboard, you need to be an administrator. With oo, you need Change services (services.write) and Start jobs (jobs.create); an administrator can give you Change services and Start jobs. The agent runs OpenClaw on a VM of its own.

  1. Open Services and choose New service.
  2. Choose OpenClaw 2.0 dashboard.
  3. Under Agent, choose the agent. Opens at shows its address.
  4. Choose Add dashboard.

Its page shows each step while the address is published.

Check it worked: the page shows Live. Choose Open dashboard.

The agent's owner and administrators can open it. Others need Open agents in their dashboard (agents.dashboard) and Chat with agents (agents.chat) on it.

Services explains what a dashboard gives.

Remove an agent's dashboard

Before you start: in the dashboard, you need to be an administrator. With oo, you need Change services (services.write) and Start jobs (jobs.create); an administrator can give you Change services and Start jobs.

  1. Open Services.
  2. Under Added services, open the dashboard.
  3. Choose Remove.
  4. In Remove this dashboard?, choose Remove dashboard.

Check it worked: the page shows Removed.

Services explains dashboards.

Browsers

Set up a shared browser

A shared browser lets an agent browse while a person logs in or watches on the same screen.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and choose Shared browser.
  2. In Name, type what people see, such as Supplier portals.
  3. Under Size, choose a VM size. A browser needs at least 2 GB of memory.
  4. Choose Plan the VM.
  5. On the browser's page, check the Price and choose Create VM.

Check it worked: the status reads Ready, and the browser's screen shows.

Once a browser is set up, Shared browser opens it instead. Make another with oo browser create.

Services explains what its VM costs.

Set shared browser access

Only administrators can use a new shared browser. Add the people and agents who need it.

Before you start: in the dashboard, you need to be an administrator. With oo, Manage API permissions (access.manage) is enough to give levels you hold on the browser; an administrator can give you Manage API permissions.

  1. Open Services and open the shared browser.
  2. Under People with access, choose a person in Choose a person.
  3. Choose View to watch, or Control to use it too.
  4. Choose Add.
  5. Under Agents with access, choose Add agent.
  6. Choose the agent, then Use to drive the browser, or View to see it.
  7. Choose Give access.

Check it worked: the person and the agent are listed with their access.

An agent can ask for access itself. It then sends you a link to the browser's page, where you confirm with Give access.

Services explains shared browsers.

Use a shared browser

Watch what agents do in a shared browser, or open your own tab while they keep working.

Before you start: you need View on the browser to watch, and Control to open a tab. Not an administrator? Ask one to add you on the browser's page (Choose who uses a shared browser).

  1. Open Services and open the shared browser.

    The screen opens, marked Watching.

  2. To browse yourself, type a page in Page to open (optional).

  3. Choose Open my tab.

  4. Type and click in the screen. Agents keep working in their own tabs.

  5. To paste a password, choose Paste text, paste it, then Send to clipboard.

  6. Press Ctrl+V or ⌘V in the screen.

  7. When you've finished, choose Close my tab.

Check it worked: the label above the screen reads Your tab.

One person's tab is open at a time. While someone helps an agent, the screen is hidden from everyone else.

Services explains shared browsers.

Help in a shared browser

When a site needs a person, such as a login or a code, the agent asks for one and waits.

Before you start: you need Control on the browser. Not an administrator? Ask one to add you on the browser's page (Choose who uses a shared browser).

  1. Open the link the agent sent, or Open the shared browser on its card in Chat.

    The page shows what the agent needs and why.

  2. Choose Help. Only you see the screen now.

  3. Log in, or do what the agent asked, on the screen.

  4. Choose Done.

Check it worked: the screen shows Watching again, and the agent goes on.

Your help ends after 10 minutes without input. An administrator can end someone's help with End their help.

Services explains shared browsers.

Remove a shared browser

Remove a shared browser nobody needs, to stop paying for its VM.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and open the shared browser.
  2. Choose Remove browser.
  3. Type the browser's name to confirm.
  4. Choose Remove.

Check it worked: it shows Removing, and leaves the list once its VM is gone.

Agents and people lose the browser at once. Its logins, cookies and downloads can't be brought back.

Services explains what its VM costs.

Use an agent's browser

An agent on a VM of its own has one browser, with its logins: any runtime but Devin, and not with Per person files. Watch it work, or use it yourself.

Before you start: to watch, you need Open agents in their dashboard (agents.dashboard) and Chat with agents (agents.chat) on the agent. Both come with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). To act in it, you need Run commands and change VM files (hosts.vm.admin): administrators have it, and so does anyone with Chat and settings on every agent on that VM.

  1. Open Agents, open the agent, and choose Browser.

    Its Screen page shows the browser live.

  2. If the browser isn't open, choose Open browser.

  3. Click and type in the screen. The agent sees what you changed before it acts.

  4. On a phone, choose Zoom in to read it, and Fit to screen to go back.

Check it worked: the screen shows the agent's browser, and your clicks reach it.

In web chat, the Side panel button shows the same browser under Browser. Clem has no browser here.

Services explains an agent's own browser.

Help in an agent's browser

When a site needs a person, such as a login, a 2FA code or a CAPTCHA, the agent asks and waits.

Before you start: you need Run commands and change VM files (hosts.vm.admin) on the agent, and access to watch its browser. Administrators have both. So does anyone with Chat and settings on every agent on that VM, which an administrator gives on each agent's Access tab (Let people use an agent).

  1. On the agent's help card in the chat, choose Open Research's browser.

    From a chat app, open the link the agent sent instead.

  2. If the agent named a page, choose Open the page.

  3. Do what it asked in the browser. Only you see the screen while you help.

  4. Choose Done.

Check it worked: the card says you finished in the browser, and the agent goes on.

Help ends after 10 minutes without your input, and an ask ends after 30 minutes with nobody helping.

Services explains an agent's own browser.

Proxy an agent's browser

An agent's browser goes out from its VM's own address. Some sites block that address; a proxy gets around it.

Before you start: you need Run commands and change VM files (hosts.vm.admin) on the agent. Administrators have it. So does anyone with Chat and settings on every agent on that VM, which an administrator gives on each agent's Access tab (Let people use an agent). For a proxy that asks for a login, add its user name and password as two of the agent's secrets first.

  1. Open Agents, open the agent, and choose the Server tab.
  2. Under Exit proxy, type the proxy in Proxy, such as http://proxy.example.com:3128.
  3. For a login, type the secrets' names in User name secret and Password secret.
  4. Choose Save.

Check it worked: Exit proxy reads Through a proxy.

The browser starts again on the proxy once it's idle. Its logins stay; its open tabs close. Remove proxy or --off takes it away.

Services explains an agent's own browser.

Hosted apps

Add a hosted app

A hosted app gives your team and agents their own Forgejo or Mattermost, at an address under your Sunport.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and choose New service.
  2. Choose the app, such as Forgejo.
  3. Check Address, Where it runs and Size.
  4. For Forgejo, under Who can sign in, choose Everyone in the Sunport or Administrators and people you choose.
  5. Choose Add Forgejo.
  6. On the app's page, check the Price and choose Create VM.

Check it worked: the app reads Live, and Open Forgejo appears.

Mattermost keeps its own accounts. Once it's installed, choose Show the password under First administrator, and keep it: it shows only once.

Services explains what its VM costs.

Set hosted app access

Decide who may sign in to a hosted app. Administrators always may.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and open the app.
  2. Under Who can sign in, turn off Everyone in the Sunport.
  3. In Person, choose someone, then choose Add.

Check it worked: they're listed with Can sign in.

In an app that keeps its own accounts, such as Mattermost, the Sunport makes, changes and suspends their accounts to match.

Services explains hosted apps.

Get a hosted app account

An app that keeps its own accounts, such as Mattermost, gets you one from your Sunport.

Before you start: you need to be allowed to sign in to the app. An administrator chooses who is.

  1. Open Settings › Profile.
  2. Under Services, choose Make my account, if it shows.
  3. When the account is Ready, choose Show password once and copy it.
  4. Choose Open, and sign in with your username and that password.
  5. Change the password in the app.

Check it worked: you're signed in to the app.

The first password is temporary: change it in the app. Lost it? Choose New password, then Show password once.

Services explains hosted apps.

Reset a hosted app password

A hosted Mattermost sends no email, so an administrator gives a new password.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Users, open the person, and choose the Services tab.
  2. On the app's account, choose Give a new password.
  3. Choose Show password once, and copy it.

Check it worked: they sign in with it, then change it in the app.

A new password is temporary. Unchanged in the app, it stops working after 7 days.

Services explains hosted apps.

Make a hosted app token

An access token signs in to the app as you, for a script or a bot of your own.

Before you start: you need to be an administrator with a ready account in the app. An administrator can make you one.

  1. Open Settings › Profile.
  2. Under Services, find Access tokens on the app's account.
  3. Type what it is for, such as deploy bot.
  4. Choose Create token.
  5. When it's Active, choose Show token once, and copy it.

Check it worked: the token is listed as Active.

Keep a token as you keep a password. It stops working once you're no longer an administrator; Revoke ends it sooner.

Services explains hosted apps.

Update a hosted app

Your Sunport's updates bring newer app versions. Update the app to use one.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and open the app.
  2. Under Version, choose the Update to … button.

Check it worked: Version says it runs the version this release offers.

The app saves a consistent copy of its data first. If the update fails, it still runs the old version.

Services explains hosted apps.

Stop or remove a hosted app

Stop an app you'll need again, or remove it for good.

Before you start: you need to be an administrator. An administrator can make you one.

  1. Open Services and open the app.
  2. Choose Remove.
  3. Choose Stop it and keep its data or Remove it and delete its data.
  4. To remove it, type the app's address label, such as git.
  5. Choose Stop it or Remove it.

Check it worked: the app reads Stopped, or Removing until its VM is gone.

A stopped app's VM is still billed as compute and backed up. Removing deletes its data and accounts, and can't be undone.

Services explains what its VM costs.

Connections and secrets

Connect Google

Before you start: you need Connect and disconnect your accounts (connections.write), which everyone has. To share with an agent, you need Chat with agents (agents.chat) on it, which an administrator gives on the agent's Access tab (Let people use an agent) with Chat.

  1. Open Settings › Connections.
  2. Under Google connections, choose Connect another Google account if an account is listed already.
  3. In Who can use this connection, keep Only you, or choose an agent.
  4. Under Services, choose each Google service it needs.
  5. Choose Connect Google.
  6. Sign in to Google and approve the permissions.

Check it worked: Google connected. You can return to your agent. appears, and the account is listed.

An agent may send you such a link itself. Open it signed in, check what it asks for, and choose Connect Google.

Connections and secrets explains what each Google app offers.

Disconnect Google

Before you start: you need Connect and disconnect your accounts (connections.write), which everyone has. You disconnect your own connections.

  1. Open Settings › Connections.
  2. Under Google connections, find the account.
  3. Choose Disconnect.
  4. Choose Disconnect again to confirm.

Check it worked: the account is no longer listed.

Disconnecting doesn't delete Google content already in conversations.

Connections and secrets explains what a connection reaches.

Set up your Google app

Before you start: you need to be an administrator, and have a Web application OAuth client in Google Cloud. An administrator can make you one.

  1. Open Settings › Connections.
  2. Under Your organization's Google app, copy the Authorized redirect URI and Authorized JavaScript origin.
  3. Add both to your client in Google Cloud.
  4. Download the client's JSON file from Google Cloud.
  5. Under Client JSON file, choose that file.
  6. To let people choose Drive files, paste a key in Picker API key (optional).
  7. Choose Save.

Check it worked: Your organization's Google app is set. appears, with its Client ID.

A new client ID ends the connections made with the old one. A new secret for the same client keeps them.

Connections and secrets explains what each Google app offers.

Give an agent a secret

Before you start: you need Manage agents' keys (agents.credentials) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).

  1. Open Secrets and choose Add secret.
  2. Under Bot, choose the agent.
  3. Under Who it's for, keep Whole bot.
  4. In Name, type the variable its tools read, such as WEATHER_API_KEY.
  5. Paste the value in Value. For a file, choose File and pick it.
  6. Choose Save.

Check it worked: the secret is listed under the agent, marked On the bot.

If you may only chat with the agent, Add your own secret sets one just for you. Offer a secret offers one for everyone; it waits for someone who manages the agent.

Connections and secrets explains who can use a secret.

Answer a secret request

Before you start: you need Manage agents' keys (agents.credentials) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent).

  1. Open Secrets.
  2. Under Needs attention, find the request marked Requested.
  3. Choose Add.
  4. Paste the value in Value.
  5. Choose Save.

Check it worked: the request leaves Needs attention, and the secret shows On the bot.

An agent may send you a private link instead. Open it, paste the value and choose Save: it works once, for 15 minutes. Send link sends the person who asked a private link. Decline closes the request.

Connections and secrets explains how agents ask.

Ask someone for a secret

Before you start: the person you ask must be able to set the secret themselves. Without --person, an agent asks its owner, and a person asks themselves.

oo secrets request GITHUB_TOKEN --agent research --why "Nightly GitHub sync" --person PERSON_EMAIL

research is the agent's ID. oo prints a link to pass on.

The person opens Settings › Approvals, signed in, and types the value there.

Check it worked: oo approvals check APPROVAL_ID exits 0 once they gave it.

A request can be given for a day at most. oo approvals cancel APPROVAL_ID takes it back.

Connections and secrets explains why the value never reaches you.

Give an agent a 1Password key

Before you start: you need Manage agents' keys (agents.credentials) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). You also need a 1Password service account that reads the key's vault.

  1. Open Settings › Connections.
  2. Under 1Password, paste the token in Service account token.
  3. Choose Connect 1Password.
  4. Open Secrets and choose Add secret.
  5. Under Bot, choose the agent, and type the Name.
  6. Choose 1Password.
  7. Choose the Vault, Item and Field.
  8. Choose Save.

Check it worked: the secret is listed with a 1Password badge, marked On the bot.

You connect 1Password once. Service accounts can't read Private or Personal vaults, so keep agents' keys in another vault.

Connections and secrets explains how often the key is read.

Remove an agent's secret

Before you start: you need Manage agents' keys (agents.credentials) on the agent. It comes with Chat and settings, which an administrator gives on the agent's Access tab (Let people use an agent). To remove only your own secret, Chat with agents (agents.chat) on it is enough.

  1. Open Secrets.
  2. Find the secret under its agent.
  3. Choose Remove.
  4. Choose Remove again to confirm.

Check it worked: the secret is no longer listed.

Connections and secrets explains whose secrets you can remove.

Give a computer GitHub access

Before you start: you need a GitHub account with access to the repositories. Run this on the computer, or ask an agent to run it on its VM.

oo github login

oo prints a verification_uri, a user_code and an install_url.

  1. On your own device, open verification_uri and enter user_code.
  2. Approve OpenOrange's GitHub App.
  3. Open install_url and install the app on the repositories it may reach.

Check it worked: oo github status shows your GitHub account and the repositories it reaches.

The token stays on that computer and never reaches more than your own access. oo github logout removes it.

Connections and secrets explains how agents get other keys.

Machines

Add the Machines service

Before you start: you need to be an administrator. An administrator can make you one. You need an OpenClaw agent on a VM of its own.

oo has no command for this. Add it in the dashboard:

  1. Open Services and choose New service.
  2. Choose Machine (OpenClaw node).
  3. Under Agents machines may be given, choose the agents.
  4. Choose Add Machines service.

Check it worked: the service's page opens, with Add a machine.

A Sunport has one Machines service. A computer you add later reaches only the agents you chose here.

Machines explains what agents may do there.

Connect a computer

Before you start: you need the Machines service. In the dashboard, you need to be an administrator. With oo, Change services (services.write) is enough; an administrator can give you Change services.

  1. Open Services. Under Added services, open Machine (OpenClaw node).
  2. Under Add a machine, type a Name and choose its System.
  3. Under Agents (up to 4), choose the agents and a Level.
  4. For Run allowed commands, list each program's full path under Allowed commands, one full path a line.
  5. Choose Add machine.
  6. Copy the line it shows. On the computer, run it as the user the agents should work as.
  7. Compare the three match words it prints with the ones on the page.
  8. If they match, choose Approve. If not, choose Reject, then Reject machine.

Check it worked: each agent shows Paired.

On Windows, run the line in PowerShell or a command prompt not run as administrator. A Windows computer takes Full access or Find commands only. With oo, add --os windows.

Machines explains each level.

Make a VM a machine

Before you start: in the dashboard, you need to be an administrator. With oo, Manage machines (hosts.manage) on the VM is enough; an administrator can give you Manage machines.

For a service VM:

  1. Open Compute and open the VM.
  2. On Overview, under Machine, find Everyone on it works as.
  3. Choose root or The user machine.
  4. Choose Use as machine.

For an agent's VM:

  1. Open Agents, open the agent, and open Server.
  2. Under Machine, choose Use as machine.

Check it worked: Machine lists you as Admin.

Only a VM the Sunport can sign in to can be a machine: one made with Clem managing it, or an agent's VM.

Machines explains who can see what is on it.

Add people to a machine

Before you start: you need to be an admin of the machine. Administrators are, and so is whoever manages its VM; any admin can add you as one.

  1. Go to /machines on your Sunport's address and open the machine.
  2. Open Members.
  3. Under Add a person or a team, choose one.
  4. Choose Member or Admin, then Add.

To take someone off, choose Remove beside them.

Check it worked: the person or team is listed with their role.

Everyone on a machine can read and change what is on it. Add only people who may.

Machines explains the machine's one Linux account.

Work on a machine

Before you start: you need to work on the machine, as a member or an admin. Its admins add people to it.

  1. Go to /machines on your Sunport's address and open the machine.
  2. Open Terminal to run commands there.
  3. Open Files to upload and download its files.
  4. Open Environment to see its system, runtimes and tools.

Check it worked: Terminal opens a shell on the machine.

A Sunport administrator's terminal is root's. oo machines ssh asks first.

Machines explains the machine's one Linux account.

Add an agent to a machine

Before you start: you need Change agents (agents.update) on the agent, and to be an admin of the machine. An administrator gives the first with Chat and settings, on the agent's Access tab (Let people use an agent). A machine's admins can add you as one. The agent must be on the Machines service.

  1. Open Agents, open the agent, and open Server.
  2. Under Works on, in Add it to a machine, choose the machine.
  3. Choose Read, Run or Full.
  4. For Run, list each program's full path under Programs it may run, one a line.
  5. Choose Add.
  6. Under Runs commands on, choose the machine.

Check it worked: the machine shows Ready, and the agent's chat header names the machine.

Until the machine is ready, the agent's chats run no commands. oo agents machine nova --own-vm moves them back to its own VM.

Machines explains where an agent runs its commands.

Change an agent's machine access

Before you start: on a computer, you need to be an administrator. On a VM machine, you need Change agents (agents.update) on the agent, and to be an admin of the machine. An administrator gives the first with Chat and settings, on the agent's Access tab (Let people use an agent). A machine's admins can add you as one.

On a computer:

  1. Open Services. Under Added services, open Machine (OpenClaw node).
  2. Beside the agent on that computer, choose Run allowed commands or Full access.
  3. Edit its allowed commands, one full path a line, and choose Save.

On a VM machine:

  1. Open Agents, open the agent, and open Server.
  2. Under Works on, beside the machine, choose Run or Full.
  3. Edit Programs it may run, and choose Save.

Check it worked: the new level and programs show beside the agent.

Rules change only while the agent's node is connected. To move to or from find commands only, add a computer again, or remove the agent from a VM machine and add it again.

Machines explains each level.

Set up new machines

Before you start: in the dashboard, you need to be an administrator. With oo, you need Change settings (settings.write) and Run commands and change VM files (hosts.vm.admin) on every VM; an administrator can give you See settings, Change settings and Run commands and change VM files.

  1. Open Settings › Machines.
  2. Under Packages, add each Debian package's name.
  3. Under Runtimes, add Node or Python, with its version.
  4. Under Setup script, write what should run as root after them.
  5. Choose Save setup.

Check it worked: the page says you changed it.

Existing machines keep what they have. An admin of one installs the new setup with Apply setup again on its page, or oo machines setup apply MACHINE_ID.

Machines explains how the setup is installed.

Remove an agent from a machine

Before you start: on a computer, you need to be an administrator. On a VM machine, you need Change agents (agents.update) on the agent, or to be an admin of the machine. An administrator gives the first with Chat and settings, on the agent's Access tab (Let people use an agent).

On a computer:

  1. Open Services. Under Added services, open Machine (OpenClaw node).
  2. Beside the agent on that computer, choose Revoke.
  3. Choose Revoke again to confirm.

On a VM machine:

  1. Open Agents, open the agent, and open Server.
  2. Under Works on, beside the machine, choose Remove.
  3. Choose Remove again to confirm.

Check it worked: on a computer, the agent shows Revoked. On a VM machine, the machine leaves Works on.

On a computer, the agent comes back only when you remove the computer and add it again.

Machines explains what an agent may run there.

Remove a machine

Before you start: for a computer, you need to be an administrator. For a VM machine, you need to be its admin. A machine's admins can add you as one.

For a computer:

  1. Open Services. Under Added services, open Machine (OpenClaw node).
  2. Beside the computer, choose Remove.
  3. Choose Remove machine to confirm.

For a VM machine:

  1. Go to /machines on your Sunport's address and open the machine.
  2. Open Members and choose Remove machine.
  3. Choose Remove machine again to confirm.

Check it worked: a computer shows Removed. A VM machine leaves your machines.

Removing a VM machine leaves the VM, with its files. To remove the Machines service, first remove its computers and every agent on a VM machine.

Machines explains what ends with a machine.