known_hosts, and ~/.ssh/config remain the source of connection settings —
Cogno does not manage keys for you.
Before you start
- Confirm
ssh <destination>works from your computer without a password prompt. - Include the ssh username, for example
deploy@build-01. - On macOS servers, turn on System Settings → General → Sharing → Remote Login.
Set up a new server
Use the Add a server → Set up over SSH at the bottom of Settings → Machines. It takes an ssh destination and turns the server into a registered, connected machine.1
Enter the server
Under New server ssh destination, enter the destination you already use —
for example
deploy@build-01 — and pick Claude Code or Codex under
Choose the coding engine.2
Set up server
Select Set up server. Cogno streams progress through each step:
Checking the server, Installing the Cogno CLI, Reading the machine
identity, Issuing the credential, Registering the daemon, and
Connecting.
3
Done
When setup finishes the server appears under Your machines, already
connected and ready to run work.
Setting up the coding engine is separate from registering the server. If the
engine cannot be installed, the server itself still finishes setup and connects.
Install the Cogno CLI
Install the Cogno CLI on the server before you set it up. The installer detects the platform, downloads the latest release, verifies its checksum, and addscogno to your PATH.
- macOS / Linux
- Windows (PowerShell)
~/.local/bin, or /usr/local/bin when it is writable without sudo.cogno version. A Remote Server runs macOS or Linux (including WSL); native Windows is not supported as a Remote Server.
Releases and release notes are at cogno-cli-releases.
Set up on the server
Open Settings → Machines → Add a server → Set up on the server. The instructions are available in Web and Desktop. Run them in a server terminal or an approved management tool.1
Run on the server
Install the Cogno CLI as described in Install the Cogno CLI. Choose the coding engine and run the displayed command as the server OS account that will execute your work.
2
Approve registration
Select Enter registration code and enter the code printed by the server. Review the hostname, OS account and Workspace, then select Approve this machine. The hostname and OS account are self-reported. The approving account owns the machine.
3
Check readiness
Select Open your machines to check service startup and execution readiness. Configure the folder on this machine in your Project execution settings.
Approval can still be followed by service startup, agent sign-in and Project preparation. Remote interaction without SSH requires Relay enablement for the Workspace and the necessary outbound network access. The Cogno operator controls Relay enablement.
SSH through Bastion, SSM or IAP
Under Set up over SSH, open Bastion, SSM and IAP connections. ConfigureProxyJump or ProxyCommand in ~/.ssh/config, then enter its alias as the destination. SSH and forwarding must be permitted. Complete cloud authentication before setup.
Connect to a registered server
A server that is already registered — by you earlier, or from another computer with the same account — is connected from its row in Your machines.1
Find the machine
Open Settings → Machines and find the server under Your machines.
2
Enter the ssh destination
Enter the destination in the row’s field (
user@host or ssh alias). It is
reached over your own ssh — your keys, config aliases and known hosts apply.3
Connect
Select Connect. The row shows Tunnel connected · <destination>
when the server is reachable.
Several people on one server
A machine is one OS account on one host. When several people use the same server, each person sets it up with their own OS account and ssh destination, and each account appears as its own machine. When two machines report the same name, the row also shows the OS account so you can tell them apart.Control Remote Engine updates
New servers installed through Desktop orcogno server install enable automatic
Engine updates. The server fetches the latest signed release for its channel,
including while Desktop is closed. It waits for active agent work and background
tasks to finish before restarting. If the replacement fails its health check,
the previous release is restored.
In Settings → Machines, use Automatic Engine updates on your server’s row
from Web or Desktop. Turning it off retains the installed Engine version.
Connecting over ssh preserves this setting. Existing servers retain their update
policy until you opt in. Older servers first need the updated CLI and one explicit
cogno server update --latest to install the runtime that supports this setting.
The server administrator can manage the same policy locally:
cogno server install --automatic-updates=false. Production servers use stable
production releases; staging servers use their separate staging release channel.
Open a port the server is listening on
A dev server you start on a remote machine listens on that machine’slocalhost,
not yours — so the http://localhost:5173 its output prints does not open in your
browser. The Ports tab beside the Task’s terminal forwards it over the
connection Cogno already holds and opens it for you.
The tab appears only for a Task running on another machine. Work on this computer
already answers at localhost, so there is nothing to forward.
1
Open the Ports tab
In the Task’s terminal strip, select Ports. Cogno asks the machine what it
is listening on and lists it under Port, Forwarded Address, and
Running Process.
2
Open a port
Select a row. Cogno forwards it and opens it in your browser. Forwarded
Address then shows the address on this computer — normally the same number,
so
http://localhost:5173 on the server is http://localhost:5173 here too.3
Come back to it
Hover a forwarded row for Copy address, Open in browser, and Stop
forwarding. The count on the Ports tab is how many are forwarded.
Ports the list does not show
The list holds what the machine reports listening on above port 1024. Use Add port for anything else — a port below 1024, or a service the machine does not report, such as a container reached through a published port. It takes a number or an address and a port, as the field says:5173 or 10.0.0.4:5173.
A port added this way is a row like any other, and stays until you stop forwarding
it or the connection to the machine ends.
Running Process is what the machine named for the socket. On Linux it names
only processes belonging to your own account, so the column is often empty.If the same number is already in use on your computer, Cogno forwards to a
different one and Forwarded Address shows which. Forwarding works from macOS
and Linux; on Windows the app asks you to use one of those.
Collect Engine logs from a machine
Every machine under Your machines runs the Cogno Engine, the background service that checks in with Cogno and runs agent work. When a machine misbehaves, you can read its Engine log from your own computer instead of signing in to the box. This works for any machine on the list — this computer, a remote server, or a headless install — as long as it is checking in.1
Open the machine's logs
In Your machines, select the row’s Engine logs button. The panel
shows when logs were last collected, or No logs collected yet.
2
Collect logs
Select Collect logs. The panel shows Requested … · waiting for the
machine to check in (usually within a minute). The machine sends the end
of its Engine log files on its next check-in; for this computer it answers
within a few seconds.
3
Read the log
Each collection appears as a row — Collected … · Engine <version>
— with the files it holds and their sizes. Open a row to read the text, and
use Copy to paste it into a support conversation.
The machine sends the end of its log — up to 512 KiB of
engine.log and
128 KiB of pty-host.log — and a row shows how much of each file that is,
for example engine.log · last 512 KiB of 9.3 MiB. The last five
collections are kept per machine. Only the account that owns the machine can
request or read its logs.Stop using a server
In Your machines, select the row’s Remove button. Its credential is revoked, so it stops running work as soon as its next check-in is refused. Sign in again on that computer — or set the server up again — to add it back.Set up a folder through Relay
When Relay is enabled for your Workspace, open Settings → Your machines and choose Set up folder on the server. Select a Project and enter an absolute directory such as/srv/project. Cogno checks that directory and
registers it as your Project folder. An existing folder assignment is shown
before you replace it. Setup can take up to 45 seconds while an idle server
opens its outbound Relay connection.
Setup requires permission to manage your execution environments and an active
server signed in to your account. The setup grant lasts two minutes and permits
only the selected Project and directory. Cogno closes the connection after setup.
In Desktop, Use Relay for Tasks selects Relay for that server in the current
window and closes its SSH tunnel. Use SSH for Tasks restores the SSH route;
use Connect to open the tunnel again. A selected route describes your choice;
a Task checks live access when it opens.
The server must reach Cogno Core and its configured Relay over HTTPS and
WebSocket on port 443. Follow your organization’s network policy, proxy and
trusted certificate configuration. See Enterprise Remote Server operations.
Connect to a dedicated Workspace server
When Cogno configures a dedicated Workspace server with an HTTPS endpoint, Task operations, conversation updates, elevated terminals, and Private Preview leases connect directly to that server. Cogno checks the same Task and member permissions before issuing short-lived access. If the direct endpoint refuses a connection, Cogno reports the failure without switching to Relay. Other registered servers keep their configured connection method. Private Previews open on a separate, short-lived preview origin. The access code is submitted in a POST body and is not included in the preview URL.Troubleshooting
Setup failures are shown in the app with a next step. The most common:
Two more general symptoms: