Share Links

A share link is a time-limited token that lets someone reach a specific machine through the CMDOP relay without an API key, without joining the workspace, and without any local install. You hand them a URL; they get a browser-based terminal scoped to one machine for the lifetime of the link.

Why share links exist

Three patterns motivated the feature:

1. Guest support. A vendor or contractor needs shell access to one server for a few hours. You do not want to add them to the workspace or hand them a long-lived API key.
2. One-off pairing. You want a colleague to look at the same shell you are looking at — paste them a link, they join, you both see the same PTY.
3. Out-of-band incident response. A relay link beats spinning up a new SSH user, opening a firewall, or adding a temporary IAM rule.

The flow goes through connectclient.CreateShare() in internal/connect/client/share.go:37–76.

Creating a link

# Default: 24-hour link.
cmdop connect share vps-audi
 
# Custom TTL.
cmdop connect share --ttl 4h vps-bmw
 
# Never expires (use sparingly).
cmdop connect share --ttl 0 prod-api-1

The CLI resolves the hostname through the unified machines.Resolve, creates the share via gRPC, and prints a URL plus metadata:

$ cmdop connect share vps-audi --ttl 4h
{
  "url":        "https://app.cmdop.com/share/3f7a8c1b...",
  "token":      "shr_3f7a8c1b...",
  "machine_id": "8f23a4b0-...",
  "expires_at": "2026-04-27T19:32:00Z"
}

--ttl accepts hours-only granularity. Values smaller than an hour round up (e.g. 90m becomes 2h). --ttl 0 mints a link with no expiration — the recipient keeps access until you revoke it from the dashboard.

What the recipient sees

Following the URL opens the web cabinet’s terminal scoped to that one machine. The recipient does not see other machines, the workspace member list, billing, or any other tenant data. They get:

• A browser PTY attached to the shared machine.
• Whatever the machine’s OS and permissions allow that shell to do.
• The same multi-client behavior as a local attach — if you are also attached, you both see the same session.

The link does not require a CMDOP account. It is intentionally as low-friction as we can make it.

Hours-only TTL

The relay stores expiration with hour granularity. This is a deliberate trade-off:

• Operators rarely think in minutes when handing out access (“for the rest of the day”, “until tomorrow morning”).
• Coarser granularity means cleaner revocation semantics — the server sweeps expired links on the hour boundary.

If you need a sub-hour link, just revoke manually when you are done.

Listing and revoking

Share links are managed from the web cabinet today. Open the machine’s detail page in the dashboard to see active links, copy URLs, or revoke them. Revocation is immediate — the next attempt to attach via the revoked token gets UNAUTHENTICATED.

There is no CLI verb for “list shares” or “revoke share” yet. The agent-tool surface (connecttool operation=share) only mints new links, mirroring the CLI.

Share link vs workspace key

If you find yourself minting share links for a teammate who will be around for more than a week, give them an API key for the workspace instead.

From an agent prompt

The connect agent tool exposes share via operation=share:

{
  "operation": "share",
  "hostname": "vps-audi",
  "ttl_hours": 4
}

Returns:

{
  "url": "https://app.cmdop.com/share/3f7a8c1b...",
  "token": "shr_3f7a8c1b...",
  "machine_id": "8f23a4b0-...",
  "expires_at": "2026-04-27T19:32:00Z"
}

Useful for prompts like “create a 2-hour share link for vps-bmw and email it to [email protected]” — the LLM mints the link, then your permission rules decide whether the email tool may actually fire.

ttl_hours: 0 means “never expires”; agents should default to a non-zero value unless the prompt explicitly asks for permanence.

Auth model under the hood

Share links use the same streaming-auth gate as any other terminal attach. The token replaces the workspace’s API key — the relay verifies it server-side, scopes the resulting session to the linked machine, and otherwise drops the user into the standard terminal flow. Password-protected machines still prompt for the password, even to share-link users.

Common pitfalls

• Sending the URL via the workspace’s chat tool. If your CMDOP agent has a chat or email tool wired up, an LLM can technically email a share link — make sure your permission rules gate that combination.
• --ttl 0 on production. Permanent links exist but should be the exception. The dashboard makes them obvious; revoke when the use case ends.
• Sharing while a password is set. The share recipient still needs the machine password to attach. If you want password-free guest access, use a workspace without machine passwords.

Related