Skip to main content
An environment is where agents run commands and work on files. CloudThinker Cloud is the managed option. A self-hosted environment connects machines you control, such as a laptop, server, or CI runner. Choose one through Run in before starting a chat. Each connected machine runs a background worker process.
Some screenshots show Workers, the previous name for Environments.Beta. Environments run on the CloudThinker CLI, which is also in beta. Command names and flags may change before general availability. The CLI retains outpost in its command syntax, so you’ll see --outpost in commands.

​
How it works

The Environment on your machine connects out to CloudThinker Cloud, runs file and shell work locally, and sends results back, while connection commands run in the cloudThe Environment on your machine connects out to CloudThinker Cloud, runs file and shell work locally, and sends results back, while connection commands run in the cloud

File and shell work runs on your machine. The model and connection credentials stay in CloudThinker Cloud.

​
Why use an environment

  • Work where your code lives. The agent edits files and runs your own tools in a private repository or on an internal host, with no inbound port opened. The Environment connects outward over HTTPS.
  • Connection credentials stay in the cloud. Commands that use a workspace connection, such as AWS or Kubernetes, still run in CloudThinker Cloud. That credential never reaches your machine. The agent’s shell can still use any credentials already on the machine, such as ~/.aws or ~/.kube/config, so run the environment under an account without them if that matters.
  • Your folder’s rules apply. The agent follows the instruction files and Skills you keep in the folder.
  • Personal or shared. Only you can use a personal environment. A shared environment is available to everyone in the workspace, including Automations.

​
Prerequisites

  • The CloudThinker CLI installed on the machine, on Linux or macOS. There is no native Windows build. See CLI.
  • Outbound HTTPS (port 443) from the machine to app.cloudthinker.io, directly or through HTTPS_PROXY. If your proxy re-signs HTTPS, set SSL_CERT_FILE to your company CA bundle.
  • A folder you want the agent to work in, such as a repository checkout. For Worktree, it must be a git repository and the machine needs git 2.38 or newer.
  • To create a shared environment: the workspace Admin role. See Roles.
  • Allow self-hosted environments turned on in More → Workspace settings → General (see workspace settings). It’s on unless a workspace Admin turned it off.
The dashboard setup below doesn’t need cloudthinker login on the machine. The setup command enrolls the environment by itself. The terminal-only setup does need a login.

​
Set up an environment

1

Open the environment setup dialog

In a new chat, open the + menu beside the prompt box, select Run in, then select New environment. Admins can also go to Admin Settings → Sandboxes (an environment is another place a chat can run, next to CloudThinker Cloud) and select Create environment in the Environments section.
The Environments section of the Sandboxes page with the Create environment button

Admin Settings, Sandboxes: Create environment adds a folder on your machine where agents can work

2

Name the environment

Enter an Environment name, for example payments-api. Turn on Share with workspace if teammates and Automations should use it. Select Create environment. Only Admins see Share with workspace; everyone else creates a personal environment.Success state: the dialog shows a setup command. It works once and expires in 10 minutes (the dialog calls it a link).
3

Run the command in your project folder

Copy the command, open a terminal in the folder you want to serve, and run it. It looks like this:
<reference> is a one-time enrollment code from the dialog. --url falls back to the address of your last cloudthinker login, else https://app.cloudthinker.io, so you can usually drop it.The Environment saves its credential in a private file (mode 0600) on this machine. It then checks that it can read files, run a shell command, cancel a command, and upload results. It keeps running in the foreground until you press Ctrl-C.Success state: the terminal prints Waiting for work. and the dialog shows <name> is verified. If the command expired, select New command.
4

Start a chat on the environment

Select Start a chat. A new chat opens with the environment selected.

​
Set up from the terminal only

Sign in with cloudthinker login first and check the workspace with cloudthinker whoami. Then:
Success state: the terminal prints Waiting for work., and the environment shows Online in the Run in menu.

​
Add more machines to an environment

One Environment can have several machines, for example a build server and its standby. Open the environment’s settings, select Connect a machine, and run the command it gives on the new machine. Each enrollment is a separate machine with its own credential, and each handles up to 4 runs at once by default. A conversation stays on the first machine and folder that picks it up. It never moves to another machine, even when that machine goes offline.

​
Use the CloudThinker Desktop app

In the CloudThinker Desktop app, the Run in menu also shows Open a folder…, which serves a folder from this computer as an environment with no terminal. For a selected Desktop folder, Remove this folder takes it off the list. Selecting a Desktop folder whose Environment is stopped starts it. These actions don’t appear in the browser.

​
Choose where a chat runs

1

Pick the environment

In a new chat, open the + menu and select Run in. Choose CloudThinker Cloud or an environment by name. Picking a target closes the menu.The Run in row appears only when there’s something to choose, such as an environment. Offline Environments move to an Unavailable submenu, where a row opens that Environment’s settings. Organization Admins also see Manage environments, which opens Admin Settings → Sandboxes.
The + menu with a Run in row showing CloudThinker Cloud
Success state: a chip with the environment’s name appears in the toolbar. Its tooltip reads like “Files and shell commands run on payments-api. Connections run in CloudThinker Cloud, and credentials stay there. You cannot change this after the first message.” While an environment is available, the chip also shows for CloudThinker Cloud, so switching is one click.
The toolbar chip for an environment, with a tooltip that explains what runs where
2

Send the first message

Ask for something that uses the folder:
Success state: the chip locks. The conversation stays on that Environment for its whole life. To run somewhere else, start a new conversation.
The composer remembers your last choice for the workspace, so the next new chat starts on the same Environment.

​
Work in a separate worktree

After you pick an environment, open Run in again. It now shows Configure local environment. If the folder is a git repository, turn on Worktree and pick a base Branch before the first message. The Environment then creates a cloudthinker/<id> branch in its own worktree, stored in the environment’s state folder outside the folder you serve, so your main checkout stays unchanged. It uses the local branch if one exists, and otherwise fetches origin/<base> once.
  • Cleanup: the environment removes a worktree after 14 days without use, but only when it has no uncommitted changes. It deletes the cloudthinker/<id> branch only when that branch is merged or pushed. List them with cloudthinker worker worktrees ls, or clean up now with cloudthinker worker worktrees prune. Dirty worktrees stay and show as dirty.
  • When the switch is greyed out: a line under it says why, for example “This folder is not a git repository.” or “Update the environment to use worktrees.” Run cloudthinker update, and cloudthinker worker doctor to check the git version.

​
What an environment can reach

In host mode, shell commands on an environment are not sandboxed. They can read ~/.ssh, write outside the folder, and reach your network. On a sensitive machine:
  • Turn on container mode, so commands run in a container that mounts only the folder and reaches only the hosts you allow.
  • Run the environment under a dedicated, non-admin account. Never run worker start as root.
  • Keep SSH keys and cloud credentials out of that account’s home folder.
  • Don’t rely on Approvals to protect the machine. It checks commands that reach your systems, such as cloud CLIs, ssh, Git pushes, and requests that send a stored credential. A command that only acts on the machine, such as rm or a file write, may run without asking.
Shell commands get a reduced environment: PATH, HOME, LANG, TERM, USER, and TMPDIR. To pass more, add flags to worker start, for example cloudthinker worker start --outpost payments-api --workdir "$PWD" --env AWS_PROFILE. The value comes from the worker process’s environment, and you repeat --env for each variable. --inherit-env passes everything. The Environment’s own credential is always left out. --background doesn’t accept these flags. Every shell command, background task start or stop, and file write is recorded in Admin Settings → Audit Logs under the Command filter, for personal and shared environments alike. Organization Owners and Admins can open it. The record keeps a redacted preview of the command (at most 1 KiB), never its output. Reads are not recorded.

​
What leaves the machine

The Environment runs the tools, but the model runs in CloudThinker Cloud. These go there and become part of the conversation:
  • File contents the agent reads, up to 1.4 MB per file.
  • Command output.
  • Files the agent uploads as results, up to 64 files and 16 MiB per operation.
Serve only folders whose contents you’re fine sending to the model. See Data protection for how conversations are stored.

​
The Use Connections switch

The Use Connections switch appears in the Run in menu after you pick an environment. It’s on by default, and anyone starting the chat can change it. It decides whether the run can use connection commands: commands that go through a workspace connection, such as aws or kubectl. Its ? help reads “Connections like AWS or Kubernetes run in CloudThinker Cloud, and credentials stay there. Turn it off to keep everything on this environment.” It never moves file or shell work off the environment.
The Run in menu with the Use Connections switch
The first message fixes the switch along with the environment.

​
What stays in CloudThinker Cloud

Cyber runs and browser sessions need CloudThinker Cloud. In an environment conversation they return an error, and nothing silently moves to the cloud. Start a new conversation in CloudThinker Cloud for those.

​
Folder rules and Skills

When a conversation starts, the agent reads the instruction files at the root of the folder: AGENTS.override.md, AGENTS.md, CLAUDE.md, and GEMINI.md. It reads every one that exists, not just the first, in that order. When it works in a subfolder, it also picks up the same files from that subfolder and the folders above it. The root files are read once per conversation, so an edit applies from the next conversation. Skills come only from .agents/skills/ (up to 64), not from other tools’ folders such as .claude/skills/. Each Skill is a folder with a SKILL.md whose frontmatter has a description, and the agent loads it when a task matches. Set disable-model-invocation: true to hide one. See Skill format.

​
Keep an environment running

worker start stops when you close the terminal. To keep it up, add --background to the same command. That does service install and service start in one step, for the same Environment, folder, concurrency, and label: a systemd user unit on Linux, a LaunchAgent on macOS. On Linux it also turns on lingering so the environment survives logout, or prints the loginctl enable-linger <user> command when it can’t. It then prints the status, logs, and stop commands. On macOS the LaunchAgent runs only while you’re logged in. To upgrade the CLI on a connected machine: run cloudthinker worker service stop (it lets current work finish), then cloudthinker update, then cloudthinker worker service start. In the foreground, press Ctrl-C, update, and run the same worker start command again. Useful worker start flags: --concurrency <1-32> (default 4) for the most runs the environment handles at once, --label <name> for the folder’s display name, --health-addr 127.0.0.1:9464 for /healthz and Prometheus /metrics endpoints, --log-format json for one JSON log object per line, and --verbose (-v) to print each operation.

​
Manage an environment

Select an environment’s row in Admin Settings → Sandboxes, or the settings icon beside the selected Environment in the Run in menu, to open its settings. The dialog lists each machine with its state (Online, Offline, Draining, Registered, or Needs enrollment), platform, CLI version, last IP address, last seen time, load, and credential age and expiry. Its Security section sets container mode, allowed hosts, and allowed IP addresses: see Environment security. A version badge shows when a machine’s CLI falls behind: Update available or Outdated. The fix for both is to run cloudthinker update on the machine. cloudthinker worker status shows the same badge.

​
When Self-hosted environments are turned off

A running worker start waits while Self-hosted environments are off, checks every 60 seconds, and resumes on its own, so you don’t need to restart it.

​
Run an Automation on an environment

In the Automation form, set Run in to a shared environment. Automations can’t use personal environments, and only workspace Admins can change where an Automation runs. A change to the Use Connections switch applies from the next run. If the environment is offline when a run is due, the run never moves to CloudThinker Cloud. Keep shared environments that serve Automations running as a service.

​
Troubleshooting

One of the startup checks failed. Stop the worker, run cloudthinker worker doctor in the folder, apply the fix it prints, then select New command and run it again. If it says Your CLI is out of date, run cloudthinker update first.
You see Offline on the environment’s row in Admin Settings → Sandboxes and in the Run in menu. The process stopped or lost the network. Check that worker start or the service is still running with cloudthinker worker status --outpost <name>. The Environment reconnects on its own after sleep or a network change.
Only PATH, HOME, LANG, TERM, USER, and TMPDIR are passed by default. Restart the environment with --env NAME for each variable, or --inherit-env.
The folder was replaced, for example deleted and recloned. Run worker start once with the same --outpost and --workdir plus --reset-folder. Conversations that used the old folder stay unavailable.
A credential stays valid for 30 days after its last use and rotates on its own while the environment runs. If it expires, enroll again with a new command from Admin Settings → Sandboxes, or Run in → New environment.
In Admin Settings → Sandboxes, open the environment’s row. Select the revoke icon on one machine (Revoke this machine), or Revoke all machines (shown with 2 or more machines). Both ask you to confirm. The credential stops working right away: running work stops, and each machine must enroll again. To retire the environment for good, select Remove environment, or run cloudthinker worker outpost archive <name> once its open conversations finish.
The conversation runs on your personal environment, so only you can send messages in it. Teammates can read it but not reply. Create a shared environment instead.

​
Next steps

CLI

Install the CLI, sign in, and run CloudThinker from your terminal.

Approvals

Choose which agent actions need a person’s approval first.

Automations

Schedule work to run on a shared environment.

Deployment options

Compare CloudThinker Cloud, Environments, and private deployments.