Skip to main content
A remote server runs agent work the same way your own computer does. You set it up once from Settings → Machines in the Cogno desktop app, and after that it appears under Your machines like any other computer signed in to your account. Cogno reaches the server with ssh from the computer running the desktop app. Your ssh keys, 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.
Linux and macOS servers are supported.

​
Set up a new server

Use the Set up a new server card 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.
If ssh has not seen the server before, Cogno shows Trust this server? with the host key fingerprint. Connect only if the fingerprint matches the one the server’s owner gave you. If setup stops, the card explains what happened as a next step — for example The server does not have your ssh key or This step needs administrator rights — and stays on Setup stopped while <step>. Fix the cause and select Set up server again; setup resumes safely. Progress is kept while you navigate elsewhere in the app.
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.

​
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.
If the connection drops, the row shows Tunnel dropped — reconnecting… and Cogno retries until the connection returns or you select Disconnect. When you relaunch the desktop app, Cogno automatically reconnects the servers that were connected last time. A server you explicitly disconnected is not redialed until you connect it again.

​
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.

​
Open a port the server is listening on

A dev server you start on a remote machine listens on that machine’s localhost, 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.
Select Read the ports again to ask the machine a second time — a server you started after opening the tab appears then. Nothing is forwarded automatically.

​
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.
A machine that is not checking in cannot answer. The panel says this machine is not checking in; it answers when it comes back, and the request stays until the machine’s Engine starts again.
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.

​
Troubleshooting

Setup failures are shown in the app with a next step. The most common: Two more general symptoms: