> ## Documentation Index > Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt > Use this file to discover all available pages before exploring further. # Connect to a remote server > Set up a development server over ssh, or connect to one that is already registered, from Settings → Machines in the Cogno desktop app. 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 ` 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. 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**. 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**. 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 \**. 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**. Open **Settings → Machines** and find the server under **Your machines**. 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. Select **Connect**. The row shows **Tunnel connected · \** 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. 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**. 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. 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. In **Your machines**, select the row's **Engine logs** button. The panel shows when logs were last collected, or **No logs collected yet**. 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. Each collection appears as a row — **Collected … · Engine \** — 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: | Message in the app | What to do | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **The server does not have your ssh key** | Add it with `ssh-copy-id`, or paste your public key into the account's `~/.ssh/authorized_keys` on the server. | | **That hostname does not resolve** | Check the spelling. A Mac on your own network usually needs the `.local` suffix. | | **The destination needs a username** | Write it as `user@host`, for example `ubuntu@192.168.1.9`. | | **The server is not accepting ssh yet** | On a Mac, turn on **System Settings → General → Sharing → Remote Login**. On Linux, start the ssh server. | | **The server never answered** | The machine may be asleep, on another network, or behind a firewall dropping port 22. | | **This host is not the machine Cogno remembers** | The host key changed — usually a rebuilt machine or a reused address. If you expected that, remove the old entry with `ssh-keygen -R` and set it up again. If not, do not connect. | | **This Mac is not signed in at its screen** | Turn on automatic login and sign in once — or ssh in and run `cogno server install` in a terminal, which registers a boot service that needs no login. | | **This step needs administrator rights** | Run `cogno server install` in a terminal on the machine, or give the account passwordless sudo. | | **Setup was run as root** | Run setup as the account the server should work as. It elevates by itself for the one step that needs it. | | **macOS is blocking Cogno from your local network** | Turn Cogno on under **System Settings → Privacy & Security → Local Network**, then set the server up again. | | **This server has an older Cogno CLI** | Update the CLI on the server, then set it up again. | Two more general symptoms: | Symptom | Fix | | ---------------------------------------------- | --------------------------------------------------------------------------------------- | | The setup card or connect controls are missing | Open Cogno in the desktop app. The browser cannot use your local ssh. | | Project work cannot start on the server | Set the project's folder under **Project settings**. See [Set up a Project](/docs/projects). | ## Related docs * [Enterprise Remote Server operations](/docs/enterprise-remote-execution) * [Set up a Project](/docs/projects) * [Run an agent on a task](/docs/agents)