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.
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. Underedge-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:
aether mcpInstall 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 ABCD-EFGH one use, expires in 10 minutes; paste it on the page that opens when you connect, if it asksThe 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):
- Open ChatGPT Plugins.
- Select the plus button, then Add custom MCP server.
- Name it
Aether, paste the URL fromaether mcpas the server URL, and choose OAuth. - Select Create as a plugin, then install it.
- 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):
- Free, Pro and Max: open Customize → Connectors, select Add custom
connector, name it
Aether, paste the URL fromaether mcp, leave Advanced settings empty and select Add. Free allows one custom connector. - 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.
- 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, oraether 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:
claude mcp add --transport http aether https://edge.onaether.dev/mcpThen 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:
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 CLITo 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, andmodeswith their dashboard names:tuiStandard,headlessBackground,acpEnhanced.accounts: the agent accounts you may launch on, your own first, then each one a teammate shared with you (Agent accounts). Each hasaccess(ownorshared),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_totalandaccounts_totalsay how many there are.- Usage is each provider's windows, labelled as the provider labels them, with
used_percentandresets_at. It is never money. An agent with no usage row has unknown usage. - Each agent has
modesa session may start in andrefusedwhen a launch on that account would be refused, such as an owner who is not signed in. fallback: with neitherfallback_account_member_idsnorno_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 itsversionandparams, every placeholder of its task withrequiredwhen it has no default (the defaults and tasks are underuntrusted); passversiontoaether_launch_sessionastemplate_versionto refuse a template changed since. Withmodels(an agent name) and optionallyaccount_member_id, that agent's models on that account, each anidto launch with and itsname, such asfableandFable 5.2, which the server caches.account_member_idwithoutmodelsis refused. When it lists none, launch withoutmodelfor the agent's default, or pass the id the agent takes. saved: your saved launch choices aslaunch.defaults.getreturns them, withinvalidandunknownlisting each choice a launch could not use or check, with the reason.saved_errorholds the error when they could not be read. Connectors can read them but not change them.server.versionandserver.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:
saved account mem-7k2m9q4xbd: permission denied: member mem-7k2m9q4xbd has not shared their account with you; pass account_member_id or clear itA 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_totalwhen there are more), as Cloudfield recorded it (source: "aether record", with thechecked_atof 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 hasnot_checked_live. A session closed as merged addsclosed_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),approvalsandchanges_requestedfrom the latest verdict of each reviewer,merge_stateandchecked_at. The checks belong to theprand head shown; when the pull request moved between the status and checks lookups,errorsays so. When GitHub cut the review list off,partialis set andapprovalsis left out, since a later verdict may be missing.report: the latest report'soutcomeandat, ornot in the last 100 reports.conflicts:success_with_failing_checks,success_with_pending_checks,success_with_changes_requestedandclosed_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:
connector: write call connector=con-7k2m9q4xbd member=mem-... method=run.launch target=ws-... result=okresult 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.
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 812SEQ 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 okYou 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:
aether mcp revoke con-7k2m9q4xbdThe 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-devicesand that device is not approved - its refresh token goes unused for 30 days (
aether mcpthen 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.