# Concors docs Source: https://docs.concors.dev # Welcome to Concors Concors is a client for coding agents. You run Codex, Claude Code, OpenCode, Pi and other agents on a machine that belongs to you, then drive them from one desktop or mobile app. The machine keeps the files, the processes and the accounts. Concors gives you one place to see all of it. Three parts fit together: | Part | What it gives you | | ------------------------------------ | --------------------------------------------------------------------------------------- | | [Machines](/machines/overview) | This computer, a Concors Cloud machine, or a self-managed machine. These hold the work. | | [Agents](/agents/overview) | Real provider CLIs, working side by side with terminals on the same files. | | [The workspace](/workspace/overview) | Sidebar, tabs, panes, files, previews and pull requests around the sessions. | ## Work that does not stop An agent session runs on the machine, not in the window you are looking at. Close the pane, close the client, close your laptop: the turn keeps going, queued follow-ups keep waiting, terminals keep their processes, and schedules still fire. When you come back, the conversation is where you left it. That works best on a machine that stays on. [This computer](/machines/local) is the fastest way to start, and [a Concors Cloud machine](/machines/cloud) is the one that stays up while you are away. On a cloud machine you can also check in from [your phone](/start/mobile), reply to an agent that needs input, or dictate the next instruction. ## What you can do - Run several agents at once, each in its own pane, on the same workspace. One implements, one investigates, one reviews. - Keep a terminal open for tests and another for a dev server, next to the agents. - Edit files in the built-in editor while an agent works, with conflicts shown instead of hidden. - See the dev servers your workspace starts under [Previews](/capabilities/previews), with a reachable address on the machine. - Follow [pull requests](/capabilities/pull-requests) for your workspaces and merge or close them without leaving the app. - Run recurring work with [schedules](/agents/schedules), which keep running while every client is closed. Your agent subscriptions and accounts stay yours. Concors does not resell model inference, and your prompts and code stay on the machine you chose. ## About this preview Concors is early. Expect rough edges and breaking changes. Some parts are complete and some are in progress; each page says what it needs. In particular, the desktop app ships for Linux x86_64 today, the mobile app is in internal testing rather than the stores, and push delivery to phones is not finished. The [troubleshooting page](/help/troubleshooting) describes the situations you are most likely to hit. ## Reading these docs Every page has **Copy page** and **Markdown** controls, so you can paste the whole page into a conversation or point an agent at it. The [docs index for agents](/help/agents) explains that workflow. If you are ready to try the product, start with [your first agent session](/start/quickstart). ## Related - [Your first agent session](/start/quickstart) - [How machines work](/machines/overview) - [What is an agent?](/agents/overview) - [The workspace](/workspace/overview) --- # Your first agent session This walks you from a fresh install to an agent doing real work in a workspace you own. It takes a few minutes, plus whatever the agent needs for the task itself. ## 1. Sign in Open Concors and sign in with your email and password, or choose **Continue with GitHub** in the desktop and mobile apps. Creating an account is free while Concors is in preview; cloud machines are billed as separate subscriptions. If you do not have one yet, switch to **Create an account** on the sign-in screen. You land in an empty workspace with no machine selected. ## 2. Choose a machine Pick a machine from the switcher at the top of the sidebar. - **This computer** is ready immediately. The desktop app starts its own Concors runtime on your computer, so your files and terminals are local to you. - **A Concors Cloud machine** keeps working when your computer is off. Create one from Settings → Machines → **New machine**, choose a region and size, pick the development tools you want, add a card, and deploy. It appears in the machine switcher when provisioning finishes. - **Your own machine** can run the runtime too; [Connect your own machine](/machines/self-managed) covers that path. The machine you select owns everything you do next. Switching machines switches workspaces, agents and terminals along with it. ## 3. Open a workspace Use the plus button next to **Workspaces**: 1. **New workspace** starts in the machine user's home folder and follows the terminal's current folder. Open a terminal, `cd` into your code, and the workspace follows you. 2. **Open folder…** browses the machine and uses the folder name as the workspace name. 3. **Clone repository…** clones from GitHub with your connected account, or from a URL or local path, into `~/repos/` by default. When the workspace appears, you have a tab strip, a pane area, and the **Project files** button. ## 4. Give an agent a task Create an **Agent** tab. Concors starts a conversation with the default provider, Codex, and shows the composer once it is ready. Type a request and press Enter. - If the provider is not installed yet, open Settings → Providers and choose **Install**. - If the provider needs an account, a prompt appears above the composer. Choose **Connect account** and follow the steps for that provider. Your credentials stay on the machine and are used by the provider CLI. - Working in a terminal instead? Create a terminal tab with the Codex, Claude Code or OpenCode profile and run the CLI there. Agent sessions in terminals still show up in the Agents list. The agent reads files, runs commands and asks for approval when it needs it. Approve, dismiss or cancel requests from the card above the composer. You can keep typing while it works; messages sent during a turn join the queue and run next. ## 5. Work alongside it Open another pane with the split control in a pane header, or add a tab with **New tab**. Put a terminal beside the agent to run tests, and keep a dev server in the third. When the dev server starts, it appears under **Previews** with an address you can open. Close your laptop and reopen it later: on a cloud machine, the sessions were never interrupted. On your own computer, they resume as long as the machine stayed awake. ## Where to go next - Edit code while the agent works; see [Files and the editor](/capabilities/files). - Watch what the machine is doing in [Resources and processes](/machines/resources). - Bring an existing CLI conversation into Concors with [Resume saved sessions](/agents/resume). - Set up recurring work with [Schedules](/agents/schedules). ## Related - [Install the desktop app](/start/install) - [What is an agent?](/agents/overview) - [The workspace](/workspace/overview) - [Troubleshooting](/help/troubleshooting) --- # Install the desktop app Concors desktop is a native app that bundles its own runtime. You do not install Node, configure a service, or start the runtime by hand: launching the app starts the local Concors runtime, and the workspace appears once you sign in. ## What it runs on | Platform | Status | | ------------ | -------------------------------------------------------------- | | Linux x86_64 | Available. A portable tarball and an Arch/Omarchy package. | | macOS | Packaging is in progress; a public build is not published yet. | | Windows | Not published yet. | Concors is in preview, so desktop builds are shared with preview participants rather than offered on a public download page. The formats below are what each build provides. ## Install on Linux Two builds come out of the release pipeline: - `Concors--x64.tar.gz` for any Linux distribution. Extract it and run `bin/concors-desktop`. Keep the `bin/` and `lib/` folders together. - `concors-bin--1-x86_64.pkg.tar.zst` for Arch and Omarchy. Install it with `pacman -U`. Both are built on Ubuntu 24.04 so the app runs on current and recent distributions. Packages are checked before publishing, so a build that cannot be installed never reaches a release. The app is signed when a signing key is configured, and downloads are verified against a published digest before anything is installed. An unsigned build is still installable after that digest check. ## Sign in and start The first screen asks for your [Concors account](/start/access). After you sign in, the app opens the local runtime and shows the workspace. The machine switcher starts on **This computer**; you can add a [Concors Cloud machine](/machines/cloud) at any time. > **Note.** Keep your computer awake while local agents work. If the computer sleeps or the runtime stops, local sessions stop with it. A cloud machine does not have that problem. ## Updates The app checks for a newer build on launch, every 30 minutes, and whenever its window comes back to the front. When one is available, an update badge appears above the account menu. What the badge can do depends on how Concors was installed: | Install | Update behavior | | ------------------------------------ | --------------------------------------------------------------------------- | | Arch package under `/opt/Concors` | Downloads and installs the package with `pacman -U`. | | Tarball in a folder you can write to | Replaces the app folder, keeping the old one until the new one is in place. | | A folder you cannot write to | Tells you a new version exists and leaves the install to you. | > **Note.** Installing an update ends local terminal and agent sessions, because the new build brings its own runtime. Workspaces, saved conversations and settings survive. The dialog says so before the download starts. ## Related - [Concors on your phone](/start/mobile) - [This computer](/machines/local) - [Machine subscriptions](/billing/subscriptions) - [Troubleshooting](/help/troubleshooting) --- # Concors on your phone The Concors mobile app connects to the same machine as your desktop client. It is built for checking in: see which agents are working, answer a request, read a diff, then put the phone away while the work continues on the machine. ## Availability Concors for iOS and Android is in internal testing, not in the App Store or Play Store yet. - Preview builds are shared through TestFlight and internal Android builds. - A browser demo with sample data is included for trying the interface with no account and no machine. Choose **Explore demo** on the welcome screen; everything in it is simulated. - Building from source is possible with Expo, but it is a development path. > **Preview.** Signing up, buying a machine, and managing billing are desktop features. The mobile app signs in to an existing account and uses machines you already created. ## Sign in Use the same Concors account as the desktop app. Sessions last 30 days and renew while you use the app. If your session expires you are asked to sign in again; the machines and sessions keep running while you do. A development build can also connect directly to a desktop machine over a private network, without a cloud account. That path is for preview testing, uses the **Connect to desktop** option, and is disabled in production builds. ## What you can do - **Check on agents.** The sidebar lists every agent session with its status: Working, Needs input, Done, Failed. Unread markers tell you what changed since you last looked. - **Reply and approve.** The conversation view has the same timeline, approvals and questions as the desktop app. Approve a tool call, answer a question, or send a follow-up. - **Dictate an instruction.** The composer uses your phone keyboard's microphone. The app never starts recording on its own. - **Read and edit files.** The Files view opens the workspace tree, renders Markdown, and edits text with the same limits as the desktop editor. - **Use a terminal.** A session view with the extra keys a phone keyboard lacks: Esc, Tab, Ctrl+C and arrows, plus reload and stop controls. - **Follow pull requests.** Open the Pull requests page, read a change, and merge or close it when the machine's GitHub account allows it. - **Run a schedule now.** Schedules created on the machine appear on the phone with their recent runs. - **Watch machine resources.** CPU and memory values sit under the machine picker; the Resources drawer lists processes. The app shows one pane at a time. Desktop split layouts are flattened into the **Tabs** picker, where you can switch between every chat and terminal; changing what you see on the phone never changes the desktop layout. ## Navigation - Swipe right on a conversation or terminal to open the sidebar. - Swipe left to open the current workspace's files. - The **Tabs** picker at the top switches panes and creates new ones. - The account drawer holds **Settings** and **Sign out**. ## Notifications In-app notifications work on the phone: agents that finish or need input surface in the app and in the Agents list. Push delivery to a locked phone is not finished yet, so Concors does not promise alerts when the app is closed. ## Related - [Install the desktop app](/start/install) - [Sign in and accounts](/start/access) - [Concors Cloud machines](/machines/cloud) - [Notifications and sounds](/workspace/notifications) --- # Sign in and accounts A Concors account is what connects your clients, your machines and your organization. Signing out of a client never stops the work on a machine. ## Create an account On the sign-in screen, switch to **Create an account**. Enter a name, an email address and a password of at least eight characters. Creating an account is free while Concors is in preview; cloud machines are billed as separate subscriptions. You can also choose **Continue with GitHub** in the desktop and mobile apps. GitHub handles the sign-in on its own page, so Concors never sees your GitHub password, and the app does not store a GitHub token. If the button is missing, that build or server does not have GitHub sign-in configured; email and password always works. Creating an account is done in the desktop app; the mobile app signs in to an existing account. Password reset and email verification screens are not part of the preview yet, so if you are locked out, use [Get help](/help/support). ## Sign in Sign in with the same details on every client: the desktop app, a second computer, and the mobile app. After the session is confirmed, the workspace opens on the machine you last used, or on **This computer** the first time. While a saved session is being checked you see the Concors mark and a short loading state. If the check fails, the sign-in screen offers **Retry**; a saved session that the server rejects is cleared, and you sign in again. ## Sessions Concors sessions last 30 days and renew while you use the app, so you are rarely asked to sign in again. Your session expiry is shown in Settings → Account, with a **Sign out** button. Signing out is local first: the token is removed immediately and the server revocation is best effort, so you can sign out with no connection. If files have unsaved changes, Concors asks before signing out. > **Note.** Signing out does not stop agents, terminals or schedules on a machine. Those belong to the machine, not to the signed-in client. Use the machine's own controls to stop work. ## Organizations Every account starts with a personal organization. If you belong to more than one, the active organization is shown in Settings → Account; switching it changes which machines, SSH keys and subscriptions you see. The personal organization is marked with **· personal** in the picker. Machines, billing and SSH keys belong to the active organization. Make sure the right organization is selected before you create a machine or invite work into it. ## Profile and devices Settings → Account shows your name, email and whether the email is verified, plus the GitHub connection if you added one. Each device signs in separately, and each keeps its own appearance, shortcuts and notification preferences. Sessions are listed only as their expiry date; device management and remote sign-out are not part of the preview. Agent accounts are separate from your Concors account. Signing in to Codex, Claude Code or another provider happens on the machine, and the provider bills you directly. See [Agent accounts](/agents/accounts). ## Related - [Install the desktop app](/start/install) - [Agent accounts](/agents/accounts) - [Machine subscriptions](/billing/subscriptions) - [Settings reference](/workspace/settings) --- # How machines work A machine runs the Concors runtime. It owns your files, terminals, agents and sessions. Every client (desktop, browser, phone) is a window into one machine at a time, so the work continues whether or not a window is open. There are three kinds of machines: | Kind | What it is | Connection | | ----------------- | ----------------------------------------------- | ------------------------------------------------------------- | | **This computer** | The runtime bundled with the desktop app | Loopback, no sign-in and no token | | **Concors Cloud** | A managed VPS provisioned for your organization | An authenticated hostname with machine tokens, billed monthly | | **Self-managed** | A machine you run the Concors runtime on | An address you configure; a preview path | ## What the machine owns Everything that must outlive a window lives on the machine: - Projects (workspaces) and their files - Saved conversations and their history - Messages you queue while an agent is busy - Terminal processes and their output - Schedules that run prompts on a cadence Because of this, the machine must stay on for work to continue. Closing the client does not stop sessions, and closing a pane does not end the process behind it. Reopening the client shows the same work, in the same place. If the machine sleeps or stops, its running sessions stop; saved conversations remain. ## What stays on your device A few settings belong to the device rather than the machine: - Appearance and theme - Keyboard shortcuts - Notification preferences and sounds - Unsent drafts in the composer These follow the device, not the machine. The same client can be signed in to more than one machine, and each machine has its own workspaces, conversations and sessions. ## Switching machines Use the machine switcher at the top of the sidebar to move between machines. Each machine is a separate workspace: the workspaces, conversations, terminals and schedules of one machine never appear under another. The switcher also creates Concors Cloud machines and opens their settings. The active machine is always visible at the top of the sidebar, so you can tell where a command or an agent will run before you start it. > **Preview.** Connecting the client to a machine you run yourself is an early path. Managed machines are the supported route for work that must continue remotely. See [Connect your own machine](/machines/self-managed). ## Related - [This computer](/machines/local) - [Concors Cloud machines](/machines/cloud) - [Connect your own machine](/machines/self-managed) - [The workspace](/workspace/overview) --- # This computer Running work on **This computer** uses the runtime bundled inside the Concors desktop app. The app starts that runtime for you on the local loopback address, so there is nothing else to install, configure, or authenticate against beyond your Concors account. ## Select This computer 1. Open the machine switcher at the top of the sidebar. 2. Choose **This computer**. 3. Open a workspace folder, or clone one, and start a terminal or an agent. The desktop app starts the runtime when you launch the app and signs in, and selects the local machine for you when it is the only one available. A browser development build can also connect to a runtime listening on `ws://127.0.0.1:7420/ws`. The bundled runtime includes everything it needs, including a real terminal engine, so you do not install Node or start the runtime by hand. ## Where local data lives Local data lives under `~/.concors` by default. Set `CONCORS_DATA_DIR` before launching the app to use another location, for example to keep a test installation separate. - Workspaces, saved conversations and session history go into a per-account profile on the machine. - Startup and runtime logs are written to the application log directory as `local-daemon.log`, normally `~/.local/share/dev.concors.desktop/logs/local-daemon.log` on Linux. Local data is partitioned by account, so two accounts on one computer do not share workspaces or history. The first account to sign in adopts an existing local installation, which keeps its workspaces and history instead of starting empty. ## Lifecycle Local sessions run on your computer. They stop when the computer sleeps, when the runtime stops, or when you sign out. Closing the client window does not stop running terminal or agent sessions; they are still there when you reopen the window, as long as the runtime is still running. The app checks its local runtime regularly and reconnects automatically if the connection drops. Closing the app leaves running sessions on the runtime, so terminals and agents can be resumed on the next launch. > **Note.** A runtime update ends local terminal and agent sessions. Saved conversations remain, and new sessions start on the updated runtime. ## Availability Packaged desktop builds ship for Linux x86_64 as a tarball and an Arch/Omarchy package. macOS packaging is in progress, and Windows builds are not published yet. If the runtime does not start, the startup screen shows **Retry** and, after 12 seconds, **Connection settings**. An incomplete build reports that the local runtime is missing instead of connecting to another service on the same port. ## Related - [How machines work](/machines/overview) - [Install the desktop app](/start/install) - [Concors Cloud machines](/machines/cloud) - [Troubleshooting](/help/troubleshooting) --- # Concors Cloud machines Concors Cloud machines are VPSs that Concors provisions and manages for your organization. Each one runs Ubuntu 24.04, connects over an authenticated hostname, and is billed monthly. This is the supported path for work that must continue when your own computer is off. ## Create a machine 1. Open **Settings → Machines**. 2. Choose **New machine**. 3. Complete the three wizard steps: **Server**, **Customize**, and **Review**. 4. Confirm on **Review** to create the machine. Nothing is ordered while you move between steps; only the final confirmation deploys a machine. ### Server - **Name**: lowercase letters, digits, and hyphens, for example `build-box`. - **Region**: a location in the United States, Europe, or Canada. - **Size**: one of the sizes below. | Size | vCPU | RAM | Disk | | ------ | ---- | ----- | ------ | | small | 2 | 4 GB | 40 GB | | medium | 4 | 8 GB | 75 GB | | large | 6 | 12 GB | 100 GB | | xlarge | 8 | 24 GB | 200 GB | **Continue** stays disabled until the name, region, and size are valid. ### Customize Choose the development tools to install after the machine is created: - Node.js, with a version select (defaults to the latest LTS, and includes npm, pnpm and Yarn) - Python and uv - Go - Rust and Cargo - Docker If your organization has no SSH keys yet, add one before you continue. SSH keys are for logging in from your own terminal; Concors manages the machine with its own key. See [SSH keys](/machines/ssh-keys). ### Review Review the machine specifications, the selected tools, your payment method, and the recurring price. Choose **Pay & deploy**, or **Deploy VPS** when your environment is unbilled. A failed creation keeps the review open with an error, and your choices are preserved. ## After creation The machine card shows its current status: | Status | Meaning | | --------------------------- | --------------------------------------------------- | | Ordering server | The order is being placed with the provider. | | Waiting for provider review | The provider is reviewing the order. | | Installing | Ubuntu and the Concors runtime are being installed. | | Running | The machine is ready to connect. | | Stopped | The machine is not running. | | Error | Creation or installation failed. | When the machine is running, the card shows SSH access as `ssh ubuntu@
` with **Copy SSH command**. It also shows the status of the development tools you selected, with **Retry setup** if one failed, and **Memory** and **Disk** meters from the machine's heartbeat. You can rename the machine, choose an icon, and cancel it. Cancelling keeps the machine running until the end of the current period, and the current month is not refunded; choose **Keep machine** to reverse a scheduled cancellation. > **Note.** Cloud machines must stay running. Stopping or cancelling a machine ends its terminal and agent sessions; saved conversations remain. Your client connects through a Concors-managed hostname using a short-lived access token. The token is never sent to your development servers. ## Related - [How machines work](/machines/overview) - [Machine subscriptions](/billing/subscriptions) - [SSH keys](/machines/ssh-keys) - [Resources and processes](/machines/resources) --- # Connect your own machine You can run the Concors runtime on a Linux machine you control and connect a client build to it. The runtime is the same one behind **This computer** and Concors Cloud machines. > **Preview.** The supported path for remote machines is [Concors Cloud](/machines/cloud). Running the runtime yourself is a preview and development path. Automatic enrollment and in-app pairing are planned, not available yet. ## Install the runtime 1. Copy the `concors-daemon` binary to the machine. 2. Start it on the loopback interface: `concors-daemon serve --host 127.0.0.1 --port 7420`. The host and port are optional; the defaults listen on loopback port 7420. 3. Check the health endpoint: `curl http://127.0.0.1:7420/health` returns `{"status":"ok"}`. 4. Keep the process running under a service manager so it restarts after a reboot or a crash. The health response also reports the runtime version, so you can confirm which build a machine is running before you connect. The runtime owns the same things here as on any other machine: workspaces, saved conversations, terminal processes, and schedules. Sessions survive client disconnects exactly as they do on a managed machine. ## Protect the connection The runtime has no built-in remote authentication in direct mode. Do not expose its port to the internet; anyone who can reach the port can use the machine. Choose one of these: - Join the machine and your devices to a private network such as Tailscale or WireGuard, and reach the runtime over that network. - Put a TLS reverse proxy in front of it and allow only authenticated traffic through. Both options keep the runtime itself on loopback or on a private interface. ## Connect a client Pairing from inside the app is not available. A preview build of the client can be pointed at the machine's `wss://` address before it is built: 1. Configure the build with the address of your protected endpoint. 2. Build and run that client. 3. Select the machine in the machine switcher. Connecting to a typed runtime address is a developer fallback. Cloud machines are listed automatically from your organization; self-managed machines are not. ## Requirements | Item | Requirement | | -------------- | -------------------------------- | | Runtime | Node 24, or the packaged runtime | | Source builds | pnpm 10 or newer | | Machine access | An SSH key on the machine | ## Limits This path has no managed certificates, hostnames, billing, or automatic updates. You install the runtime, keep it running, and update it yourself. The runtime must stay running for sessions to continue. ## Related - [How machines work](/machines/overview) - [Concors Cloud machines](/machines/cloud) - [Resources and processes](/machines/resources) - [Get help](/help/support) --- # Resources and processes Concors shows how much of the selected machine is in use and lets you inspect the processes behind that usage. Both are read-only views. Nothing here limits a workload or stops work on its own. ## CPU and RAM indicator The bottom status bar of the workspace shows the selected machine, its CPU percentage, and RAM used over total, with a percentage. The indicator covers the whole machine, not only Concors, and stays visible when the sidebar is collapsed and while workspace content scrolls. It is hidden in Settings. | State | What you see | | ------------ | --------------------------------------------------------------- | | Normal | CPU percentage and RAM used/total | | High usage | CPU or RAM at 90% or more | | Stale | Readings disappear after about ten seconds without a new sample | | Older daemon | **Update daemon for usage** | Readings come from the selected machine's runtime. Switching machines drops the previous readings immediately. The first CPU reading is unknown while the baseline is established, and unavailable counters are never shown as zero. ## Open Resources Open **Resources** in any of these ways: - The computer menu at the top of the sidebar - The CPU/RAM indicator - Workspace search ## The Resources page The page lists the processes on the machine with these columns: | Column | Meaning | | ------- | -------------------------------------------------- | | CPU | Share of the whole machine | | RAM | Resident memory | | State | The process state reported by the operating system | | Ports | Listening ports | | Preview | Shown only when the process serves browser content | Expand a row to see its PID, working directory, and, when applicable, the reason it is protected. **Stop** is in the expanded row. - Filter the list by name, PID, or folder. - Sort by RAM, CPU, or name. - The list refreshes every few seconds while the page is open. > **Requires a recent machine runtime.** If a control is missing, update the runtime on that machine. ## Stopping a process **Stop** asks for confirmation and rechecks the process identity before sending a signal. System processes and the runtime's own processes are protected and cannot be stopped this way. Stop sends `SIGTERM` to the selected process only. Child processes may remain, and a process can ignore the signal. There is no force-kill and no automatic stop, and a sleeping or idle process is not treated as unwanted. ## Limits - Process inspection is available on Linux machines only. - Values are visibility only. They do not cap CPU or memory and are not provider billing quotas. - CPU and RAM can differ from what a container or service limit reports, and shared memory can be counted more than once across processes. ## Managed machine cards Concors Cloud machine cards show **Memory** and **Disk** usage from the machine's 30-second heartbeat. A sample is stale after 90 seconds or whenever the machine is not running, and missing samples display as unavailable, never as zero. ## Related - [How machines work](/machines/overview) - [Concors Cloud machines](/machines/cloud) - [Previews and dev servers](/capabilities/previews) - [Usage and limits](/billing/usage) --- # SSH keys SSH keys let you log in to your organization's machines from your own terminal, outside Concors. They are separate from any GitHub connection and from the accounts your agents use. ## Where to manage keys Open **Settings → SSH keys**. Each entry shows the key name, its type and fingerprint, and the date it was added. A key created on the current device is marked **This computer**. ## Add a key 1. Create a key pair on your computer if you do not have one, for example with `ssh-keygen -t ed25519`. 2. Copy the public key, normally the contents of `~/.ssh/id_ed25519.pub`. 3. In **Settings → SSH keys**, choose **Add SSH key**. 4. Enter a **Name** you will recognize, paste the **Public key**, and save. Paste the public key contents only. The private key never leaves your computer. Concors does not ask for it and cannot use it. The full key text is shown only while you add it; after you save, the list shows the fingerprint and type instead. Use one key per device. If a computer is lost or replaced, remove its key without affecting the others. On the desktop app, you can also choose **Set up SSH on this computer**, which creates `~/.ssh/concors_ed25519` if that file does not exist, registers the public key under the computer's name, and shows the `ssh` command to use. An existing key is never replaced. ## When keys are installed Public keys are installed on your organization's machines when the machines are created. Adding a key later does not reach machines that already exist; those keep the keys they had. Removing a key stops it from being installed on machines created afterward, and the key stays on existing machines, so remove it there directly if you need to. > **Note.** If no keys exist for your organization, Concors warns you before machine creation. Add a key first so you can reach the new machine from your terminal. ## Fingerprints and removal - Fingerprints identify a key without exposing it. Compare the fingerprint shown in Concors with the one printed by `ssh-keygen -lf .pub` if you are unsure which key is which. - Removing a key deletes it from the organization's list. Use **Remove** on its row and confirm. - Keys do not expire on their own. Remove a key when you no longer trust the device that holds the private half. ## Related - [Concors Cloud machines](/machines/cloud) - [Terminals](/capabilities/terminals) - [Git and GitHub](/capabilities/git) - [Sign in and accounts](/start/access) --- # What is an agent? An agent is a coding CLI that runs on the machine you choose and is driven from a chat pane in Concors. You write prompts in the pane; the CLI does the work in your workspace with the account you already use. ## What an agent can do Agents work inside the open workspace. Depending on the provider, an agent can: - read, create and edit files in the workspace - run shell commands and read their output - search file names, paths and workspace structure - call MCP tools configured for the provider - propose a plan and track each step as it works - ask for your approval before sensitive actions ## How a turn works 1. You write a prompt in the composer and press Enter. The session sends it to the provider CLI on the machine. 2. The agent decides which tools to use and calls them. Tool rows appear in the timeline with a running, completed, failed or interrupted state. 3. When a call needs your consent, an approval card appears and the turn waits. See [Approvals and control](/agents/approvals). 4. The agent writes its reply in the timeline with a summary of the work and any command or file output you can expand. ## Agent statuses The pane and the sidebar badge both reflect the session state. | Status | Meaning | | ----------- | ------------------------------------------------------------- | | Starting | The pane is opening a session with the provider. | | Ready | The session is idle and waits for your next prompt. | | Working | The agent is running a turn. | | Needs input | The agent waits for an approval or an answer. | | Done | The agent finished a turn. The badge clears on the next turn. | | Failed | The turn or the session ended with an error. | | Interrupted | The turn was stopped, by you or by a runtime restart. | ## Where agents appear The **Agents** list in the sidebar shows one row per live session, including terminal sessions that run a detected agent. Each row shows the provider icon, the agent name and a status badge. An unread dot marks a finished or needs-input update you have not seen. Rows are sorted by most recent activity. Open a row to return to its conversation, and use [Notifications and sounds](/workspace/notifications) to control alerts. ## Sessions that keep running An agent session lives on the machine, not in the window. Closing the pane, the tab or the client does not stop it. Reopening the pane reattaches to the same conversation and shows the recorded turns. Several agents can run side by side with terminals in the same workspace. A plain terminal is a shell you drive yourself. An agent is a provider CLI with a structured conversation, tool summaries, approvals, status and saved history. Terminal-based agents still report status in the Agents list. See [Terminals](/capabilities/terminals) for the plain terminal case. > **Note.** Concors does not resell model inference. Requests run through the provider account configured on the machine, and the provider's own usage and limits apply. ## Related - [Supported agents](/agents/providers) - [Conversations and workspaces](/agents/conversations) - [Approvals and control](/agents/approvals) - [Terminals](/capabilities/terminals) --- # Supported agents Concors runs the agent CLIs you already use on the machine you choose. Five integrations are enabled by default, and a catalog of opt-in presets adds more providers once you enable them. ## Built-in providers | Provider | State by default | Notes | | -------------- | ---------------- | ------------------------- | | Codex | Enabled | OpenAI Codex CLI | | Claude Code | Enabled | Anthropic Claude Code CLI | | OpenCode | Enabled | OpenCode CLI | | Pi | Enabled | Pi coding agent | | GitHub Copilot | Enabled | Built-in preset | | OMP | Disabled | Oh My Pi | Enabled providers appear in the **Agent and model** picker when a session starts. ## The opt-in preset catalog The same page lists dozens of opt-in presets, including Cursor (`cursor-agent acp`), Gemini CLI, Cline, Goose, Kiro, Kimi Code CLI, Factory Droid and Qwen Code. Presets are disabled until you enable them. A preset does not certify every CLI or account, and Concors does not load arbitrary third-party plugins. ## Settings → Providers 1. Connect to the machine you want to use. 2. Open **Settings → Providers**. This works from desktop and mobile. 3. Choose **Check provider installations** to discover the CLIs installed on that machine. Discovery reads the machine; it does not download packages. 4. Use **Search providers…** to filter the list, or **Add provider** to define a custom profile. 5. Choose **Install** when a package installer is offered, or open the provider's install guide link and install it yourself. 6. Enable the provider so it appears in the agent picker. Each row shows a status and the actions available for that provider. | Status | Meaning | | --------------------------- | --------------------------------------------------- | | Not installed | The CLI was not found on the machine. | | Installed · Enabled | The CLI is present and offered in the agent picker. | | Installed · Disabled | The CLI is present but hidden from the picker. | | Installing on this machine… | A managed install is running. | Rows with a package installer show **Install**; others link to the provider's external install guide. **Configure** opens the provider editor. ## Configure a provider | Field | What it sets | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | The label shown in pickers. | | **Protocol** | The engine that drives the CLI. | | **Executable** | The command to run. | | **Arguments · one per line** | Extra arguments, one per line. | | **Enable in the agent picker** | Whether the provider appears when you start a session. | | Credentials | Environment keys the CLI reads, and a model IDs filter, one per line. Leave the filter blank to show the provider's full catalog. | | **MCP servers** | A JSON override for the servers the provider loads. A blank value keeps saved overrides; `[]` removes them. Hidden where the provider does not support overrides. | > **Note.** Installed does not mean signed in. Open the provider's CLI in a terminal on that machine, or use the account prompt in the agent pane. See [Agent accounts](/agents/accounts). ## Structured chat and terminal agents Most providers open as structured chat with status, approvals, queues and saved history. Some agents run in a terminal session instead. Terminal-based agents still appear in the Agents list with their status. Controls vary by provider and version; a CLI can refuse an operation because of its own version, account or current turn. ## Related - [Agent accounts](/agents/accounts) - [Models and agent settings](/agents/models) - [What is an agent?](/agents/overview) - [Terminals](/capabilities/terminals) --- # Agent accounts Concors never asks for provider credentials. Each provider CLI stores and refreshes its own account on the machine, and the agent pane only helps you start the sign-in and shows its progress. ## The account prompt When you open or select an agent, the pane checks the selected provider's account. If none is configured, a prompt appears above the composer. You can dismiss it and continue with the credentials already present on the machine, and the dismissal is remembered for that machine and provider. The small **Connect account** button reopens the prompt. Neither the check nor the dismissal blocks sending prompts. If a check fails, the prompt offers a retry and the composer stays usable. The prompt is a convenience, not a gate. An agent that already has credentials in its environment keeps working while you decide, and the check runs again on later sessions. ## Sign-in flows ### Codex and ChatGPT The prompt shows a one-time device code and a link to OpenAI's sign-in page. Open the link, enter the code, and wait for the completion. Some accounts need device-code login enabled in ChatGPT security settings first. ### Claude Code The prompt shows the CLI's browser link. Sign in, complete the authorization, and paste the authorization code back into the prompt. Both Claude subscriptions and Anthropic Console accounts are offered. ### OpenCode Sign in with OAuth in the browser, or add an API key. Free and local models do not count as a signed-in account. ### Pi, OMP and ACP providers Sign in through the provider's own CLI in a terminal on the machine. Concors does not run these sign-in flows in the pane. ## What Concors keeps Provider CLIs save and refresh their own credentials on the selected machine. Login challenges and the codes or keys you submit are transient: they are never stored in conversation history, drafts or client storage, and an unfinished sign-in expires. Cancel, dismissal or disconnecting the client ends the associated sign-in process. Concors keeps no copy of your provider credentials; they stay with the provider CLI. ## Accounts belong to the machine An agent account is machine state shared by the agents running there, and it is separate from your Concors account. Sign in once per machine and per provider. Adding another machine means signing in there as well. Your Concors account covers the client, machines and billing; see [Sign in and accounts](/start/access). > **Requires a recent machine runtime.** If the account prompt or **Connect account** is missing, update the runtime on that machine. ## Related - [Supported agents](/agents/providers) - [Sign in and accounts](/start/access) - [What is an agent?](/agents/overview) - [Troubleshooting](/help/troubleshooting) --- # Conversations and workspaces An agent conversation belongs to one workspace on one machine. It lives in an **Agent** pane inside a tab and keeps its own provider, model and transcript. ## Starting a conversation Open **New tab → Agent** to create an empty agent pane in the current workspace. The session starts automatically and shows **Preparing agent…** until it is ready. Choose the provider and model from the composer's **Agent and model** picker. The agent sees the files under the workspace the pane belongs to. ## Switching providers Changing the provider in the composer starts a new conversation in the same pane. Each provider keeps its own conversation, and switching back restores that provider's history without replaying prompts. Concors never replays one provider's transcript into another. A running turn, an open approval or queued messages must be finished or stopped before you switch, so no work is hidden in a detached session. ## Sessions outlive panes and clients The session runs on the machine, not in the client. Closing the pane, the tab or the client leaves it running, and reopening the pane reattaches to the same conversation with its recorded turns. Each conversation keeps its own pane, so work in one session never overwrites another. You can run several conversations in one workspace at the same time, in separate tabs or split panes. See [Running work in parallel](/capabilities/parallel). If the machine's runtime restarts, active turns are marked interrupted and their queues pause until you resume them. Disconnecting a client does not interrupt anything. ## Queuing follow-ups While the agent is working, pressing Enter queues a follow-up on the machine instead of sending it. The queue panel shows **Follow-ups run on this machine** or **Queue paused**, with **Pause queue**, **Resume queue** and per-item **Remove queued message**. Up to 20 queued messages keep running after every client closes; a stop, a failure or a runtime restart pauses delivery until you resume it. See [Approvals and control](/agents/approvals#queue-follow-ups) for the details. ## Where history lives Conversations are saved on the machine. Reopening a pane resumes the provider's own session and backfills the transcript the provider still has. Each machine keeps up to 128 saved sessions. Unsent drafts are scoped to the machine and the conversation, so a message you typed but did not send returns with the pane. Use [Resume saved sessions](/agents/resume) to bring a session from the provider's CLI into Concors, and [Chat history and navigation](/agents/history) to see what is kept. ## Related - [Models and agent settings](/agents/models) - [Approvals and control](/agents/approvals) - [Resume saved sessions](/agents/resume) - [Chat history and navigation](/agents/history) --- # Models and agent settings The **Agent and model** picker in the composer is where you choose the provider, the model and the controls the provider exposes for the current conversation. ## The picker Open the picker from the composer. It groups providers and lists the models reported by the selected provider and account. Under each provider, **Current conversation** marks the provider in use; **Use in this pane** switches to another one, which starts a new conversation. Type in search to filter the list. The list comes from the provider and is cached for a few minutes. Reopening the picker, focusing the window or leaving the composer visible refreshes it in the background. A cold catalog can take time; while it loads, the pane may say "Models are being discovered. They will appear here automatically." If the provider has never reported a model, the pane says "No models reported. Check this provider in Settings." or shows **Select model** without guessing a version. Concors does not list a model the provider does not advertise. ## Thinking effort **Thinking effort** lists **Default ({model default})** plus the effort levels the selected model supports. The choice applies to the current conversation. ## Agent mode Providers that offer modes show an **Agent mode** control next to the model. The available modes depend on the provider and the model. ## Permission mode for Codex Codex adds a **Permission mode** control. Shift+Tab in the composer cycles the three modes. | Mode | Behavior | | ------------------- | --------------------------------------------------------- | | Default permissions | Workspace access; asks when approval is needed. | | Auto-review | Same sandbox; eligible requests go to the reviewer agent. | | Full access | File and network access without approval prompts. | ## Plan mode and Speed **Plan mode** asks the agent to explore and plan with read-only access before it changes anything. When a completed plan proposal exists, the agent supports plan mode and the agent is idle, an **Implement plan** button appears. Codex also offers **Speed** tiers through its own picker. ## Context window The ring beside the composer shows how much of the model's context window the conversation has used. Open it to see "{used} / {limit} tokens · {n}% used" and "{total} cumulative tokens". If the provider has not reported usage yet, the popover says "Usage will appear after the agent reports it." The ring is not a provider plan or billing meter; see [Usage and limits](/billing/usage). ## How switches apply Model, thinking, mode and permission changes apply to the current conversation and take effect on the next message. Providers vary: a control appears only where the provider offers it, and a CLI can refuse an operation because of its version, account or current turn. ## Related - [Conversations and workspaces](/agents/conversations) - [Approvals and control](/agents/approvals) - [Supported agents](/agents/providers) - [Usage and limits](/billing/usage) --- # Approvals and control Agents can change files and run commands, so providers ask for permission at sensitive moments. Concors shows each request as a card in the agent pane and keeps it available while you are disconnected. ## Approval cards An approval card shows the provider's title and summary, an optional plan in Markdown, and a **Review request details** expander with the full request. The buttons come from the provider, or fall back to **Allow once**, **Dismiss** and **Cancel turn**. Permission scopes keep the provider's native labels, such as once, session, always or rule. **Dismiss** denies that request; the turn may continue with other work. **Cancel turn** interrupts the active turn, settles any pending questions and rejects late results. The two actions are separate, so denying one tool does not have to end the turn. Approvals survive disconnects and are visible from any connected client. Any device can answer the same card, and it clears everywhere once resolved. ## Questions When the agent needs more than a yes or no, it asks a question card: - radio or checkbox options, each with a description - **Other answer** for free text - optional multiline or secret fields - **Submit answers** or **Continue** to send the response Some MCP servers need an external sign-in. In that case the card links to the server's authentication page and offers an **Authentication completed** button for when you return. Agents can also ask questions after a later turn; the card waits for you. ## Queue follow-ups While the agent is working, sending a message queues it on the machine instead of interrupting the turn. The queue panel shows "Follow-ups run on this machine" when delivery is active, or "Queue paused" with **Resume queue**. Use **Pause queue** to hold delivery and **Remove queued message** on any item you no longer want. Up to 20 queued messages keep running when all clients are closed. A stop, a failure or a runtime restart pauses delivery until you resume it. ## Steer, interrupt and retry **Steer the current turn** appears when the provider supports steering and you have a draft without attachments. It adds your instruction to the running turn rather than queueing it. **Interrupt agent** stops the current turn. If the client cannot confirm that a message arrived, it shows "Delivery could not be confirmed." with **Retry same message**. Concors does not resend automatically, so send it again only when you mean to. ## Related - [Models and agent settings](/agents/models) - [Conversations and workspaces](/agents/conversations) - [What is an agent?](/agents/overview) - [Notifications and sounds](/workspace/notifications) --- # Resume saved sessions An empty agent conversation offers **Resume session** so you can bring older work back into a pane. New chats still prepare the default provider automatically; the picker is there when you want a saved conversation instead. ## Opening the picker Select **Resume session** in the empty pane. The list combines saved conversations from every enabled, installed provider for the workspace folder on the connected machine. Each row shows the provider's logo and name, the conversation title, and when it was last active. - **Search** filters by title. Results arrive as you type, and the list keeps loading while a search is running. - Provider filter chips narrow the list to one provider. Filtering keeps the pages already loaded. - **Refresh sessions** in the header starts a fresh listing from every provider. - Scroll to the end of the list to load older results automatically. Each provider loads on its own. If one is slow or fails, its rows show a retry action and the other providers stay usable. When nothing matches, the pane shows "No saved sessions in this workspace." Some rows carry a state instead of resuming directly: - **Already open** means the conversation already has a pane in this workspace. Selecting it focuses that pane. - **Working in another client** means the provider reports that the conversation is active elsewhere. Leave it until that work finishes. ## Resuming a session 1. Stop the provider CLI in its terminal first. Concors cannot take over that process for you. 2. Select the conversation. An empty pane is reused; a conversation that is already open is focused instead. 3. Concors loads the provider's saved conversation and restores its history without sending a prompt. A resumed conversation stays with its own provider. Newly imported sessions start with the provider's defaults instead of an unrelated model override, and they inherit conservative permission defaults. Detached sessions that were idle are rebound with the settings they already had. > **Note.** **Resume session** acts on an empty pane. A draft, attachments, queued messages, pending requests, or an active conversation block the picker; clear or finish them first if you meant to replace the pane's work. ## What resuming does not do - It does not take over or kill a provider CLI that is running in a terminal. Stop that process yourself, then resume. Busy conversations and active detached agents are rejected. - It does not copy messages into a different provider. Each conversation stays with the provider that saved it. - It does not install providers or sign you in. Only enabled, installed providers appear in the list. - It does not list other folders or workspaces. Results stay in the current workspace folder. - It does not send a prompt, approve a tool call, or replay earlier messages. > **Requires a recent machine runtime.** If **Resume session** is missing, update the runtime on that machine. ## Related - [Conversations and workspaces](/agents/conversations) - [Chat history and navigation](/agents/history) - [Supported agents](/agents/providers) - [Terminals](/capabilities/terminals) --- # Chat history and navigation A conversation is saved on the machine, and the pane shows a window of it. You can page through old messages, jump to anything you sent, and return to the newest reply. ## What is kept and what is loaded The full conversation persists on the machine. The pane keeps up to 240 messages in its current window and loads more in pages of 80. - Scrolling near the top loads earlier messages and shows "Loading earlier messages…" while a page arrives. - Scrolling near the bottom loads newer messages that were trimmed from the window. - Persisted history is not deleted when a page leaves the window. - A visible-message anchor keeps your place when pages arrive or leave, and a new reply does not pull you to the bottom while you are reading older history. - **Latest** returns to the newest page, even when another page is still loading. - If a page fails, the existing messages stay and **Retry loading messages** appears. Concors does not retry in a loop on its own. ## The message rail A rail beside the conversation marks the messages you sent. - Hover a marker to preview that message. - Click a marker to jump to it. Concors fetches the context around the message, then resumes normal scrolling. - Use Up and Down to move between markers, Home and End to reach the first or last one, and Enter to jump. - New prompts stay indexed while you read older history. On narrow panes the rail is hidden, and the history navigator is the **Browse your messages** dialog at the top of the pane. Mobile uses the same dialog. ## What is never replayed Jumping to an old message moves the view. It does not resend anything. - Failed turns keep their messages. The error and the partial output stay in the transcript. - Interrupted sessions keep their messages. If the machine's runtime restarts, the active turn is marked interrupted and its messages remain. - No message is ever resent when you jump to it, and no prompt is delivered again. - When you come back to the app, notifications restore the sidebar's unread badges instead of replaying old alerts. > **Requires a recent machine runtime.** Older daemons still load earlier messages as you scroll. The bounded window and newer-message paging need a current daemon; if a control is missing, update the runtime on that machine. ## Related - [Conversations and workspaces](/agents/conversations) - [Resume saved sessions](/agents/resume) - [Notifications and sounds](/workspace/notifications) - [Search](/capabilities/search) --- # Schedules and automations A schedule runs a saved prompt on a cadence on one machine. The runtime starts each run, so schedules keep working while your client is closed, as long as the machine stays on. ## Creating a schedule 1. Open **Schedules** above Workspaces in the sidebar. 2. Select **New schedule**. 3. Fill in the form. | Field | What it does | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | Name | The label on the schedule's card. | | Workspace | The folder each run works in. | | Agent session | **New dedicated session** creates one saved conversation on the first run and reuses it, or choose an existing session. | | Provider | The installed provider for a new session. | | Model | Leave **Provider default**, or pick a model. | | Prompt | The instruction sent on each run. | | Repeat | **On an interval**, **Daily**, or **Weekly**. | | Every | The interval in minutes, minimum 15. | | At | The time for daily and weekly schedules. | | On these days | The weekdays for weekly schedules. | | Time zone | The zone used by daily and weekly schedules. | 4. Select **Enable schedule** to start the cadence, or leave it off to save a paused schedule. Daily and weekly schedules use an IANA time zone. A repeated clock time at the end of daylight saving runs once; a time that does not exist at the spring change is skipped. **Next run** timestamps use the time zone of the device you are viewing them on. ## Watching runs Each card shows Active or Paused, the last run status, its cadence and the next run. Statuses are Working, Needs input, Done, Failed, Skipped, and Interrupted. - **Run now** starts a run immediately and works on paused schedules too. - **Pause** and **Resume** control future runs. Stop a current turn in its chat. - **Edit** changes the schedule. **Delete** removes it and keeps its conversation. - Expand **Recent runs** to see history, and select **Open agent** to open the conversation a run used. A dedicated schedule marks its session with a clock in the agent sidebar. The conversation stays available between runs. ## Limits | Limit | Value | | ------------------------ | ---------- | | Schedules per account | 64 | | Recent runs per schedule | 20 | | Minimum interval | 15 minutes | - A run is skipped when the session is busy, a prompt is queued, or an approval is pending. Skipped occurrences still appear in the run history. - A run that cannot start on time is recorded as missed and is not replayed. The cadence moves to the next occurrence. - The machine and its runtime must stay on for schedules to run. - Runs use the session's current model and tool-approval settings. A run that needs approval may wait for you. ## Asking an agent Codex, Claude Code, and OpenCode can create and manage schedules for you. Ask an agent inside its workspace. For example: "Create a Concors schedule to review recent commits every weekday at 09:00, using this conversation." Agent-created schedules appear in the same list and are labeled **Created by agent**. Normal provider approvals still apply, and an agent can manage schedules only in its own workspace. Cron jobs and schedules created outside Concors are not imported. > **Note.** Newly started or resumed providers receive the schedules ability. An existing process needs to reconnect after the runtime is updated. ## Related - [Conversations and workspaces](/agents/conversations) - [Approvals and control](/agents/approvals) - [Notifications and sounds](/workspace/notifications) - [How machines work](/machines/overview) --- # Voice dictation On supported desktop browsers, the composer offers a microphone button. Dictation turns your speech into draft text that you review before sending. ## Before you record The microphone sits in the composer, beside the send button. It is disabled when the browser has no speech recognition support, and when the draft already holds 16,000 characters. On phones, use the keyboard's microphone key instead; the app does not request microphone permission there. ## The recording view Selecting the microphone replaces the composer with a recording view. It shows **Listening**, a live waveform and volume meter for the microphone signal, and a timer for the recording duration. The controls are: | Control | What it does | | -------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Stop dictation** | Ends capture and shows the transcript for review without sending. | | **Edit** | Ends capture and returns the text to a focused, editable composer. | | **Cancel dictation** | Discards the dictation and restores the draft from before recording. Escape does the same. Existing attachments stay. | | Send | Ends capture, waits for the speech service's final result, and sends the text through the usual chat path. | A working agent queues a message sent this way, as it would any other. An empty dictation never sends an existing draft or attachment by itself. ## While you dictate Dictated words are appended to the draft as they are recognized and saved with the session's draft. You can edit the text before sending. Switching tabs, hiding the app, disconnecting, or closing the composer releases the microphone. A pending send cannot deliver after you leave the tab or disconnect. If recognition stops unexpectedly, the words captured so far stay in the draft. If recognition takes too long to finish, a five-second timeout ends capture and keeps the words for review. Results from a canceled recording never overwrite a newer draft. ## Recognition and privacy Speech recognition uses your browser's speech service, which may send audio to its own network service. Concors measures the waveform locally at up to 20 samples per second to draw the meter. It does not record or upload audio, and every microphone track and audio context is released when dictation ends, is canceled, or fails. If metering is unavailable, transcription still works and the meter reports that its level is unavailable. With reduced motion enabled, the scrolling waveform history is hidden and the live level meter remains. ## Errors - Microphone permission denied: the recording view closes and the composer returns. Grant permission in the browser to dictate. - No speech detected: recording ends without adding text. - Unexpected stop: the words captured so far remain in the draft, with the error. - Could not finish: finalization timed out. Review the captured words, edit them, and send when ready. Nothing is sent automatically when an error occurs. ## Related - [Conversations and workspaces](/agents/conversations) - [Approvals and control](/agents/approvals) - [Chat history and navigation](/agents/history) - [Concors on your phone](/start/mobile) --- # Terminals A terminal in Concors is a real PTY session owned by the machine, not by the pane that shows it. It keeps running when the pane or the client closes, and more than one device can view it. ## Starting a terminal 1. Select **New tab** and pick a profile. **Terminal** opens the machine's default shell. **Codex**, **Claude Code**, and **OpenCode** open those agent CLIs. Custom profiles run the commands you saved. 2. The session starts automatically in the workspace folder once the tab opens. 3. Splitting a pane or switching a pane to a terminal profile also starts a session. An ended session needs an explicit restart. Agent CLIs must already be installed and signed in on the machine. Concors does not install them or move credentials. A live Codex, Claude Code, or OpenCode terminal appears in the Agents list, labeled **Open in terminal**. Process activity is not an agent status: only structured chat events show working, done, or needs input. ## Input ownership - The device that clicks or types in a terminal controls its input and dimensions. Other viewers are read-only until they claim the terminal. - An unowned terminal activates automatically for the device that focuses it, without taking control from another device. - Closing the controlling view releases ownership, and typed input is never replayed automatically. ## Banners and recovery - **Reconnecting…** appears while a client reattaches. The last screen stays visible, and the scroll position is preserved where possible. - **Session ended** appears when the process exits. - **Session failed** offers **Start new session** and **Retry connection**. Closing a pane, tab, or client does not stop the process. Use **Stop** in the **Sessions** menu to end it; Concors waits for the exit event. **Sessions** lists current and historical terminals, including sessions detached when a workspace or tab was removed. Create an empty pane in the same workspace and choose **Attach an existing session** to restore a detached binding. When the runtime restarts or the machine reboots, recovery follows these rules: - A shell reopens in the workspace directory. Previous variables, jobs, and commands are not replayed. - Codex and Claude resume their saved sessions and open the provider's conversation picker. You select the conversation; Concors does not guess. - An unknown process recovers to a shell. Explicitly stopped sessions stay stopped. ## Profiles Open **Settings → Terminals** to add, edit, or delete profiles. Each profile has a name, an executable, and arguments, one argument per line; spaces inside a line stay together. Arguments are passed individually, without shell expansion, so use an explicit shell command for a script. Profiles are saved on the machine and synced to connected clients. Concurrent edits report a conflict instead of overwriting another device. A pane keeps the profile it was created with, so editing or deleting a profile does not change existing sessions. ## Limits and clipboard | Limit | Value | | ----------------------------- | --------- | | Running terminals per machine | 16 | | Terminal emulator instances | 32 | | Retained terminal sessions | 256 | | Scrollback per session | 500 lines | Terminals render 256 colors and true color, with light and dark palettes. Clipboard shortcuts are Ctrl+Shift+C and Ctrl+Shift+V, or Ctrl+Insert and Shift+Insert, and Super+C and Super+V on macOS. Plain Ctrl+C still interrupts the running command. ## Related - [Files and the editor](/capabilities/files) - [Running work in parallel](/capabilities/parallel) - [Keyboard shortcuts](/workspace/shortcuts) - [Resources and processes](/machines/resources) --- # Files and the editor The **Project files** button opens a file tree for the current workspace. You can browse the workspace, edit text files in place, and keep drafts safe while an agent works in the same folder. ## Opening the file tree 1. Select **Project files** beside the workspace tabs. The panel is docked on the right on wide screens and opens as a full-height overlay on narrow ones. 2. Drag the panel's left edge to resize it between 240 and 560 pixels. Arrow keys resize in small steps, Home and End jump to the limits, and double-clicking the edge resets the width. 3. The width is remembered on this device. Expanded folders stay open when the panel closes, reopens, or refreshes. ## Finding files The toolbar above the tree has buttons for a new file, a new folder, hidden files, and refresh. - The filter searches names of entries that are already loaded. It does not search file contents. - Folders load when you expand them. - Dotfiles are hidden by default; the toggle is remembered on this device. - Use refresh after changes made outside this client. There is no directory watcher. ## Opening and editing Opening a file adds a file tab beside your session tabs. Up to 32 file tabs can be open at once. - Markdown opens as a rendered preview. Use **Edit source** for the raw text. - Other text files open in a CodeMirror editor with syntax highlighting, line numbers, search, word wrap, and optional Vim bindings. - Save with the toolbar or Ctrl/Cmd+S. With Vim bindings enabled, `:w` saves. - Agent Markdown links and file paths in tool results open in the same editor, including `:line` suffixes. Links outside the workspace are refused. - Drafts belong to the file, so switching tabs, workspaces, or machines does not throw them away. Closing a tab with unsaved changes asks first. ## Saving and conflicts Saves are written atomically and checked against the file's last known revision. If another process or client changed the file while you were editing, Concors keeps your draft and offers three choices: - **Compare with disk** shows the differences. - **Use disk version** replaces your draft with the version on the machine. - **Keep my draft** keeps your text so you can decide what to save. The active file is checked when it regains focus and every five seconds. A change on disk is flagged without replacing what you are reading or typing. ## Limits | Limit | Value | | ------------------------ | ---------------- | | File type | UTF-8 text only | | File size | 1 MiB | | Open file tabs | 32 | | Directory entries listed | 2,000 per folder | | Rename or delete | Not available | | Binary and image preview | Not available | | Symbolic links | Not followed | - There is no workspace-wide content search. Use find in the editor, an agent, or `grep` in a terminal. - File tabs and unsaved drafts belong to this client session. They are not synced and are not restored after a restart, so save before leaving. ## Related - [Terminals](/capabilities/terminals) - [Search](/capabilities/search) - [Conversations and workspaces](/agents/conversations) - [Troubleshooting](/help/troubleshooting) --- # Previews and dev servers Concors finds the dev servers your workspace starts and gives each browser page a reachable address. There is nothing to register or configure: start a dev server on the machine and it appears in the sidebar under **Previews**. ## How discovery works The machine runtime watches the ports that processes listen on. Each listener is probed, and only ports that answer with browser content are promoted to previews. The list refreshes while the sidebar is open, so a server appears within seconds of starting and disappears when it stops. Only pages appear. Agents, agent tool servers, the runtime's own services, and plain TCP listeners such as databases or message brokers are not previews, even when they hold a port. > **Note.** A preview is an HTTP page. Anything that does not answer an HTTP request with browser content stays out of the list. ## Open a preview 1. Open **Previews** in the sidebar. 2. Select a listed entry to open it in a new browser tab. Where the address points depends on the machine: | Machine | Address | | --------------------- | ------------------------------------------------------------------------ | | **This computer** | Its loopback address, such as `http://localhost:3000` | | Concors Cloud machine | An authenticated hostname per port, such as `3000.m-example.concors.app` | | HTTPS upstream | The same hostname with an `https-` label | ## Access on a managed machine On a Concors Cloud machine the address is authenticated for your account. Concors exchanges a short-lived credential for a private session cookie and never forwards it to the development server, which sees ordinary requests. Concors proxies HTTP and WebSocket traffic, so hot reload and live updates keep working. The preview route stays reachable only through the authenticated hostname; the machine's port is not published directly. The address is private to authorized Concors users with access to the machine. ## What you cannot do - There is no add, edit, or remove action. The list reflects what the machine finds. - You cannot point a preview at a different port or path by hand. - There is no preview for files, agent chats, or services that are not HTTP pages. Stop the server and its entry disappears on the next refresh. The machine does not keep a history of servers that are no longer listening. > **Requires a recent machine runtime.** If **Previews** is missing or a running server never appears, update the runtime on that machine. ## Related - [Resources and processes](/machines/resources) - [Running work in parallel](/capabilities/parallel) - [Terminals](/capabilities/terminals) - [How machines work](/machines/overview) --- # Git and GitHub Git runs on the machine, not in the client. Cloning, committing, and pushing all use the machine's own Git installation and credentials, so agents and terminals work the same way they do in a shell on that machine. ## Clone a repository 1. Open the plus menu next to **Workspaces** in the sidebar and choose **Clone repository…**. 2. Choose a source: - **GitHub repositories** picks from the accounts connected to Concors. Use the account picker, type in **Search repositories…**, and watch for the private lock badge on restricted repositories. **Load more repositories** fetches the next page. - **Paste a URL** accepts HTTPS, SSH/scp-style URLs, or a path on the machine. 3. Choose the destination folder. It defaults to `~/repos/` and stays editable. 4. Select **Clone repository**. A setup job runs with streamed progress, and **Cancel setup** stops it. Existing folders are never overwritten. Clones run as jobs, up to four at a time. You can close the dialog and the job keeps going; reopen the dialog to see its progress again. If the runtime restarts while a job is running, the job is marked interrupted instead of restarting on its own. Files the job already created remain on disk for inspection. ## Connect GitHub Open Settings, then **Account**, and find the GitHub card under **Integrations**. | Control | What it does | | ------------------------------- | ------------------------------------------------------- | | **Connect GitHub** | Starts authorization in your system browser. | | **Add account or organization** | Grants access to another account or organization later. | | **Reconnect** | Repairs an expired or revoked connection. | | **Disconnect** | Removes the connection from your account. | | **Refresh GitHub** | Reloads the status and repository access. | The card shows **Connected across your VPSs** when the connection is healthy. **Repository access** chips list the accounts and organizations you granted. Missing repositories are added on GitHub first: each organization must approve the installation, and membership alone does not grant access. ## Credentials The GitHub connection covers cloning through the repository picker. Concors authorizes the clone without exposing a token to your device, so a managed machine can clone the repository you chose. On the machine, Git operations use the credentials that are already there: an SSH agent or a credential helper. Cloning a pasted URL works only when the machine can authenticate that URL. If Git asks for credentials in a terminal, configure the machine's Git credentials first. Agents commit, branch, and push with their own tools. Concors does not intercept those commands; an agent uses the same SSH key or credential helper as your shell. > **Note.** Git credentials and known hosts must be configured on the machine. The client never sees or stores a GitHub access token. > **Requires a recent machine runtime.** If the clone dialog does not offer **GitHub repositories**, update the runtime on that machine. ## Related - [Pull requests](/capabilities/pull-requests) - [Files and the editor](/capabilities/files) - [The workspace](/workspace/overview) --- # Pull requests Concors tracks the GitHub pull requests opened against the repositories in your workspaces. You can review, merge, close, and comment without switching to GitHub. ## Where pull requests appear The sidebar has a **Pull requests** entry, and each workspace row shows its open count at the far right. Hover the count to see each repository's share, or select it to open the page filtered to that workspace. The **Pull requests** page lists every workspace and shows the total. ## The Pull requests page The page opens on **Open** and has three tabs: | Tab | Shows | | ---------- | ---------------------------------------------- | | **Open** | Open pull requests, drafts included | | **Merged** | The most recently updated merged pull requests | | **Closed** | The most recently updated closed pull requests | Counts in the sidebar and on the **Open** tab include open pull requests only, drafts included. Use **Refresh** to reload the list. Narrow it with: - **All workspaces**, or a chip for one workspace - A repository chip - **Opened by you** Rows show a **Draft** badge when the pull request is still a draft, along with review and check counts. Each open row offers **Merge** and **More actions for #n**, which contains **Close pull request…** and **View details**. Concors offers only the actions the machine's GitHub account is allowed to take. ## Pull request details Selecting a row opens the detail page with the merge status region, the state badge, the source and target branches, the size, labels, checks, the description, and the conversation. - **Merge…** asks you to confirm the method: squash, merge, or rebase, limited to the repository's allowed methods. While it runs, the button reads **Merging…**. - **Close…** closes the pull request without merging and offers an optional comment. - **Comment** posts to the conversation. Press Ctrl+Enter, or Cmd+Enter on macOS, to post. - **Open on GitHub** is the only link out. The merge uses the head commit you were shown, so GitHub refuses it if newer commits arrived. Drafts and conflicting branches cannot be merged. Out-of-date branches, branch protection, and failing checks are explained in the status region and left to GitHub, which may still let an administrator merge. ## GitHub access on the machine Pull request operations use GitHub credentials on the machine, not the connection used for cloning. The runtime looks for, in order: 1. `GH_TOKEN` or `GITHUB_TOKEN` in the environment 2. The GitHub CLI login (`gh auth token`) 3. The Git credential helper for `https://github.com` Lookups never prompt. A machine without a usable token shows **Sign in to GitHub on this machine** with the command to run. Run `gh auth login` on the machine and refresh. If GitHub rejects a token, the runtime forgets it and looks again on the next refresh. ## Which repositories belong to a workspace - A workspace inside a repository shows that repository, whether the workspace root is the checkout or a folder in it. - Any other folder shows its direct child repositories, one level deep. A child counts when it contains a `.git` entry. Linked children are ignored. - Several checkouts of one repository are grouped and counted once. ## Limits | Limit | Value | | ---------------------------------------- | ----- | | Open pull requests loaded per repository | 25 | | Repositories per workspace | 32 | | Repositories per machine | 90 | | Checks shown in a detail view | 50 | | Comments shown in a detail view | 30 | | Reviews shown in a detail view | 20 | A repository with more open pull requests links to the rest on GitHub. Descriptions and comments longer than 20,000 characters are cut, and listings are cached for a minute. A failed refresh keeps the last listing and says so. > **Requires a recent machine runtime.** If the sidebar shows no counts, update the runtime on that machine. ## Related - [Git and GitHub](/capabilities/git) - [Running work in parallel](/capabilities/parallel) - [The workspace](/workspace/overview) --- # Running work in parallel Concors is built to keep several streams of work going at once on one machine. Each piece runs in its own tab or pane, and the machine keeps everything alive while you look away. ## Ways to run work at once - **Tabs.** Each tab is a separate container, so one tab can hold a feature in progress while another holds a review. Switching tabs does not disturb the other. - **Split panes.** Split a tab horizontally or vertically to watch two sessions side by side, such as an agent and the terminal running its tests. - **Several agents.** Start a different agent for each task. One agent can implement a feature while another investigates a bug in a second workspace. - **Terminals.** Keep a terminal for the test runner and one for the dev server. Terminal sessions survive pane, tab, and workspace changes. - **Schedules.** A schedule runs an agent on a cadence, so recurring work proceeds with no pane open. ## What keeps running Sessions live on the machine, not in the window. Closing a pane, switching tabs, or closing the client does not stop an agent or a terminal. Reopen the pane and it reattaches to the same session. This applies to **This computer**, self-managed machines, and Concors Cloud machines while the machine is running. ## Limits These limits apply per machine unless noted. | Resource | Limit | | ---------------------- | ----- | | Tabs per workspace | 32 | | Panes per tab | 32 | | Layout nodes per tab | 63 | | Running terminals | 16 | | Agent sessions | 128 | | Live provider runtimes | 8 | Live provider runtimes are the provider CLIs the machine keeps warm. Idle runtimes are evicted first and resume when an agent needs them again. At the tab limit, the **New tab** button disables. At the terminal limit, close a terminal or wait for one to exit. ## Keep track of it all - **Agents** lists every running agent with a status badge and an unread dot for updates you have not seen. - **Notifications** alert you when an agent finishes or needs input, on this device. - **Previews** lists the dev servers that are serving pages. - **Search** jumps to any workspace, tab, agent, or command on the machine. - The **Resources** page shows what the machine is running and how much CPU and memory it uses. ## A way to work A common arrangement for one feature: 1. Open a workspace and start an agent in the first pane to implement the change. 2. Split the tab and start a second agent to investigate a related bug. Keep it in the same tab to compare, or give it its own tab to keep the first tab focused. 3. Open a terminal for the test command and rerun it as the first agent commits. 4. Open a preview to use the app while the tests run. Unread dots and notifications tell you which session moved last, so you can move from one to the next without checking each pane. ## Related - [Agents overview](/agents/overview) - [Terminals](/capabilities/terminals) - [Previews and dev servers](/capabilities/previews) - [Schedules and automations](/agents/schedules) --- # Search Search is one finder for everything on the selected machine: workspaces, tabs, agents, terminals, and commands. It is built for navigation, not for reading the contents of your work. ## Open Search - Select **Search** in the sidebar. - Press Ctrl+Shift+K. - Press Ctrl+K, or Cmd+K on macOS, when a terminal is not focused. Search opens as a dialog on desktop. Type to filter, then choose a result to go there. Escape, the close button, and the backdrop close it and return you to where you started. Reopening starts with an empty query and the **All** category. ## What it searches Search is machine-scoped and covers names and paths: | Category | Matches | | -------------- | --------------------------------------------------------------------------------------------------------- | | **Workspaces** | Workspace names and their directories | | **Tabs** | Tab names, workspace, pane profile, working directory, and the attached agent's name, provider, and model | | **Commands** | Navigation actions, every enabled shortcut, theme switching, **Reconnect to machine**, and **Sign out** | | **All** | Everything above, with exact names ranked first | Every word you type must match, in any order. Case and accents are ignored. Equal matches favor the active workspace. Duplicate workspace names show their paths so the destinations are distinguishable, and each pane in a split is its own destination. Commands are secondary. Use the **Commands** category, or type an action such as Settings or Shortcuts in **All**. Only commands that are available right now appear, so split and focus commands stay off phones. Thirty results appear at a time. Use **Show more results** to see the rest. Results come from the selected machine's live metadata, so renamed and removed tabs disappear without a refresh. ## What it does not search - Messages in agent conversations - File contents - Other machines - Directories beyond the loaded workspaces The dialog states that it searches names and paths, not messages or file contents. There is no full-text search across chats or files. Switching machines or accounts clears the query, and each machine keeps its own results. ## On mobile The same finder opens as a bottom drawer, leaving the sidebar visible behind it until you choose a result. Choosing a result on a phone focuses that pane locally and does not change the layout on your other devices. ## Related - [The workspace](/workspace/overview) - [Keyboard shortcuts](/workspace/shortcuts) - [Running work in parallel](/capabilities/parallel) - [Resources and processes](/machines/resources) --- # The workspace A workspace is a folder you open or clone on a machine. It holds the tabs, agents, terminals, and files for that folder. Everything you do in Concors happens inside a workspace on one machine at a time. ## The layout The workspace uses four regions: - **Sidebar.** The machine switcher at the top, **Search**, then **Workspaces**, **Agents**, and **Previews**, with the account menu at the bottom. - **Tab strip.** The open tabs in the current workspace, including file tabs. - **Panes.** The content of the selected tab, split as you arrange it. - **Resource bar.** The bottom bar with the machine's CPU and RAM. ## Create or open a workspace Open the plus menu next to **Workspaces** and choose one of: | Action | What happens | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **New workspace** | Opens a terminal in the machine user's home folder. The workspace follows the terminal's current folder. | | **Open folder…** | Browses folders on the machine, with filtering and an optional hidden-folder toggle. The folder name becomes the workspace name. Opening a folder that is already open focuses its existing workspace. | | **Clone repository…** | Clones a Git repository and opens it. See [Git and GitHub](/capabilities/git). | A **New workspace** starts in the home folder and takes its identity from where the terminal goes. Inside a Git checkout, the workspace uses the checkout root, so moving into a subfolder does not rename it. Closing a workspace removes it from every connected device. Files and running sessions are kept; only the workspace entry and its layout are removed. ## Tabs A tab holds one or more panes. - **New tab** opens the profile picker: Terminal, Agent, and your saved terminal profiles. - Double-click a tab name, or press F2, to rename it. - Drag a tab to reorder it. - Select the **X** on a tab to close it. Closing a tab closes its panes; sessions keep running on the machine. - File tabs appear after session tabs and show a dot when the file has unsaved changes. Up to 32 tabs fit in one workspace. At the limit, the **New tab** button disables. ## Panes A pane holds an agent conversation or a terminal. - Use the **Pane actions** menu to split horizontally or vertically. - Drag a pane header onto a drop zone to move the pane and re-split the tab. - Drag the separator to resize a split, or focus it and use the arrow keys. Splits stay within usable bounds. - Focus moves by geometry; there is no wrapping from one edge to the other. A tab holds up to 32 panes and 63 layout nodes. Closing the last pane closes its tab. ## Sidebar and files The sidebar collapses to a 44 px rail of icons. Rows show tooltips on hover or keyboard focus, so you can keep the rail narrow and still find a workspace or agent. The file sidebar docks beside the panes on wide windows and floats over them below 1024 px. Its width is adjustable and persists between sessions. ## Sync and disconnects Workspace state syncs across the clients connected to the same machine. Rename a tab on your desktop and your phone shows the new name. When the connection drops, the last saved state stays visible and editing is disabled until a fresh state arrives. The machine publishes changes even while the client that made them is disconnected. > **Note.** Closing the client does not stop sessions. Reopen it and the layout returns with the same agents and terminals running. ## Related - [Themes and appearance](/workspace/themes) - [Notifications and sounds](/workspace/notifications) - [Running work in parallel](/capabilities/parallel) - [Search](/capabilities/search) --- # Themes and appearance Appearance settings control how Concors looks on this device. Open **Settings** and choose **Appearance** under Personal. Changes apply immediately and do not affect what runs on the machine. ## Interface theme **Interface theme** controls light and dark mode: | Option | Behavior | | ---------- | ----------------------------------------------------------------------- | | **Light** | Always uses the light variant. | | **Dark** | Always uses the dark variant. | | **System** | Follows the operating system and changes live when the system switches. | ## Color theme **Color theme** offers seven bundled palettes. Each one includes a light and a dark variant: - **Concors** (the default) - **Cobalt** - **Dusk** - **Forest** - **Rose** - **Sand** - **Ocean** Choosing a palette recolors workspace surfaces, sidebars, menus, agent chats, terminals, and the file editor right away. Terminal ANSI output and editor syntax colors follow the palette too. Running terminals and agents are not restarted, and open documents keep their contents, cursors, and undo history. Programs that set their own 256-color, true-color, or application colors keep those colors. The selection belongs to this device. Your other devices keep their own appearance. ## Corner style **Corner style** shapes frames, tabs, buttons, menus, and agent inputs: - **Square** - **Slightly rounded** (the default) - **Rounded** ## Custom themes **Custom themes** shows the theme directory on the selected machine, usually `~/.concors/themes`. A theme is one JSON file. Choose **Copy theme instructions** to put a template and guidance on your clipboard, then paste it into an agent conversation and describe the theme you want. A theme file looks like this: ```json { "version": 1, "id": "my-sunset", "name": "My sunset", "description": "Warm amber accents", "extends": "sand", "light": { "accent": "#984522" }, "dark": { "accent": "#ffc092", "terminal": { "red": "#f39c8b", "blue": "#a4bbff" } } } ``` - `version` is `1`. - `id` is a unique lowercase slug. - `name` is the display name, and `description` is optional. - `extends` names one of the seven built-in palettes. Colors you do not set inherit from it. - `light` and `dark` are optional overrides. Values use `#RRGGBB` or `#RRGGBBAA`. - `terminal` is an optional block of ANSI colors. Choose **Refresh themes** to reload immediately. Connected clients also pick up changes within a few seconds, and a selected theme updates in place. > **Requires a recent machine runtime.** If a control is missing, update the runtime on that machine. ## Limits and recovery | Limit | Value | | ----------------------- | ----------- | | Theme files per machine | 64 | | File size | 32 KiB | | Content | Colors only | Themes cannot load scripts or remote resources. A malformed file shows an error in Appearance and the last valid version stays in use, and it never prevents the app from starting. Deleting the selected custom theme returns the client to **Concors**. ## Related - [The workspace](/workspace/overview) - [Settings reference](/workspace/settings) - [Keyboard shortcuts](/workspace/shortcuts) --- # Keyboard shortcuts The Shortcuts page lists every workspace command and its default bindings, and lets you change them. Open **Settings**, then **Shortcuts** under Personal, or press `Ctrl+Shift+/`. Searching for "Shortcuts" from workspace search opens the same page. ## Default bindings | Action | Shortcut | | -------------------------------------------- | --------------------------------------- | | Search workspaces, agents, and tabs | `Ctrl+Shift+K` | | New workspace | `Ctrl+Shift+N` | | New tab | `Ctrl+Shift+T`, then Enter | | Previous tab | `Ctrl+Shift+T`, then Left | | Next tab | `Ctrl+Shift+T`, then Right | | New pane beside the current pane | `Ctrl+Shift+P`, then Enter | | New pane to the left, right, above, or below | `Ctrl+Shift+P`, then the matching arrow | | Focus the neighboring pane | `Ctrl+Shift+Arrow` | | Close pane | `Ctrl+Shift+P`, then Backspace | | Close tab | `Ctrl+Shift+T`, then Backspace | | Settings | `Ctrl+Shift+,` | | Shortcuts | `Ctrl+Shift+/` | | Rename tab | `F2` | | Move tab left or right | `Alt+Shift+Left` or `Alt+Shift+Right` | Outside terminals, `Ctrl+K`, or `Cmd+K` on macOS, is a search alias. In the desktop app, `Ctrl+Shift+Tab` and `Ctrl+Tab` also move between tabs. ## Two-step sequences A shortcut such as `Ctrl+Shift+P`, then an arrow, is a sequence. Press and release the first combination, then press the second key. An action picker appears after the first step and shows the available choices. Escape, clicking outside, or leaving the window cancels the sequence, and an unrecognized second key is not sent to the terminal or chat. ## Customize shortcuts 1. Choose **Edit** beside a command. 2. Record a key combination, or choose **Type combinations instead** and enter one such as `Ctrl+Alt+S` or `F6`. 3. Add a second step if you want a sequence. 4. Choose a scope. 5. Choose **Save shortcuts**. You can add up to four alternative bindings per command. The scopes are the whole app, outside terminals, only the native desktop app, and while a tab title is focused. The first step must include Control, Command, Alt, or a function key, and the second step can be a bare key. Escape is reserved for canceling. A conflicting binding must be reassigned explicitly. Saving removes the conflicting alternatives from the other commands, and removing every binding disables that command's shortcuts. **Use defaults** restores one command, and **Restore all defaults** restores every command. Preferences apply to this device, not the machine or the workspace. If a browser or the operating system reserves a combination, it may handle the key before Concors receives it. > **Requires a recent machine runtime.** New panes to the left and above need a current runtime. If a control is missing, update the runtime on that machine. ## Terminal clipboard Select terminal output, then copy and paste with any of these: | Action | Keys | | ------ | ------------------------------------------------------- | | Copy | `Ctrl+Shift+C`, `Ctrl+Insert`, or `Command+C` on macOS | | Paste | `Ctrl+Shift+V`, `Shift+Insert`, or `Command+V` on macOS | Plain `Ctrl+C` still interrupts the running command, and plain `Ctrl+V` keeps its shell behavior. The clipboard shortcuts are handled locally and never sent to the shell. Closing a pane or a tab never stops its sessions. The terminal or agent keeps running on the machine. ## Related - [The workspace](/workspace/overview) - [Settings reference](/workspace/settings) - [Themes and appearance](/workspace/themes) - [Terminals](/capabilities/terminals) --- # Notifications and sounds Concors tells you when an agent finishes or needs input. Open **Settings**, then **Notifications** under Personal. The **Agent notifications** section states: "Preferences apply to this device. Unread indicators sync across devices." The two controls are independent, and both are off by default. ## Sound Turn on **Sound** to hear a distinct sound for completion and for a request for input. Use **Test completion sound** and **Test input sound** to preview each one. Browsers require a user gesture before audio can play, and the test buttons enable it. ## Desktop notifications Turn on **Desktop notifications** to receive an operating system notification when an agent you are not viewing finishes or needs input. Permission is requested only when you turn the option on. Use **Test desktop notification** to check delivery. If the browser does not support desktop notifications, the page says so. If permission is blocked, allow notifications in your browser or system settings, then try again. ## Delivery rules | Situation | What happens | | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | Completion in the conversation you are viewing | Silent | | A request for input in the focused conversation | Plays its sound | | An event in the background | Waits briefly, then rechecks whether you are still away and whether the agent still needs you | | You read the conversation elsewhere | The queued alert is cancelled | Notifications appear as cards in the bottom-right corner and, when enabled, as operating system notifications. Clicking an in-app card or an operating system notification opens the agent's conversation. If the conversation moved to another machine in the meantime, the old click target no longer applies. Dismissing a card closes its system notification but does not mark the conversation read. Focus modes, system notification settings, and browser background throttling can affect delivery. ## Unread indicators Unread dots appear in the Agents list. They sync across devices, so reading a conversation on your phone clears the dot on your desktop. Reconnecting restores unread badges without replaying old alerts. Notifications reflect live transitions while the client is running. They are not an offline inbox: an event that happens while no client is connected does not produce a notification later. ## On phones In-app notifications work on iOS and Android. Push delivery is not available yet. > **Preview.** The mobile client can register for push, but the delivery service is still being built. In-app notifications work today. ## Related - [Settings reference](/workspace/settings) - [Approvals and control](/agents/approvals) - [Concors on your phone](/start/mobile) - [Keyboard shortcuts](/workspace/shortcuts) --- # Settings reference Settings holds the account, workspace, and developer options for Concors. Open it in any of these ways: - The account menu at the bottom of the sidebar, then **Settings**. - `Ctrl+Shift+,`. - Workspace search. - The settings drawer on mobile. The Settings sidebar groups pages under **Personal**, **Workspace**, and **Developer**, with **Back to app** at the top. The account menu keeps **Settings** reachable even if you change or disable its shortcut. ## Personal | Page | What it holds | | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | **Account** | Your profile, email, GitHub integration, active organization, VPS subscriptions, session expiry, and **Sign out**. | | **Appearance** | **Interface theme**, **Color theme**, **Corner style**, and **Custom themes**. | | **Shortcuts** | Every workspace command, its bindings, and the editor for changing them. | | **Notifications** | Sound and desktop notification preferences for this device. | ## Workspace | Page | What it holds | | ------------- | ---------------------------------------------------------------------------- | | **Machines** | **This computer**, your cloud machines, **New machine**, and resource usage. | | **Providers** | Install, enable, and configure agent CLIs on the selected machine. | | **Terminals** | Saved terminal profiles. | | **Billing** | Payment method, machine prices, and invoices. | | **SSH keys** | Public keys installed on your organization's machines. | ## Developer | Page | What it holds | | ------------ | --------------------------------------------------------------------------------------------- | | **Advanced** | Connection status and endpoint, runtime version, client version, and the Concors API address. | ## What each scope covers | Scope | Settings | | ---------------------------- | -------------------------------------------------------------------------------------- | | This device | **Appearance**, **Shortcuts**, and **Notifications** | | The selected machine | **Providers**, **Terminals**, and the **Custom themes** directory | | Your account or organization | **Machines**, **Billing**, **SSH keys**, GitHub integration, and **VPS subscriptions** | A device-scoped choice follows you across machines but not across devices. Machine-scoped settings belong to the machine and are shared by every client connected to it. Account and organization settings follow the signed-in account. When you switch machines, machine-scoped pages follow the selected machine, and device-scoped pages do not change. ## On mobile Mobile shows the same drawer with the same three groups. Billing and purchasing are not available there, and **Add machine** explains that machines are created in the desktop app. Providers and terminal profiles on the selected machine work the same way as on desktop. ## Related - [Themes and appearance](/workspace/themes) - [Keyboard shortcuts](/workspace/shortcuts) - [Notifications and sounds](/workspace/notifications) - [Machine subscriptions](/billing/subscriptions) --- # Machine subscriptions Each Concors Cloud machine is a separate monthly subscription, charged in advance to your organization's card. A subscription starts when you confirm a new machine and renews each month until you cancel it. ## Where subscriptions appear Open **Settings**, then **Account**, and find **VPS subscriptions**. The list shows each machine with its price, its status, and its renewal or end date. Choose **Refresh subscriptions** to update the list. A machine can show one of these statuses: **Active**, **Trial**, **Payment overdue**, **Unpaid**, **Payment pending**, **Paused**, or **Ends at period end**. A cancelled machine shows **Ends at period end** with the date it stops running. ## Billing settings Open **Settings**, then **Billing** under Workspace. - **Payment method** shows the card brand, the last four digits, and the expiry date. A **Payment failed** badge appears when a charge needs attention. - **Add a card** or **Add another card** opens Stripe's hosted page in your browser. The app verifies the result when you return. - **Manage billing** opens the Stripe portal, where you can update cards and billing details. - **Invoices** lists each charge with its date, number, status, and amount. Choose **Open invoice** to view one. ## Creating a machine The **New machine** wizard asks for a name, region, size, and tools, then shows the monthly price in the order summary. You add or choose a card on the review step. The first month is charged when you confirm with **Pay & deploy**. Navigating the wizard or adding a card never creates or charges a machine on its own. Prices depend on the size and region you choose. ## Canceling Choose **Cancel** on a machine card to cancel its subscription. The machine keeps running until the end of the paid period, future charges stop, and the current month is not refunded. Choose **Keep machine** to undo a cancellation before the period ends. ## What you are not charged for There are no usage-based charges, spending caps, or automatic shutdowns. A machine that uses more CPU or RAM is not billed more, and Concors does not stop it to control cost. Provider subscriptions and token charges stay with your provider, not Concors. See [Usage and limits](/billing/usage). ## Servers without billing If billing is not configured for your organization's server, the **Billing** page says "This Concors server runs without billing; machines are not charged." > **Preview.** Concors is in preview. Stripe can be in test mode while machine provisioning still happens for real. ## Related - [Concors Cloud machines](/machines/cloud) - [Usage and limits](/billing/usage) - [Settings reference](/workspace/settings) --- # Usage and limits Concors shows three kinds of usage. Two are visible today, and one is in progress. ## Context window Each agent conversation has a context window. A ring beside the composer shows how much of it the conversation has used. Open the ring to see the used and limit token counts plus the cumulative tokens for the conversation. Before the provider reports usage, it shows "Usage will appear after the agent reports it." The context window belongs to the conversation, not the machine. ## Machine resources The bottom status bar shows the selected machine's CPU percentage and RAM used over total. Readings at 90% or more are labeled **High usage**. This is visibility only. Concors does not enforce CPU or memory limits, and the indicator is not a spending or safety control. A machine can run at full load for as long as the work takes. For a per-process view, open **Resources** from the computer menu or the indicator. See [Resources and processes](/machines/resources). ## Provider plan usage Provider plan usage meters, such as the plan windows for Claude or Codex, are in progress and not available yet. > **Preview.** Plan usage meters are still being built. Use the context window ring and the machine indicator for now. ## Runtime limits | Resource | Limit | | -------------------------------- | ---------------- | | Saved agent sessions per machine | 128 | | Live provider runtimes at once | 8 | | Queued messages per conversation | 20 | | Attachments per message | 3, at 1 MiB each | | Running terminal sessions | 16 | | Terminal emulator instances | 32 | | Retained terminal sessions | 256 | | Tabs per workspace | 32 | | Panes per tab | 32 | | Workspaces per machine | 64 | | Open file tabs | 32 | | Text file size | 1 MiB | | Directory entries listed | 2,000 | | Schedules per machine | 64 | | Recent schedule runs kept | 20 | | Custom themes per machine | 64 | Idle provider runtimes are evicted when the limit is reached and resume later. Retained terminal sessions keep their output after the pane closes. Closing a pane or a tab never stops a session. ## What Concors does not bill Provider subscriptions and token charges stay with your provider, not Concors. Concors bills only machine subscriptions, and those are a flat monthly price with no usage component. See [Machine subscriptions](/billing/subscriptions). ## Related - [Resources and processes](/machines/resources) - [Machine subscriptions](/billing/subscriptions) - [What is an agent?](/agents/overview) - [Settings reference](/workspace/settings) --- # Troubleshooting Most problems in Concors come from a machine that is not reachable, a runtime that needs an update, or a session that needs a retry. Find the symptom below, follow the step, and check the result. ## Startup ### The splash stays longer than expected The splash loads the account session, the saved machine, and the first workspace snapshot. After about 12 seconds it offers **Retry** and, once you are signed in, **Connection settings**. Select **Retry** first. If the splash returns, check the machine address in **Connection settings** or choose another machine. A stopped or asleep machine cannot send a snapshot. ### This desktop build is missing its local runtime The installed package is incomplete. Install a complete Concors desktop package and open it again. ### The first connection is slow The first connection waits for the machine's first workspace snapshot. A new [Concors Cloud](/machines/cloud) machine may still be installing. Wait, then select **Retry** if it is offered. ## Machines ### A cloud machine shows Offline or Provisioning **Provisioning** (or a step such as **Installing**) means the machine is still being created; wait and refresh its card in **Settings → Machines**. **Offline** means it cannot be reached. Check that it stays on, since a stopped or sleeping machine ends its sessions, then reconnect. ### Access revoked Sign in again on this device. If the message returns, check that you are still a member of the organization that owns the machine. ### Update daemon messages A message such as **Update daemon for usage** or **Update the daemon on this machine to use schedules** means the machine runs an older runtime than the client. Update the runtime on that machine, then reconnect. Older runtimes keep the features they already support. > **Requires a recent machine runtime.** If a control is missing, update the runtime on that machine. ### Connection lost keeps the last saved workspace Concors keeps showing the last saved workspace and disables edits until a fresh state arrives. Check the machine and your network, then reconnect. Sessions keep running on the machine while you are away. ## Agents ### An agent pane fails to start The pane shows the error and a **Retry** button. Select it. If it fails again, confirm the provider is installed and signed in on the machine. ### The daemon restarted The message says the conversation can be continued without resending the previous prompt. The interrupted turn does not resume on its own. Send a new message to continue; the history stays. ### The queue is paused A stop, a turn failure, or a runtime restart pauses follow-ups. Select **Resume queue** in the queue panel to deliver the waiting messages. ### Delivery could not be confirmed Select **Retry same message**. Concors does not resend automatically, so do this only when you mean to send again. ### Update this machine's daemon to browse saved sessions The resume picker needs a recent runtime. Update the runtime on that machine. Until then, use the provider CLI's own resume command in a terminal. ### A provider is missing Open **Settings → Providers**, choose **Check provider installations**, then install or enable it. See [Supported agents](/agents/providers). ### A provider is not signed in Complete the account prompt above the composer, or sign in through the provider's CLI in a terminal on the machine. See [Agent accounts](/agents/accounts). ## Terminals ### Reconnecting… The client is reattaching, for example after a runtime restart. The last screen stays visible and the scroll position is kept where possible. Wait for the banner to clear. ### Session ended or Session failed **Session ended** means the process exited. **Session failed** offers **Start new session**; select it to launch a fresh process. ### A shell recovery lost its variables and jobs The shell reopens in the workspace directory. Variables, jobs, and commands are not replayed; set them up again in the recovered shell. ### Codex and Claude recover through their resume commands Codex opens `codex resume` and Claude Code opens `claude --resume`. Select the saved conversation in the provider's picker; Concors does not guess. ### Explicitly stopped sessions stay stopped A session ended with **Stop** is not relaunched during recovery. Create a new tab or pane to start it again. ## Files ### Update or reconnect the machine to open project files The file panel needs a live connection and a recent runtime. Reconnect and open **Project files** again. If the message returns, update the runtime on that machine. ### This file changed on the machine Another process or client changed the file while you were editing, so your draft was kept. **Compare with disk** shows the differences, **Use disk version** replaces your draft with the machine's text, and **Keep my draft** keeps your text so you can decide what to save. ### This file link is outside the current project Agent file links open only files inside the current workspace. A path outside it is refused; open the file from a terminal instead. ### No rename, delete, binary, or image previews The editor cannot rename or delete files, and it does not preview binaries or images. Use a terminal on the machine. ## Search and notifications ### Search only matches names and paths Search is a navigation finder; it does not read message text or file contents. To find text, use find in the editor, ask an agent, or run `grep` in a terminal. ### Notifications are off by default Enable them in [Notifications and sounds](/workspace/notifications). Desktop notifications also need browser or operating system permission, which is requested after you turn them on. ### Sounds need one interaction Browsers block audio until you interact with the page. Select a sound test in settings once after loading. ## Dictation ### Microphone access denied Grant microphone access in the browser or system settings, then select the microphone again. ### No speech detected Recording ends without adding text. Check the selected microphone and try again; nothing is sent. ### Unsupported browser The browser has no speech recognition, so the microphone button is disabled. Use the keyboard's dictation or type the message. ## Mobile ### Session expired or could not verify Retry once, then check the connection. If the message returns, sign in again; it can also mean the machine is offline or access was revoked. ### Access revoked Automatic retries stop. Sign in again on the phone. See [Sign in and accounts](/start/access). ### Direct desktop connection needs Tailscale Connecting a phone directly to a desktop runtime needs a private network such as Tailscale. Without it, use a [Concors Cloud](/machines/cloud) machine. ### Push notifications are not delivered yet The app can register for push, but the delivery service is not finished. In-app notifications work, so open the app to see finished and needs-input updates. See [Concors on your phone](/start/mobile). ## GitHub and pull requests ### Sign in to GitHub on the machine Run `gh auth login` on the machine, then refresh. Concors never prompts for a token in the client. ### Merge and close buttons are missing They appear only when the machine's GitHub account may take that action. Drafts, conflicts, and read-only access hide or disable them. ### The pull request list is empty The workspace may have no GitHub remote, or the account cannot see its repositories. Check the repository's remotes and the machine's GitHub access. See [Pull requests](/capabilities/pull-requests). If a symptom is not covered here, or the steps do not fix it, see [Get help](/help/support) for what to include. ## Related - [Get help](/help/support) - [How machines work](/machines/overview) - [Approvals and control](/agents/approvals) - [Files and the editor](/capabilities/files) --- # Get help Concors is in preview, and support happens directly in the Concors issue tracker. Check [Troubleshooting](/help/troubleshooting) for your symptom first; many problems have a known step. This page covers where to report a problem, what to include, and how to handle a security issue. ## Before you file Work through these steps and include the results in the issue: 1. Reconnect to the machine, or switch to another machine and back. 2. Update the runtime on the machine if a control or setting described in these docs is missing. 3. Reproduce the problem once more and note the exact steps and what happened. ## Report a bug or request a feature Open the issue tracker at https://github.com/hologramxyz/concors/issues. It is public, and the people building Concors read it. Search the open issues before filing so an existing report can be confirmed instead of duplicated. ## What to include - What you expected to happen, and what happened instead. - The exact message or error text, copied as it appears. - Whether the problem happens on **This computer** or on a cloud machine, and which machine. - The versions from **Settings → Advanced**: client version, runtime version, and connection status. A screenshot or a short recording helps when the problem is visual. Attach it to the issue. ## Make the report small Reproduce with the smallest workspace you can: one folder, one agent or terminal pane, and no unrelated tabs. A small reproduction is much easier to confirm and fix than a full workspace. Include the steps that lead to the problem, in order, and the command or prompt that triggers it when there is one. If a docs page describes a control you cannot find, name the page in the issue. It may depend on a machine that runs an older runtime. ## Keep private data out The tracker is public. Remove tokens, keys, private repository names, file contents, and anything else you would not post publicly. If the problem cannot be shown without private data, describe it and redact the details. ## Security issues Do not open a public issue for a security problem. Report it privately using the process in the repository's security policy. Include the same details you would for a bug, plus anything that shows the impact. ## Status There is no public status page yet. When a machine seems down, open **Settings → Machines** and check its state: an offline or provisioning machine is usually visible there, along with any setup error and, for development tools, **Retry setup**. ## Related - [Troubleshooting](/help/troubleshooting) - [Settings reference](/workspace/settings) - [Glossary](/help/glossary) - [Use the docs with an agent](/help/agents) --- # Glossary This page defines the words Concors uses in the app and in these docs. ## Terms | Term | Meaning | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent | A coding CLI such as Codex, Claude Code, OpenCode, Pi, GitHub Copilot, or an ACP preset, driven from a chat pane in Concors. It runs on a machine with the provider account configured there. | | Agent account | The provider sign-in an agent CLI uses on a machine. It is separate from your Concors account and is stored by the CLI itself. | | ACP (Agent Client Protocol) | An open protocol for driving agent CLIs. Concors uses it for opt-in presets such as Cursor and Gemini CLI, which you enable in **Settings → Providers**. | | Approval | A provider's request for permission before a sensitive tool call. It appears as a card in the agent pane, and any connected device can answer it. | | Attention | The durable unread state behind the done and needs-input notifications. It survives restarts and clears when you view the conversation. | | Client | The Concors app you look at: the desktop app, a browser window, or the mobile app. It shows and controls work that runs on a machine. | | Concors account | The account you sign in with, using email and password or GitHub. It covers the client, machines, and billing, and it is not a provider account. | | Concors Cloud | Managed VPS machines that Concors provisions, connects, and bills monthly for your organization. | | Context window | How much conversation and tool output a model can consider at once. The context meter in an agent pane shows how much of it the current conversation uses. | | Concors runtime | The process on a machine that owns files, terminals, sessions, and provider credentials. The app calls it the daemon in a few places, and messages about older machines use that word. | | File tab | A tab that shows a file from the workspace. Drafts belong to the file, and closing a dirty tab asks before discarding them. | | Machine | Anything running the Concors runtime: **This computer**, a self-managed machine, or a Concors Cloud machine. | | MCP | Model Context Protocol, a standard way for agents to call external tools and data sources. Providers load the MCP servers configured for them. | | Pane | A split inside a tab that holds one agent chat or one terminal. | | Preview | A dev server the runtime discovered in your workspace, with a reachable address. Previews appear in the sidebar. | | Provider | The backend that runs an agent, for example Codex. Providers are installed and enabled per machine. | | Pull request | A GitHub request to merge a branch. Concors lists pull requests for a workspace's repositories and can merge, close, or comment when the machine's GitHub account has permission. | | Queue | Follow-up messages you send while an agent is working. They wait on the machine and run when the turn finishes. | | Resume | Bringing a saved provider conversation back into an empty agent pane. Concors loads the provider's history and does not send a prompt. | | Schedule | A saved prompt that runs on a cadence on a machine. | | Session | A running agent conversation or terminal process. Sessions keep running when panes and clients close. | | Tab | The top-level container in a workspace, holding one or more panes. | | Terminal profile | A saved command for a terminal, such as Terminal, Codex, or a custom profile. Profiles are saved on the machine and synced to connected clients. | | This computer | The machine running the desktop app, using the Concors runtime bundled with it. | | Turn | One prompt and the agent's work while handling it. A turn ends when the agent is done or when you interrupt it. | | Unread indicator | The dot on an agent row that marks a finished or needs-input update you have not seen. | | Workspace | The folder you open, create, or clone on a machine. It holds the tabs, panes, and files for that folder. | ## Related - [How machines work](/machines/overview) - [The workspace](/workspace/overview) - [What is an agent?](/agents/overview) - [Troubleshooting](/help/troubleshooting) --- # Use the docs with an agent Every page in these docs is available as Markdown, so an agent can read the same instructions you do. You can paste a page into a conversation, ask an agent to fetch one, or let an agent choose pages from the documentation index. ## Copy or open a page Each page has two controls: - **Copy page** copies the page as Markdown, ready to paste into an agent conversation. - **Markdown** opens the raw page at a stable path under `/content/`. The path does not change when the page is edited, so an agent can fetch it later. The raw page keeps its headings, tables, code blocks, and links, so an agent gets the same structure the site renders. ## The index and the full bundle - `/llms.txt` is a linked index of every page, with its title and description. - `/llms-full.txt` holds every page in one file. Both files come from the same sources as the pages, so they stay in step with the site. Point an agent at the index when it should choose pages for itself, and at the bundle when it needs all of the documentation at once. ## Ways to use a page with an agent 1. **Paste it.** Select **Copy page**, then paste the text into the conversation with your request. This works when the agent cannot reach the network. 2. **Ask an agent to fetch it.** In a Concors terminal, tell the agent to read the Markdown path before it follows the page. This works well for procedures that must be followed exactly, such as recovery steps. 3. **Point it at the index.** Give the agent `/llms.txt` and a task. It can choose the pages it needs and fetch each one by its path. ## Example prompt ```text Read the Terminals page in the Concors docs, then start a terminal in the api workspace and run the test suite. ``` Keep the request in the same message, so the agent applies the page to your task instead of only summarizing it. ## Preview notes These docs describe the preview release. The client and the machine runtime update separately, so an agent working from a page may see different labels on a machine that runs an older runtime. When a page and the app disagree, trust the app. > **Requires a recent machine runtime.** If a control described on a page is missing in the app, update the runtime on that machine. ## Related - [Troubleshooting](/help/troubleshooting) - [Get help](/help/support) - [Glossary](/help/glossary) ---