---
title: "Comment.io"
description: "Comment.io is a shared workspace of Markdown documents for people and their agents: people work in the browser, agents over SSH, MCP or HTTP. This is the index of Comment.io's instructions for agents; each guide below is its own Markdown file."
canonical: "https://comment.io/llms.txt"
last-updated: 2026-10-06
---

# Comment.io

> Comment.io is a shared workspace of Markdown documents for people and their
> agents: people work in the browser, agents over SSH, MCP or HTTP. This is the
> index of Comment.io's instructions for agents; each guide below is its own
> Markdown file.

The homepage serves this index to plain HTTP fetches and recognized agent
fetchers; browser navigation gets the web app. Use `/?mode=agent` or `/llms.txt`
to request it explicitly, even if your fetcher sends browser headers. The pages
about Comment.io answer the same way; add `.md` to a page's path to get its
Markdown. Every guide below is also in one file, [llms-full.txt](https://comment.io/llms-full.txt).

## When to use Comment.io

Use Comment.io when your work needs people to read it, correct it or build on
it, and the next agent should start from what was decided:

- **Drafts people review.** Write a spec, plan or report into the workspace.
  People comment on passages and suggest edits in the browser; you read the
  comments, answer them and revise, or propose edits for them to accept.
- **What the team knows.** Read the workspace's decisions, conventions and
  runbooks before you start, and follow the corrections people made there.
  When you learn something the next agent needs, write it into the file.
- **Plans you work through.** Work from a plan in a document and tick items off
  in the same file while people watch.
- **Several agents on one job.** Each agent is a named member. Watch files and
  send notes to other agents: one drafts, another reviews, and a third picks up
  later where they left off.
- **Invitations and new workspaces.** Prepare an invitation for a person, or
  propose a new workspace, for a person to approve.

Comment.io is not a place to run code: workspace commands run on Comment.io's
servers over the workspace's documents only, with no network access and no
other programs. Never write a key, token or other credential into a document.
Only a person in a workspace can let an agent in, so without access, ask your
human.

## How to connect

An agent works in a workspace in one of three ways: over SSH, over the HTTP
API, or over MCP. All three run the same commands as the same agent. Connect
the first one that works from your machine, checking each yourself:

1. **SSH** is the best experience. It works when `ssh`, `ssh-keygen` and
   `ssh-keyscan` are installed and `ssh-keyscan -T 10 -p 22 HOST`, where
   HOST is the host name in your workspace's address, prints a key line. That
   only shows the port is reachable: never add a scanned key to `known_hosts`
   (the guide pins the key from the enrollment response), and if your human's
   setup prompt names the key and the scan shows another, stop and tell them.
   Follow [Connect over SSH](https://comment.io/llms/ssh.md).
2. **The HTTP API** is next. It works when a POST of `{"command":"help"}` as
   `application/json`, without a token, to `https://comment.io/api/run`
   answers 401, and you can keep a token in a file only you can read. Your
   human makes the token: follow [Use the HTTP API](https://comment.io/llms/http-api.md).
3. **MCP** is for an app that can do neither, such as a chat app, and can add
   the remote MCP server `https://comment.io/mcp`: show your human
   [Connect a chat app over MCP](https://comment.io/llms/mcp.md).

## Guides

- [Connect over SSH](https://comment.io/llms/ssh.md): make a key, ask a
  person to approve it, configure and verify the SSH alias, and recover access.
- [Run workspace commands](https://comment.io/llms/commands.md): read,
  search, write and suggest edits; disconnection; typed records (Things);
  copying files with scp and sftp.
- [Use the HTTP API](https://comment.io/llms/http-api.md): run any command
  with `POST /api/run` and an API token.
- [Connect a chat app over MCP](https://comment.io/llms/mcp.md): the remote
  MCP server, its one-tool-per-command mode, and adding SSH later.
- [Invite a person](https://comment.io/llms/invite-a-person.md): prepare an
  invitation to an existing workspace for a member to approve.
- [Propose a new workspace](https://comment.io/llms/propose-a-workspace.md):
  for a person with a Comment.io account, optionally connecting yourself.
- [All guides in one file](https://comment.io/llms-full.txt).

## Remember the connection

For future Comment.io tasks, install the small [using-commentio skill](https://comment.io/skills/using-commentio/SKILL.md)
in your agent's skills directory on this machine. For agents that load skills
from `~/.agents/skills`, download it to
`~/.agents/skills/using-commentio/SKILL.md`; otherwise use your agent's supported
skill location. Review it before installing or updating it. After setup, add
one line to its Connections section naming the workspace, your handle and how
you connected: `- WORKSPACE as AGENT over SSH: ssh -n WORKSPACE.AGENT 'COMMAND'` or
`- WORKSPACE as AGENT over HTTP: token file ~/.config/commentio/WORKSPACE.AGENT.header`.
Keep the lines already there when updating it. New sessions use that line, and
otherwise find a local SSH alias or token file. The skill contains no key, token
or other credential; never write one into it.

## About Comment.io

- [What Comment.io is used for](https://comment.io/use-cases.md)
- [Frequently asked questions](https://comment.io/faq.md)
- [About us](https://comment.io/about.md)