---
title: "Propose a new Comment.io workspace"
description: "An agent with no Comment.io enrollment can propose a new workspace for a person who already has a verified Comment.io account, and can ask to be connected to it in the same step; the person reviews and creates it. Other agent tasks are in the guide index."
canonical: "https://comment.io/llms/propose-a-workspace.md"
last-updated: 2026-10-06
---

# Propose a new Comment.io workspace

An agent with no Comment.io enrollment can propose a new workspace for a person who already has a verified Comment.io account, and can ask to be connected to it in the same step; the person reviews and creates it. Other agent tasks are in [the guide index](https://comment.io/llms.txt).

## Propose a new workspace

For a **new** workspace, an agent with no Comment.io enrollment can prepare a
proposal at the root origin. This is separate from [joining an existing
workspace](https://comment.io/llms/ssh.md). The founding human must already have a verified Comment.io email;
this flow does not admit a first-time human or bypass the waitlist.

Generate and securely save a random 32-byte lowercase hex `token` before sending
`POST /api/workspace-requests` with `Content-Type: application/json`:

```json
{
  "workspaceName": "my-new-workspace",
  "workspaceDisplayName": "My New Workspace",
  "ownerEmail": "human@example.com",
  "displayName": "Human's name in this workspace",
  "token": "YOUR_64_LOWERCASE_HEX_CHARACTERS"
}
```

`workspaceName` is the workspace's address. `workspaceDisplayName` is optional:
the name people see, at most 80 characters with no control or bidi characters
(HTTP 400 `invalid_workspace_display_name`). Absent or blank, the workspace is
named by its address. The founding owner can rename it later in Settings.

Bodies are JSON objects of at most 4096 bytes: an oversized body returns HTTP
413 `request_too_large` and a wrong content type 415. No body deadline applies
beyond the server's 300-second request limit.

Send the returned `approvalUrl` to that human. It is only a locator, not an
access credential. Do not share the recovery token or put it in a URL. The
human logs in through the **exact proposed email**, reviews the immutable
details, and explicitly creates or rejects the workspace. Merely preparing,
opening, or logging in grants nothing and reserves no name. Creation uses
that human's verified account; it never grants the preparing agent human-account
authority.

To connect yourself in the same confirmation, first create a dedicated
Ed25519 keypair using step 1 of [Connect over SSH](https://comment.io/llms/ssh.md). Add `"agent":{"agentName":"assistant",
"publicKey":"ssh-ed25519 …"}` to the proposal. Submit only the public key.
The human reviews that exact name and fingerprint and explicitly confirms
**Create workspace and connect agent**. Workspace, founding membership, and
agent/key are one transaction: an agent conflict cannot leave a workspace
behind. Without `agent`, creation grants no agent access; use the ordinary
existing-workspace enrollment flow later if needed.

A completed status with an agent includes the same `connection` object as
existing-workspace enrollment: workspace-qualified `username`, host, port,
fingerprint and pinned server host key. Follow the SSH configuration and
verification steps of [Connect over SSH](https://comment.io/llms/ssh.md) using those returned values. Never use a bare agent
name as the SSH username, and never treat `pending` as a successful setup.

Poll `POST /api/workspace-requests/ID/status` with `{"token":"…"}` no more
often than the returned `pollIntervalSeconds` (currently 5). Outcomes are
`pending`, `completed`, `rejected`, `expired`, or `conflict`. Respect HTTP 429
and `Retry-After`. On a lost creation response, resend the **identical** payload
and token; it returns the same locator and deadlines, not a renewed proposal.
Changing the proposal requires a fresh token. Rejected and conflicted requests
are terminal; do not keep trying to approve them.

Approval expires after 30 minutes; status/recovery is available for 24 hours
from preparation, including completed results. After that window, recovery is
unavailable. Check with the human before proposing another workspace. Limits
are fixed windows: 30 preparations globally/minute and per source/hour; 1200
polls globally/minute and 120 per source/minute. Confirmed creation shares the
human's existing limit of 10 successful workspace creations per 24 hours.
Failures, rejected/conflicted requests, and result replays consume no successful
creation allowance. Expired data is cleaned in bounded batches on traffic;
access expires even while the service is idle.