Skip to the content
docs

ChatGPT and Claude connectors

Cloudfield was named Aether until November 2026. The commands, paths and hostnames in this guide still use that name. View this guide on GitHub.

Browse guides / Connectors

A connector is a custom MCP connector in ChatGPT or Claude that points at your Cloudfield server. Once you add one, you can launch sessions, see what needs you, answer agents, and check pull requests from a chat in ChatGPT or Claude, the phone apps included, with no Cloudfield app on the phone. The connector acts as you: the Cloudfield member who authorized it, under the same role checks as aether and the dashboard.

CODE
flowchart LR
    A[ChatGPT or Claude] -->|HTTPS tool calls| E[Edge]
    E -->|forwards| S[Your Cloudfield server]

The edge is a public relay your server connects out to (edge.md). Your server hosts the connector endpoint and signs you in.

Prerequisites

  • A server connected to an edge. ChatGPT and Claude reach the connector at <edge-url>/mcp, the universal URL every server on the edge shares, or at the server's own <edge-url>/mcp/<server id>. A server reachable only on a tailnet cannot have one. To turn the edge on, see edge.md.
  • A server new enough to serve connectors. Otherwise the edge answers HTTP 501: server <name> (<id>) runs aether-server <version>, which has no MCP endpoint; upgrade it: sudo aether-server update.
  • A linked CLI (aether link) on an approved device, a member SSH key or a tailnet connection. Under edge-access account, any registered device works.
  • A ChatGPT or Claude plan that allows custom connectors (see below).

Get the URL

In the app, open Settings → ChatGPT and Claude, or pick Connect ChatGPT or Claude in the command palette (Ctrl+K or ⌘K). The link ?page=settings&id=connectors opens the same section, and the last onboarding step links to it. Pick ChatGPT or Claude for that app's steps. The section shows the URL at once. What the third step asks depends on the server's edge-access policy:

  • account, with a GitHub account linked to you: no code. The page that opens signs you in at the edge. Watch for the connection waits up to 10 minutes for it.
  • Otherwise: Get a code shows a pairing code with a live countdown.

The section checks every 3 seconds and shows ChatGPT (chatgpt.com) connected with its scopes once the app connects. It lists your connectors with their scopes, the URL each was added at, when each was added and last used, and Reconnect and Revoke buttons. Errors appear as aether mcp prints them, with a link to the fix.

From a terminal:

CODE
aether mcp
CODE
Install Cloudfield from the ChatGPT or Claude directory where it is listed, or add this URL as a custom connector:
  URL   https://edge.onaether.dev/mcp
  No code: on the page that opens, sign in to the edge with GitHub, pick this server and select Allow
Connected:
  con-7k2m9q4xbd  ChatGPT (chatgpt.com)  scopes read,write  added 2026-10-18  last used 2h ago  universal URL
Remove one: aether mcp revoke <id>

Where the page asks for a code, aether mcp prints one instead of the No code line:

CODE
  Code  ABCD-EFGH   one use, expires in 10 minutes; paste it on the page that opens when you connect, if it asks

The URL is the same for both apps and every server on the edge. On the server, sudo aether-server edge status also prints it. Before edge protocol 3, and for a member with no GitHub account linked, it is the server's own URL, https://edge.onaether.dev/mcp/<server id>. The code works once, within 10 minutes. Running aether mcp again replaces a code you have not used.

That URL's page asks for a code even when the universal URL needs none, so a connector added there reconnects with one. aether mcp code prints a code alone. In Settings, Reconnect on such a connector shows the server's own URL and a code. A connector added at the universal URL of another address of the edge is not such a connector: it shows as Universal URL and reconnects with the sign-in.

Add it in ChatGPT

Custom MCP servers are added on the web only, at chatgpt.com (OpenAI: custom MCP servers):

  1. Open ChatGPT Plugins.
  2. Select the plus button, then Add custom MCP server.
  3. Name it Aether, paste the URL from aether mcp as the server URL, and choose OAuth.
  4. Select Create as a plugin, then install it.
  5. On the universal URL, the edge's page opens: sign in with GitHub and select Continue with <server>. A page from your server opens: Connect ChatGPT (chatgpt.com) to <server>. Paste the code if it asks for one, choose its scopes and select Allow.

As of October 2026, OpenAI says write tools need ChatGPT Business or Enterprise/Edu. Pro gets the read tools only (OpenAI help center). The plugin then works in ChatGPT on the web, desktop and mobile.

Add it in Claude

On claude.ai (Anthropic: add a custom connector):

  1. Free, Pro and Max: open Customize → Connectors, select Add custom connector, name it Aether, paste the URL from aether mcp, leave Advanced settings empty and select Add. Free allows one custom connector.
  2. Team and Enterprise: an Owner opens Organization settings → Connectors, selects Add, Custom, then Web, and pastes the URL. Each member then selects Connect under Customize → Connectors.
  3. Select Connect. On the universal URL, the edge's page opens: sign in with GitHub and select Continue with <server>. A page from your server opens: Connect Claude (claude.ai) to <server>. Paste the code if it asks for one, choose its scopes and select Allow.

The connector then works in Claude on the web, desktop and mobile.

The universal URL

https://<edge>/mcp is one URL for every Cloudfield server, so one ChatGPT plugin can serve every Cloudfield user. Once Cloudfield is listed in ChatGPT's plugin directory (chatgpt-plugin.md) or Claude's connector directory (claude-connector.md), install it from there instead of adding a custom MCP server; connecting then works as described here.

When you connect, the edge's sign-in page opens: sign in with GitHub if you have not. Choose a server names the app you are connecting and lists your servers with their names, ids, your role and whether each asks for a code, each with Continue with <server>, and the servers that cannot take the connection with why. It asks even when you have only one server, so you always see which server you connect. That server's consent page opens and states the server, its id, the client and, under account, the member. Then, depending on the server's edge-access policy:

  • account: Connect ChatGPT (chatgpt.com) to <server> as <member>, with the scopes and no code. Signing in at the edge already admits you there.
  • approved-devices: the page asks for the code. Paste the code from Settings → ChatGPT and Claude in the app, or aether mcp.

Continue posts the edge's signed statement that your GitHub account chose this server to the edge, never in a URL. The server binds it to the first browser that brings it, and only that browser's consent page can use it, once, within 5 minutes. A link copied out of your browser, history or a log connects nobody. edge.md has the details.

The sign-in page lists a server only to the GitHub accounts bound to its members. So the app and aether mcp show the universal URL only to a member with a GitHub account bound, and <edge>/mcp/<server id> to one with only a member SSH key or tailnet login. sudo aether-server edge status prints both.

A connector added without a code stops working when the server switches to approved-devices, when its GitHub account is unbound from the member (aether member identities, or deleting the account at the edge), or when the member is removed. It has no device, so a method that needs an approved device refuses it, as it refuses a device no person approved, and it cannot mint a pairing code or a Slack link code. Connectors added at <edge>/mcp/<server id> keep working there.

Move a connector to the universal URL

A connector keeps the URL it was added at. Settings marks each one Universal URL or This server's own URL, and aether mcp prints universal URL or at <url>. Once Settings shows the universal URL for you, Move to the universal URL next to a connector on the server's own URL starts a new connection: add Cloudfield again in the app with the universal URL. Settings revokes the old connector once a new one from the same client, such as ChatGPT or Claude, connects at the universal URL and calls Cloudfield. If none calls within 10 minutes, it leaves the old one and says so. Remove the old Aether connector in ChatGPT or Claude yourself. From a terminal, connect again at the universal URL, then run aether mcp revoke <old id>.

Self-hosted and custom edges

The universal URL is https://<relay host>/mcp of whichever edge the server uses, so an operator's own edge has its own. <edge>/mcp/<server id> with a pairing code works on every edge from protocol 2 and under either policy.

An edge with more than one relay host serves a connector at each of them once the edge and the server both speak edge protocol 6. A connector keeps working only at the host it was added at (edge.md).

Claude Code

Claude Code connects at the same URLs:

CODE
claude mcp add --transport http aether https://edge.onaether.dev/mcp

Then run /mcp in Claude Code and authenticate. Its client metadata document, https://claude.ai/oauth/claude-code-client-metadata, lists http://localhost/callback and http://127.0.0.1/callback, and Claude Code listens on a port it picks. For that client id alone, the consent page accepts those redirect URIs on any port (RFC 8252); every other client must return to an HTTPS URL on its own host. PKCE is required as for every client. Any program on your machine that can listen on a local port could receive the code, but it cannot redeem it without the PKCE verifier Claude Code holds.

Scopes

The consent page also sets the connector's scopes. ChatGPT and Claude do not choose them; the server ignores any scope they request other than offline_access, the only one the OAuth metadata lists in scopes_supported.

Scope On the page Grants
read Always granted Every read-only tool
write Launch and message, checked by default Launching sessions; messaging, pausing, resuming, relaunching, protecting and archiving sessions; answering agents' and teammates' questions; marking sessions reviewed; adding and pinning team memory; asking your assistant
control Stop and approve, unchecked by default Deciding permission requests, stopping and closing sessions, switching a session's mode, handing sessions to teammates, opening and merging pull requests. Text an agent wrote could talk the assistant into approving or ending work without asking you

Every member can read every session on the server, so a connector can read all of them. A connector lists only the tools of its scopes, and aether mcp shows each connector's scopes.

The server also checks the scope of every call a connector makes, whatever the member's role. Reads such as run.get, run.close_check, workspace.timeline, member.list, memory.show, template.list, changes.list and launch.defaults.get need read; run.launch, template.launch, run.inject, run.room.post, run.pause, run.resume, run.wake, run.review, run.relaunch, run.protect, run.archive, memory.add, memory.pin, memory.unpin and assistant.ask need write; run.kill, run.close, run.mode.switch (it discards a turn in progress), run.handoff, run.pr.create and run.pr.merge need control. run.input.respond needs control to decide a permission request and write to answer a question. run.review with complete needs control for a live session unless its agent reported success and the session awaits review, since completing any other live session ends it. Every other method, such as member.role, connector.revoke or launch.defaults.set, is refused to every connector:

CODE
run.kill needs the control scope, which ChatGPT connector con-7k2m9q4xbd was not granted; select Reconnect next to it in Settings → ChatGPT and Claude and check Stop and approve on the consent page
member.role: ChatGPT connector con-7k2m9q4xbd cannot call this method; no connector can, so use the Cloudfield app or the aether CLI

To change scopes, revoke the connector and connect again, or select Reconnect in Settings. It gets a new code where the page asks for one, and revokes the old connector once the new connection calls Cloudfield. Connectors added before scopes existed have all three.

What it can do

The connector has these tools and no others:

Tools What they do Scope
aether_list_workspaces Workspaces, and agents (installed, signed in, Enhanced) read
aether_launch_options What you can launch and on which account: workspaces, your accounts with their usage, each account's agents and modes, fallback, a workspace's templates, and an agent's models when asked for (Launch options) read
aether_list_sessions, aether_get_session Your sessions (or everyone's with mine: false) with their last report, filtered by workspace, activity, what needs you, or words in the title, task, workspace name or branch; one session with what it waits on, its wait_conditions, its latest report and its pull request; evidence: true adds progress evidence read
aether_session_history A page of a session's conversation (Enhanced) or terminal, with the session's newest reports, the same on every page; limit (default 20, at most 50) caps the page and the reports read
aether_needs_attention What needs you, the dashboard's Needs you list, each item naming the tool that answers it read
aether_activity_summary What your sessions did today, yesterday or this week, in your time zone read
aether_session_changes, aether_pr_status A session's commits, conflicts, changed files and optionally its diff, for its primary or an extra repo, paged; its pull request's checks, reviews, comments, merge state and head commit read
aether_overlaps, aether_memory_search Pairs of active sessions touching the same files; the workspace's team memory, or with id one note with the notes that replaced it or that it replaced read
aether_changes What changed since a cursor: session status, reports, agent mail, pull requests and lifecycle, oldest first, paged with next_cursor read
search, fetch Find runs by text, in the shape ChatGPT deep research uses read
aether_watches Your watches, each with its state, conditions and last notice; with watch_id, one watch with its 10 newest notices and where each was delivered read
aether_launch_session Start a session, from a task or a saved template, on any account you may use, with a fallback policy and extra repositories write
aether_message_session, aether_answer Message a session; answer an agent's or a teammate's question write
aether_pause_session, aether_resume_session, aether_mark_reviewed Pause or resume a session; accept a reported success, which closes the session, put it off, or say the work is not finished write
aether_session_lifecycle Relaunch a stopped session, protect or unprotect it, archive or restore it write
aether_memory_add, aether_memory_pin Add a team memory note; pin or unpin one write
aether_ask_assistant, aether_decide_assistant_card Send a prompt to your assistant and read its reply; approve or decline a card its turn raised (Ask your assistant) write
aether_watch, aether_unwatch Watch a session (run_id) or pull request (pr: owner/name#7 or its GitHub URL) for conditions, optionally relaying each notice into up to 4 sessions (relay_to), or with watch_id change its conditions, relay_to or expires_at, or pause or resume it; delete a watch and its notices write
aether_decide_approval Allow or deny a permission request, once control
aether_stop_session Stop a session, or with outcome close it as merged or abandoned control
aether_switch_session_mode Switch a live session to Standard or Enhanced, discarding the turn in progress control
aether_handoff_session Give a session to a teammate, who then owns and controls it control
aether_pr_create, aether_pr_merge Open a pull request from a session's pushed branch; merge it on GitHub control

Things to ask:

  • "What needs me in Cloudfield?"
  • "What is the agent working on edge doing?"
  • "Launch a Claude run in api to fix the flaky login test."
  • "Which subscription has the most usage left? Launch the docs fix on it."
  • "What changed since I last asked?"
  • "What did my agents do today?"
  • "Is CI green on the login fix PR? What did reviewers say?"
  • "Tell the parser session to use the new tokenizer."
  • "Which sessions touch the same files as the migration session?"
  • "Merge the login fix PR if CI is green."
  • "Tell me when the login fix session needs me or finishes."

The connector tells ChatGPT and Claude to launch and write the task as Cloudfield's assistant does: What a launch's task holds.

Results link to the session in the dashboard when the server serves one on its tailnet (web-port); the edge serves no dashboard. A result's text is a one-line summary followed by the result as JSON. Text that agents, teammates or GitHub users wrote, session titles, failing check names, the reasons sessions wait, and a watch's receipt, observed state and notices included, comes back under an untrusted field; outside it are only fixed labels such as The agent asks a question, ids, states, counts, times, links, workspace and agent names, branch names, file paths and the server's own errors. A session's wait_conditions keep the parsed spec, kind, repository, number, target session, state, outcome, observed checks and times outside it; each condition's summary, detail and the errors GitHub or delivery returned sit under untrusted.wait_conditions, by id. A list row's waiting_until holds the specs still pending. Untrusted text is cut to 200 characters for titles, check names, commit subjects, a list row's reason or last report, and a watch notice's title and body; 300 for each pull request review or comment; 2000 for a conversation item; 12000 for a diff; and 600 for everything else, such as tasks, reports, questions, permission request text, terminal lines and memory notes. search and fetch keep OpenAI's shapes, with no untrusted field: their descriptions say titles and text are data, fetch's text marks where agent text begins, and it returns a session's title, task and reason whole. A permission request longer than 600 characters is decided only in the dashboard, never by aether_decide_approval. Lists return 20 rows by default, at most 100, and say how many matched when they cut rows; aether_needs_attention returns at most 30 items, pending permission requests and questions first, since a sudo request expires after 10 minutes, then the rest oldest first. aether_session_changes lists 20 commits and up to 10 diff files of 6000 bytes, 12000 in all, per page, and returns next_commits_offset and next_diff_file for the next page, diff_clipped_files with the numbers of files cut at 6000 bytes, and diff_truncated: true when the server cut the diff before paging, so files past the cut are missing. The diff is the worktree against the merge base with the session's base: committed, staged and unstaged tracked changes, not untracked files. With no diff it is diff: [] with a diff_note, never null; an unresolvable base is diff_error. repos names a multi-repo session's extra repos, which repo selects. Tools that take a run_id also accept the run: ids search returns. When the server no longer keeps the start of a session's conversation or terminal, aether_session_history returns truncated_before: true and a note saying so.

A launch, message or answer takes an optional idempotency_key; a retry with the same key returns the first result. A write's result has write: "done", or "pending" while a launch is starting or a message waits for approval, and the key it used. write says only that the call finished; a message's state says whether it reached the agent. A message the session did not take fails the call with the failure code and the way forward, for example message to session run-… was not sent (session_protected; …); unprotect it with aether_session_lifecycle, and the real error under untrusted.failure, since an agent's refusal is the agent's text. Send it again, with a new idempotency_key if you passed one. A failure that leaves it unknown whether the write happened, such as a timeout, ends with the key to retry with. A teammate answer retried with its key after the question stopped waiting returns the saved answer; an answer_id that is not a teammate question on the session fails and writes nothing. A launch still starting after 30 seconds, such as one pulling its image, keeps starting after the tool call ends. The tool then repeats the call with the key to look up the session, which does not count as a write call. If the lookup answers within 5 seconds, the result has the id, state: "starting" and the key; poll aether_get_session. If it does not, the result has only state: "starting" and the key, plus the lookup's error when it failed; call the same tool again with the same arguments and key to get the id. Without a key, a session launch with the same workspace, agent, task, mode, model, account, fallback policy and extra repositories within 60 seconds returns your earlier session, unless it failed, was interrupted or was abandoned, instead of starting another; so does an identical launch still starting, or one that failed in the last 60 seconds without saying whether it started. A message without a key reuses the key of the same message to the same session still being sent or sent within 60 seconds, so a retry is delivered once and its result has duplicate: true. To send the same text again on purpose, pass a new idempotency_key.

Launch options

aether_launch_options answers what the launch dialog shows, in one call:

  • workspaces, and modes with their dashboard names: tui Standard, headless Background, acp Enhanced.
  • accounts: the agent accounts you may launch on, your own first, then each one a teammate shared with you (Agent accounts). Each has access (own or shared), ready (some agent can launch on it), its usage, and its agents. A teammate's account that is not shared with you never appears. Past 100 workspaces or accounts, workspaces_total and accounts_total say how many there are.
  • Usage is each provider's windows, labelled as the provider labels them, with used_percent and resets_at. It is never money. An agent with no usage row has unknown usage.
  • Each agent has modes a session may start in and refused when a launch on that account would be refused, such as an owner who is not signed in.
  • fallback: with neither fallback_account_member_ids nor no_fallback, a launch whose account has used 95% of a usage window moves to the usable account with the most usage left.
  • With workspace_id, its templates, each with its version and params, every placeholder of its task with required when it has no default (the defaults and tasks are under untrusted); pass version to aether_launch_session as template_version to refuse a template changed since. With models (an agent name) and optionally account_member_id, that agent's models on that account, each an id to launch with and its name, such as fable and Fable 5.2, which the server caches. account_member_id without models is refused. When it lists none, launch without model for the agent's default, or pass the id the agent takes.
  • saved: your saved launch choices as launch.defaults.get returns them, with invalid and unknown listing each choice a launch could not use or check, with the reason. saved_error holds the error when they could not be read. Connectors can read them but not change them.
  • server.version and server.ops_contract, the version of the tools' inputs and results. It is 2 since launches fill omitted fields from your saved choices.

aether_launch_session takes account_member_id, fallback_account_member_ids (an order), no_fallback, extra_workspace_ids, children (on or off: whether its agent may start subsessions; without it, your setting decides) and permission (root, default or isolated: the session's permission tier), as aether session does. Any other permission fails with the tool's schema error, such as validating /properties/permission: enum: admin does not equal any of: [ root default isolated]. The server checks the account before anything starts: a launch with an agent or fallback account not shared with you fails with the server's error. A launch or template launch the server does not understand fails with unknown param "<name>" instead of starting without it.

A launch fills each field you leave out from your saved launch choices: what you pass wins, then what you saved, then the server's own defaults, which for permission is Default. harness may be left out when you saved an agent that can launch on the launch's account; the saved agent's mode and model apply to whichever agent the launch uses. A saved mode the agent cannot start in on the launch's account, or a saved fallback member launch.defaults.get reports as invalid, is skipped with its reason. A saved model is always used: launch.defaults.get checks it only on the saved account and can only report it unknown, and the agent refuses a model it does not offer when the session starts. A saved account you may no longer use fails the launch:

CODE
saved account mem-7k2m9q4xbd: permission denied: member mem-7k2m9q4xbd has not shared their account with you; pass account_member_id or clear it

A share revoked after that check fails at launch with the server's error; the launch never moves to another account. With no agent passed and none saved, the launch fails with harness is required: you have no saved agent. Pass saved_defaults: "ignore" to send exactly the given fields. Leaving the fallback fields out cannot ask for automatic fallback while you saved an order or off: pass saved_defaults: "ignore" with every other field you want. Template launches never use saved choices. A keyed retry the server refuses as a different launch adds your saved defaults may have changed since the first attempt; pass the fields explicitly.

Each launch's result and aether_get_session has a launch receipt: id, workspace_id, harness, mode, mode_name, model (absent means the agent's default), account (member_id, name, access: own, shared, or other for a teammate's own session), requested_account when usage fallback moved the session, fallback (policy: automatic, ordered with order, or off), repos, the session's own children setting, its permission tier, via, and url. An Enhanced session sets its model after it opens, so a launch's model is the one asked for; when the agent refuses it, aether_get_session names it in refused_model, model is the one the session runs on (absent for the agent's default), and untrusted.model_error says why. A new launch's receipt adds defaults_applied, the input fields your saved choices filled, defaults_skipped, each saved choice it did not use with field and reason, and defaults_unchecked, each saved agent, mode or model it used without being able to check it on the account the session started on, with field and reason: an agent or mode when the agents could not be listed, which the server then checks at launch, and a model the server could not check there. A duplicate or replayed launch's receipt has none of them. It adds idempotency_key and skipped_fallback_accounts: the fallback accounts the server left out because checking them failed, each with a fixed error reason; the server log has the detail. aether_get_session also names the session's parent_run_id and lists its children, nearest first, each with its state, agent and account, stale when the session's branch moved past the commit the subsession started from, its latest report's outcome and at, and what its parent asked of it and the report's summary under untrusted; children_error says why they could not be read, unless the server has no subsessions.

Progress evidence

aether_get_session takes evidence: true to answer "what is left" and "did we ship" from evidence rather than from an agent's own report. Without it it makes no GitHub lookups for this. Every part carries its source and the time it was read (as_of or checked_at); a lookup that failed returns its error instead of a guess, and the summary line ends with Not confirmed: and the number of lookups that returned an error, sessions with pull requests not checked live, and unreadable reports. It adds released and deployed as {"state": "unknown", "reason": "Cloudfield does not track releases or deployments of this repository"}.

The lookups are the same as aether_pr_status's, for at most 5 sessions per call: one may record what GitHub showed in Cloudfield and tell open dashboards that the session's pull request changed.

aether_get_session's evidence has:

  • pull_requests: the first 20 pull requests the session opened (pull_requests_total when there are more), as Cloudfield recorded it (source: "aether record", with the checked_at of that record), or as GitHub just showed it (source: "github"). Only a lookup that reached GitHub without an error relabels one; a finished session's lookup can answer from Cloudfield's record without asking GitHub, and a recorded merge stays as recorded. A pull request not merged that no lookup confirmed has not_checked_live. A session closed as merged adds closed_as_merged: a person closed it, which is not a GitHub merge.
  • reviewed: for a session with a pull request not merged, GitHub's checks (total, failing, pending), approvals and changes_requested from the latest verdict of each reviewer, merge_state and checked_at. The checks belong to the pr and head shown; when the pull request moved between the status and checks lookups, error says so. When GitHub cut the review list off, partial is set and approvals is left out, since a later verdict may be missing.
  • report: the latest report's outcome and at, or not in the last 100 reports.
  • conflicts: success_with_failing_checks, success_with_pending_checks, success_with_changes_requested and closed_as_merged_but_pr_not_merged.

aether_launch_session with template (a name from aether_launch_options with workspace_id) and params runs a saved template on your own account with its agent, mode and model. It takes no task, agent, mode, model, account, fallback or extra repositories, since template.launch has none, and refuses them by name. Without template, it needs task, and harness unless a saved agent fills it. Without an idempotency_key, a template launch is deduplicated only while an identical one is still starting.

Changes

aether_changes pages changes.list. Without cursor it returns the newest changes; pass next_cursor back for the ones after them, while more is true. Filter by workspace_id, run_id and kinds. Report summaries and status reasons sit under untrusted, cut to 200 characters. CI checks are not changes; read them with aether_pr_status. A cursor the server's history no longer matches, such as one from before a restore, fails with an error that says to call again without cursor.

Writes

aether_mark_reviewed completes only a session whose agent reported success and awaits your review; to end any other session, use aether_stop_session under control. Both read run.close_check before they act, and so does a stop without outcome, since a stop also ends the session and settles its subsessions: one with warnings fails with closing session <id> has warnings (<kinds>), listed under untrusted.warnings; ... until the call repeats with acknowledge: true, so the assistant shows you what each stop or close affects first. acknowledge is the caller's word that it showed them; the server does not tie it to the warnings it returned. The warnings sit under untrusted because they quote session titles agents wrote. The dashboard assistant's close card lists the same warnings (failure-handling.md). A message to your own session that no one controls in the dashboard, or to a session you control, reaches the agent at once. Any other message waits about 45 seconds for the member in control to approve it. aether_decide_approval allows or denies a permission request once; it never picks an "always" option, so it cannot change what the agent may do next time. Any other tool call is cut off after 40 seconds, inside ChatGPT's wait.

The other writes repeat safely without a key. Each aether_session_lifecycle action but relaunch sets a state, so a repeat changes nothing, and aether_switch_session_mode to the mode a session is already in reports that without switching; relaunch fails on a session that is still live. aether_handoff_session to the session's owner reports that and writes nothing. aether_pr_create returns the session's open pull request instead of opening another, and aether_pr_merge reports a merged one as merged. aether_watch takes one target: run_id or pr, optionally with run_id for the session that opened it; any other combination is refused with the fields named. Its conditions depend on the target, the defaults marked *:

Target Conditions
run_id needs_you, finished, pr_merged, ci
pr ci, review, merged*, closed

A condition the target does not take, or deployed, fails with the server's error, which names the conditions to use (watches.md). expires_at is an RFC 3339 time at most 90 days ahead; without it a watch expires after 14 days. relay_to lists session ids each notice is written into, as Relaying notices describes; [] with watch_id stops relaying. aether_watch takes no idempotency key: creating a watch the server already has live, the same target, conditions and relay_to, returns that watch and resumes it if paused. Its result holds the watch's state and the server's one-line receipt under untrusted, since it carries the target's title; only active means it is watching. Its links open the watch in Settings → Watches. aether_watches lists the newest 50 watches and says how many more the dashboard lists there; one watch's notices come from the newest 50 the server returns, so a full page reads at least 50 and sets more_notifications_capped. aether_unwatch of a watch already deleted succeeds with state: "not_found", so a retry is safe. aether_memory_add returns the existing note for a duplicate, and repeating a replacement (supersedes) that went through returns the note that replaced the old one.

aether_pr_merge takes repository, number and expected_head_oid, the pull request's repository, number and head_oid aether_pr_status returns, and refuses when the session's pull request is now another one, in another repository, or its head has moved since, before asking GitHub; with no head to compare, as for a finished session whose environment is gone, it fails with why. A merge GitHub accepts but has not done, as with a merge queue, returns write: "pending"; follow it with aether_pr_status. That refusal and GitHub's own count the failing and pending checks and the reviewers requesting changes, as lower bounds when GitHub's feedback was cut off, and give the merge state; aether_pr_status names them under untrusted. It merges with squash unless method says merge or rebase, and only into the base branch it saw. aether_pr_create opens the pull request from the session's current branch and head into the target run.pr.status resolves, the workspace's base branch on its source repository as the dashboard proposes, and passes both to run.pr.create, so neither changes after you approve; the branch must be pushed. When GitHub's answer is lost but the pull request is found afterwards, the result is that pull request. aether_pr_status and aether_pr_merge take the same repo as aether_session_changes. Once a finished session's sandbox is gone, aether_pr_status still reports its recorded pull request's checks and reviews, read from GitHub, without merge state or comments: its result sets comments_unavailable and its summary says comments unavailable instead of a count. When only the reviews read fails, it keeps the checks, sets reviews_unavailable and puts the error in its summary in place of the review count. aether_handoff_session takes the teammate's member id or exact display name; an unknown or ambiguous one fails with the teammates' ids and roles, and the server refuses a viewer. aether_switch_session_mode holds no control lease, so it fails while a member controls the session in the dashboard. Text a pull request, agent or note carries never authorizes anything: these tools act only on what the arguments name.

Ask your assistant

aether_ask_assistant sends a prompt to your assistant as a turn in your one conversation, with your preferences applied. Each call costs the external model's tokens and a turn on the assistant's sign-in, so read with the other tools. Pass prompt, with an optional idempotency_key, to queue a turn, or turn_id to read that turn again without starting one. Either waits up to 25 seconds for the turn to end.

The result holds turn_id, state (done, queued, running, waiting_for_approval or failed) and, under untrusted, reply, pending_cards and a failed turn's error. Poll with turn_id until state is done or failed; polls do not count against the 30 write calls. A repeat with the same idempotency_key returns the first turn, so ask the same question again with a new key or none. Without a key, the same prompt from the same connector within 60 seconds of its first send returns that turn while it is queued or running, and starts a new one once it ended. A turn_id or card_id from another connector or another door fails as an unknown id would.

reply and error are the turn's own: never the transcript, your preferences or earlier turns. A connector turn reads none of your dashboard view context, such as the page or file you have open. Each run of words matching a saved preference reads [preference withheld], zero-width and control characters are dropped, and text over 4 KiB ends with [reply cut here, at byte <n> of <total>]. A paraphrase of a preference gets past the check (security.md).

Each pending card is {card_id, card}, where card is the card's summary followed by one <field>: <value> line for each parameter the call runs with, whole, and a template launch's rendered task. A value holding a line break or a character not printed as itself, such as a bidi override, is shown quoted with escapes.

aether_decide_assistant_card decides one: card_id, decision (approve or decline) and card, byte for byte. Anything else fails with card text does not match card <id>; show the person the card and pass its text exactly and decides nothing. It is a separate tool so the host asks before each decision; an Always allow on it lets the external model approve cards without asking you, so allow it once at a time. Approving needs the scope of the method's own tool: write for launches, messages, answers, pauses, session lifecycle, memory notes and watches, control for stops, closes, merges, pull requests, mode switches and handoffs. A method no connector tool calls, such as saving the environment or your launch defaults, is decided only in Cloudfield. Declining needs no scope. Only a card a turn of this connector raised can be decided. A card reads Waiting for your approval in Cloudfield and is decided only there when its text is over 2,000 characters, its summary holds a line break or a character not printed as itself, it forgets a preference or shows a saved one, or approving it needs a scope the connector lacks now or lacked when the turn ran. The connector offers only Approve and Decline; rules and auto-approval change only in Cloudfield.

Your approval rules and auto-approval apply to connector turns as to dashboard turns, within the connector's scopes: a method the connector was not granted always shows a card, decided in Cloudfield. A call that never shows a card, such as a pause, runs only under a scope the connector holds, so a connector turn cannot save a preference. The server reads the connector's scopes when each prompt is sent and each call is checked, not when the prompt was queued: once you revoke the connector, its waiting prompts fail with assistant: ChatGPT connector <id>: it was revoked, its turn's calls no longer pass without a card, and its calls that never show one, such as a pause, fail.

The assistant not being signed in fails the call with assistant: no agent is ready; ..., and a full queue with the queue's own error. The MCP Tasks extension is not supported: the Go MCP SDK this server uses (v1.7.0) has no tasks/get, so clients poll with turn_id.

Only in the dashboard

These need a browser or a control lease, which a connector and the assistant do not hold:

  • Typing into a Standard session's terminal, and agent account logins.
  • The browser pane and port forwarding.
  • File attachments; send a link or pasted text instead.
  • Web push subscriptions.
  • Cancelling an Enhanced session's turn, setting its options such as effort, deciding a queued message, and "always" answers to permission requests.

ChatGPT and Claude ask before each tool that is not read-only. ChatGPT asks by default and can remember your answer for a conversation. Claude offers Allow once and Always allow per tool. Cloudfield shows no confirmation card of its own for these tools, and the assistant's auto-approval applies only inside aether_ask_assistant turns. Your role still decides: a viewer's launch is refused, as it is in aether. A connector's calls are judged by the device its code was minted on: a method that needs an approved device refuses a connector minted on a registered one.

Each connector can make 30 write calls at once, enough for many parallel launches, then regains one every 2 seconds, up to 30 again. Past that, the call fails with connector <id> used its 30 write calls and gets one more every 2s; retry in <seconds>, at <time>.

Attribution

A session launched through a connector shows Launched via ChatGPT (or Claude) in its header, and a message sent through one shows <member> via ChatGPT as its author. The server logs one line per write call:

CODE
connector: write call connector=con-7k2m9q4xbd member=mem-... method=run.launch target=ws-... result=ok

result is ok or the call's error. Audit records, such as a member merge's confirmed_by, name the connector: ChatGPT connector con-7k2m9q4xbd of member mem-....

Audit history

The server also keeps a durable audit history of:

  • every write call a connector makes past its rate limit, including calls the server refused, such as a method outside the connector's scopes
  • every write call the assistant makes
  • connectors being created and revoked, including the server revoking one whose rotated refresh token was used again (connector.reused) and deleting one with its member, or when the edge account that authorized it or its device is unlinked or deleted (connector.removed)
  • account shares and revocations, member approvals, removals and role changes, device revocations, edge sign-in removals, member merge acceptances, and Slack link codes and unlinks, however they were made

A connector whose refresh token lapsed after 30 days unused is deleted without an entry.

An entry names the member, how the call arrived, the method, the workspace, the session, note, question, connector, member, device or Slack user it acted on (for an accepted merge, the absorbed member; for a refused one, the proposal), and ok or error with the error code. It never holds tokens, messages or other parameters. How a call arrived is connector with the client and connector id, assistant, dashboard for the server-hosted dashboard, or cli for any SSH client, including the desktop app and aether gui.

CODE
aether audit                                  # your entries, newest first
aether audit --connector con-7k2m9q4xbd       # one connector's calls, creation and end
aether audit --before 812                     # the page after one ending at 812
CODE
SEQ  TIME                 MEMBER          VIA                                METHOD      TARGET          OUTCOME
814  2026-10-26 14:02:11  mem-4f8x2kq9vd  connector ChatGPT con-7k2m9q4xbd    run.kill    run-d6ay38tj8j  error -32001
813  2026-10-26 14:01:40  mem-4f8x2kq9vd  connector ChatGPT con-7k2m9q4xbd    run.launch  run-d6ay38tj8j  ok

You see your own entries; a super admin sees everyone's. An admin also sees the entries in the workspaces they own, except another member's entries about a session they do not reach in every workspace, or one since deleted, and about a note from such a session or one since deleted. The audit.list RPC returns the same entries, at most 200 a page. The server keeps each member's newest 10,000 call entries and, apart from them, their newest 10,000 connector, account, member and Slack changes that took effect, so a flood of calls cannot push a security change out of the history. A call that changed nothing, such as revoking a share that does not exist, is a call entry. After a member merge, the absorbed member's entries keep their id, so only super admins see them.

Revoke a connector

Select Revoke next to it in Settings → ChatGPT and Claude, or run:

CODE
aether mcp revoke con-7k2m9q4xbd

The connector's next call fails, including one in a session the app already has open, and so does its refresh token; the app asks you to connect again with a new code. You can revoke your own connectors, and a super admin can revoke anyone's; any other connector id fails as an unknown one. Removing the connector in ChatGPT or Claude does not revoke it on the server. Revoke it here too.

A connector also stops working at its next request when:

  • the device it was minted on is revoked (aether device revoke <device id>)
  • its member is removed
  • the server runs under edge-access approved-devices and that device is not approved
  • its refresh token goes unused for 30 days (aether mcp then no longer lists it)
  • the edge moved to another origin, which changes the connector URL

A connector whose code was minted over a member SSH key or a tailnet connection has no device, so revoking a device never cuts it off. Revoke it with aether mcp revoke.

Troubleshooting

aether mcp prints errors as aether: rpc error <code>: <message>.

Message Fix
connector.code: this server has no edge (edge-url is empty), and ChatGPT and Claude reach a connector only through one; an admin turns it on with: sudo aether-server config set edge-url https://edge.onaether.dev, then sudo systemctl restart aether-server Turn the edge on
connector.code: this server is not connected to its edge at <edge-url>; an admin sees why with: sudo aether-server edge status Fix the edge connection
connector.code needs an approved device, a member SSH key or a tailnet connection; this connection signed in with device "<label>", which is registered An admin approves your device, or run aether mcp from an approved one
method not found: connector.code; the server is older than this CLI, and an admin updates it with aether server update Update the server
connector.revoke: no connector <id>; aether mcp lists yours The id is wrong or already revoked

A tool call can fail with:

Message Fix
<method> needs the <scope> scope, which <client> connector <id> was not granted; ... Select Reconnect next to the connector and check the box the message names
<method>: <client> connector <id> cannot call this method; ... No connector can. Use the app or the CLI
503 server is not connected to the edge The server is down or cannot reach the edge; an admin runs sudo aether-server edge status. For 30 seconds after the edge sees the server's control channel end, it holds up to 16 calls and sends them to the server once it is back, so a quick restart does not fail them. A host that drops off the network without closing the channel is noticed only after 60 seconds of silence. If the client marks the connector failed, reconnect it (in Claude Code, /mcp)

On the page that opens when you connect:

Message Cause
That code is wrong, expired or already used. Get a new one from Settings → ChatGPT and Claude in the Cloudfield app, or aether mcp, and paste it here. The code is not live. A server restart also forgets codes
10 wrong codes came from your address in the last minute. Wait a minute, then paste the code again. 10 wrong codes in a minute from your address (your IPv6 /64). Other addresses are not affected
300 wrong codes came to this server from all addresses in the last minute. Wait a minute, then paste the code again. Someone is guessing codes from many addresses. Pairing resumes a minute after the guessing stops
Cloudfield connectors work with ChatGPT and Claude; <host> is not one of them. Only chatgpt.com and claude.ai can connect
None of your servers can take this connection. (edge sign-in page) Each server listed under Not available says why: not connected, too old for the universal URL (an admin runs sudo aether-server update), or an invitation you have not joined
The edge sign-in page does not list your server Your GitHub account is not bound to a member there. Bind it (aether member identities) or use the <edge>/mcp/<server id> URL aether mcp prints
Cannot connect as your GitHub account: <account> is not a member of <server>; ... That GitHub account is not bound to a member. Sign in at the edge as the right account, or connect with a code
Cannot connect as your GitHub account: the edge's sign-in for it was already used., ... expired at <time> or ... was issued at <time>, and this server takes only sign-ins issued from <time>, 30s after it last started Start again from ChatGPT or Claude
Cannot connect as your GitHub account: the edge's sign-in for it was already opened in another browser. or ... this consent page was opened in another browser than the one that signed in at the edge. The page was opened or posted from a browser other than the one that chose the server. Start again from ChatGPT or Claude in one browser
The edge put its sign-in in the URL, where logs and browser history keep it, so it is refused. The server's edge speaks protocol 4, but something sent the old hand-off. Start again from ChatGPT or Claude

If an app asks you to sign in again, the connector was revoked or cut off. Connect again from the app; aether mcp prints the URL and a code if the page asks for one.

Security model

The connector acts as you through the tools of its scopes and nothing else. The edge decrypts connector traffic, because ChatGPT and Claude need a public certificate, so a compromised edge can read tool calls and act as you through a live token. security.md lists what each token allows and what cuts a connector off.