Skip to main content
A machine is a computer that can run agent work — your own computer through the desktop app, or a server your workspace enrolls. Settings → Machines is where you see whether a machine is ready, control the Engine that runs work on it, and check which machines your workspace can reach. This page is the home for all of that; environments (the folder a project runs in) are set from each project, and server enrollment has its own page.
Most of Settings → Machines manages the computer you are sitting at, so it needs the Cogno desktop app. Opened in a browser, only the Your machines roster renders. Open the page from the desktop app to see This machine, Startup & background, and server enrollment.

​
What’s on the Machines page

The public /demo uses sample machines. Exploring it does not re-register your computer, remove its Engine credential, or reconnect your saved servers. Returning to your workspace resumes the usual machine registration checks.

​
Control execution access

Each entry under Your machines has two access settings: Choose Ask for approval, Auto in workspace, or Full access for each setting. The user-initiated setting is a machine maximum: each Session also has a Session access choice in the composer, and the Engine uses whichever choice is more restrictive. The autonomous setting directly controls unattended queue turns.
Full access can run commands and change files outside the Session workspace without native approval. It may also reach files and credentials available to the Engine’s OS account. Cogno asks you to confirm before enabling it, especially for autonomous runs that can start while no one is present.
An older Engine keeps the safe Auto in workspace boundary and does not offer Full access; update the Engine before using Session access controls.

​
Keep the Engine running

The Engine is the always-on local runtime that runs agent work on a machine. Under This machine, its state reads Running, Stopped, or Not running, with Start, Stop, and Restart controls.
On macOS the window’s close button only puts the window away — the Engine keeps running in the menu bar. Quit Cogno in the menu bar is what actually ends it. Turn on Startup & background → Open Cogno at login so the Engine is there from the moment you sign in.
A machine that stops reporting for two minutes counts as offline, and runs routed to it wait in the queue until it is back.

​
Read the Readiness line

This machine shows a Readiness line. When it reads Ready, the machine can pick up work. When it does not, the details list exactly what blocks it — for example:
  • neither Claude Code nor Codex available, or a provider signed out — with claude auth login or codex login shown as the fix
  • git or Node.js missing
  • the GitHub CLI signed out
  • the disk almost full
Fix what the line names, then the machine returns to Ready on the next check-in. A new run uses a healthy supported CLI and does not prefer one provider when both work. Reset & re-register applies to the Cogno machine credential; for a coding-agent sign-out, run the provider-specific login command shown in the readiness details.

​
Environments live in the project

An environment is a folder on a machine plus the settings work runs under there (AI tool, model). Settings → Machines shows which folders this machine has registered, but you do not add a project’s folder here — each member connects their own folder from the project’s settings. See Set up a project for connecting a folder or cloning repositories.

​
Run a machine on a server

To run work on a machine you are not sitting at — a Linux box, a cloud VM — enroll it as a server. Set up a new server walks the ssh enrollment, and cogno doctor on the server reports each readiness check with the command that fixes it. See Run Cogno on your own server for the full flow, and Enterprise remote execution for fleet setups.

​
Reference

​
Routing

How a run chooses the machine and directory it lands on: A task that has already run keeps its environment, so later runs land on the same machine and directory. For the states a run itself moves through (pending → claimed → running → completed), see Run agents on a task.

​
Engine states

​
Machine status

​
Troubleshooting

For anything not listed here, see Troubleshooting.