The assistant is a chat panel in the dashboard where you ask Cloudfield for things in plain language: "what's the status of my sessions?", "launch a session to fix the flaky login test", "install Rust in my environment". It acts with your permissions and asks before it launches, messages or stops a session, or saves your environment, unless you turn on auto-approval.
The assistant is not a session. It is an Enhanced session of Claude Code or Codex with a sign-in of its own, which you make once for it. Its usage counts against the account you sign it in to. It works before you have a workspace.
Where it runs
Each member's assistant runs in a sandbox of its own, created from the
server's standard image: the container aether-assistant-<member>, or with
session-runtime vm the VM unit aether-vm-assistant-<member id>.service.
Your sessions and your environment (the persistent sandbox
aether terminal opens) cannot see it:
- Its home is
<data>/assistant/<member>/homeon the server. It mounts nothing from your home or any other member's: noCLAUDE.md,AGENTS.md,~/.claude,~/.codex,~/.local/binand no agent login. - Its working directory is
/assistant, which holds the server's instructions and is read-only. - Its Enhanced adapter is in
<data>/assistant/<member>/install/<agent>, mounted read-only under/opt/aether-assistantand first in itsPATH. /etc/claude-codeand/etc/codex, where the agents read managed settings, are empty and read-only.- Claude Code's auto-memory is off for it.
Each start of the assistant replaces its container, so nothing the agent
changed outside its home survives. In the home it keeps only the sign-in file
and the files that resume the conversation: ~/.claude/projects for Claude
Code; ~/.codex/sessions and archived_sessions for Codex. Settings, hooks,
instructions, MCP servers, skills, memories and Codex's session_index.jsonl
and state_*.sqlite files are deleted, and ~/.claude.json is written again
with only the onboarding flag.
The sign-in file must hold only what a sign-in writes. Claude Code's
.credentials.json keeps claudeAiOauth; Codex's auth.json keeps
auth_mode (chatgpt or apikey), OPENAI_API_KEY, tokens and
last_refresh. Anything else, such as a gateway URL that would receive your
prompts, is removed, and that start fails with the keys it removed. Retry
starts with the rest. A sign-in file over 64 KiB is deleted.
On every start the server itself checks the sign-in with the vendor before
the container starts. It refreshes the token at the vendor's sign-in service
(platform.claude.com for Claude Code, auth.openai.com for Codex), writes the
new tokens back into the home, and asks which account they belong to: Claude
Code's profile endpoint at api.anthropic.com names the account and
organization, and Codex's new tokens name the ChatGPT account. A Codex API-key
sign-in is not refreshed; its key is the identity. The first start of either
agent after you sign in records that account outside the home, before any
agent runs; one that cannot be verified then leaves that agent not signed in.
Every later start must find the same account, or fails with the assistant's sign-in changed since you signed in. Sign in again.
So the assistant cannot start without reaching the vendor: when it is
unreachable or answers with an error, the start fails with couldn't verify the assistant's sign-in with <vendor>: ... and the sign-in stays. When the
vendor refuses the refresh token, the agent is no longer signed in. A server
that stops between refreshing and writing the new tokens back leaves a used
refresh token, so the next start asks you to sign in again.
On the first start, and after a server upgrade that pins a newer adapter, the
panel shows Installing while a short-lived container,
aether-assistant-install-<member>, runs npm install of the pinned adapter
into that directory. It needs network access to the npm registry. The adapter
carries the agent itself: the Claude Code binary of its Agent SDK, or the Codex
version Cloudfield pins with the adapter. Neither updates on its own; both move
when a server upgrade pins a newer version.
Open it
- Select Assistant in the sidebar next to New session, in the top bar when the sidebar is hidden, or the Assistant tab on a phone. A dot on it means an action waits for your approval.
- Press
Ctrl+Shift+Space(⌘Shift+Spaceon macOS), even while a text field or a terminal has focus. - Run Ask Cloudfield from the command palette.
Viewers do not see the assistant. On a wide screen the panel docks on the right
and can be resized. On a narrow window it floats over the page and Esc closes
it. On a phone it is a side sheet. Closing it keeps your unsent message.
First use
With no ready agent the panel shows Needs setup and lists Claude Code and
Codex. An agent is ready when you signed it in for the assistant; a sign-in in
your environment does not count, because your sessions can change it. A row that
is not ready says Not signed in for the assistant and has Sign in.
The first time you open the panel, while no agent has ever been signed in for
the assistant, the panel starts the sign-in of the first agent the server
lists, Claude Code before Codex. It never starts one on its own again: the
server reports sign_in_recorded in the assistant status once any agent's
sign-in has begun (<data>/assistant/<member>/signin/started, kept when a
sign-in is abandoned or forgotten), and the dashboard starts at most one per
page load.
Otherwise select Sign in on a row.
The sign-in runs in the assistant's container: claude-agent-acp --cli auth login for Claude Code, or codex login --device-auth for Codex. It installs
the adapter first if needed. The panel reads the sign-in's output and shows:
- Claude Code: Open Claude sign-in, the URL the sign-in printed, and a Paste the code field that types the code the page shows into the sign-in, followed by Enter.
- Codex: Open Codex sign-in and the one-time code to enter there, with a copy button.
The button opens only a URL on the vendor's own hosts (claude.com,
claude.ai, anthropic.com; openai.com, chatgpt.com), the newest one the
sign-in printed. After you send a code the terminal opens, since the sign-in
reports only there whether the code worked.
Show terminal shows the sign-in's own terminal; when the sign-in exits or cannot start, the panel shows the terminal and the real error. In Settings > Assistant > Sign-in the terminal shows from the start.
Starting a sign-in deletes that agent's earlier sign-in, so what the server records is what the sign-in writes. The sign-in is written to the assistant's home only. Starting it stops a running assistant; the next prompt starts it again, and a prompt sent while the sign-in runs fails until it exits. Select Done when it exits.
Cloudfield checks only that the sign-in file exists, not that it still works. When the sign-in expires or you want another account, use **Settings > Assistant
Sign-in > Sign in again**.
After sign-in the panel asks once How should your assistant act?: Ask before acting (recommended) keeps approval cards, and Act without asking turns on auto-approval, with its warning shown under the button. Either answer is stored with your settings; a member who already set auto-approval, from Settings or the CLI, or answered the suggestion to turn it on, is not asked.
Same account as your sessions
Once the first start has recorded the assistant's account, the panel's empty
conversation and Settings > Assistant > Sign-in compare it with the login
your sessions use: ~/.claude/.credentials.json and ~/.codex/auth.json in
your environment's home (assistant.account). For Claude Code the server sends
that file's access token to the profile endpoint the start uses and compares
the account and organization; for Codex it reads the ChatGPT account from the
file's token claims, with no network call. The line reads one of:
Same Claude account as your sessions, with the email when the profile names one.Your sessions use another Claude account (account <uuid>, organization <uuid>, <email>), or for Codex(ChatGPT account <id>)or(an API key). Codex compares the ChatGPT account only; the API key a ChatGPT login holds is its own.Can't compare: your environment's Claude token is expired. Start a session to refresh it. Codex has no such case, because its claims are read without the vendor.Can't compare with your sessions' <vendor> account: <error>, for exampleyour environment has no ~/.codex/auth.json, or the profile endpoint's answer.
The check only reads the file. It never refreshes, writes, or locks it, and the refresh token stays where it is. The result is information only: it gates no start, and the assistant's own recorded account stays the one every start checks. Your sessions can rewrite the environment's login, so a match says only what the file holds now. A session on a shared account uses the owner's login instead of yours; the check reads yours.
The first conversation uses the first ready agent, Claude Code before Codex. A
conversation keeps its agent, because another agent cannot continue it. If that
agent stops being ready, a prompt fails with, for example, Claude Code is not ready: Not signed in for the assistant; sign in again or start with another agent. Sign in again, or select New conversation, which picks the first
ready agent.
What it can do
The assistant can do what you can do through the dashboard and nothing more. It can also read Cloudfield's own guides, so it can explain features of the server you run.
| What | Examples | Asks first? |
|---|---|---|
| Read | List sessions, workspaces and agents. Read one session and its conversation. See your remaining agent quota and your environment's state. Search and show team memory notes. | No |
| Pause and resume | Pause or resume a session | No |
| Launch a session | Start a session with a workspace, agent and task | Yes |
| Message a session | Send a message to a session's agent | Yes |
| Watch | Watch a session or pull request, change or pause a watch | No; Yes, even with auto-approval, when the watch relays notices into sessions (relay_to), except to pause it |
| Stop or close a session | Stop a session, or close it as merged or abandoned | Yes |
| Save your environment | Save it as the image new sessions and terminals start from | Yes |
| Session lifecycle | Relaunch a stopped session, switch its mode, protect or archive it, hand it to a teammate | Yes |
| Open and merge | Open or merge a session's pull request | Yes |
| Team memory | Add a note, pin or unpin one; it cannot remove notes | Yes |
Asked "what is left", "continue this" or "did we ship?", the assistant reads the session with its progress evidence and answers requested, implemented, reviewed, merged, released and deployed on separate lines, each with its source and time, or "unknown" when Cloudfield has no source, as for releases and deployments. An agent's success report alone is not proof. "Continue" never repeats a launch, message or merge; the assistant proposes the next step and launches only when you ask.
Pausing and resuming a session take effect at once. The session's events name you as the actor. After each action the assistant says what it did, to which session, and the result.
An approved message reaches the agent at once when you control the session, or when it is your own session and no one controls it. Otherwise it waits about 45 seconds for the member in control to approve or deny it.
Installing a toolchain or editing a file is not a Cloudfield action. The assistant does it in its own shell in your environment, then offers to save the environment.
What a launch's task holds
A question about how something works, an idea or pasted text never launches
anything; the assistant answers or discusses it and offers a launch. "Can you
fix the login test?" is a request for work, not a question. When you ask for
work, the session's task is your request in your meaning: the goal, every
constraint and must-not you gave ("do not touch billing", "research only"), the
names, ids and numbers you used, the workspace, branch, session, pull request or
error you pointed at, and the style and review expectations you saved. It adds
no features, tests, docs, merges, pushes or constraints you did not ask for; it
suggests them in chat instead. Each guess it had to make, such as which branch
you meant, appears in the task as a line starting Assumption:, and its reply
lists them and offers to show or edit the task.
The assistant launches a clear request without asking "shall I?" first; the approval card, or the transcript under auto-approval, shows the task. It asks one short question only when the goal, the workspace or a must-not is unclear. What you say in the message beats launch picks, which beat saved defaults, which beat what you used before. It uses the account you chose or saved, without asking again, while launch options still show it as usable (on a server without launch options, only an account you named, else your own), and says which account the session used and any fallback it took. When a saved agent, model or account is no longer usable, it says why and asks instead of launching on another.
What it sees
Each message carries a short description of what your dashboard shows, so "why is this stuck?" works without ids: the page you are on, the workspace and run, the open session view, the open file's path (never its contents), the last 8 pages you visited, and the mode and model you last launched each agent with from this browser while signed in as you (up to 4, newest first). It never holds titles, file contents, drafts, terminal text or secrets. The assistant launches with those choices unless your message names others.
The page is pinned when you start typing. If you move to another session or page before sending, the panel asks You moved to Ship the docs. Ask about: with both pages, and sends nothing until you pick one.
To point a message at something specific, use Fix this on a failed session,
the button beside a failing check or beside the pull request number in a session's
header, or the session menu's
Ask the assistant to fix this session and Ask the assistant why this is
stuck. Each opens the panel with that session, check or pull request
attached and a short draft to edit; nothing is sent until you press Send. The
attachment holds only ids and names, such as acme/api#42 · check lint; the
assistant reads the details with its tools.
Above the message box, a chip names each thing the message is about. Remove one with its x, or Delete or Backspace. Removing the page stops the assistant reading the page between messages until you send or add it back; a message sent right after waits until the server has forgotten it. Inspect lists every field the next message sends, and Raw JSON shows the exact payload. Clear Share the page I am on with the assistant there to stop sending the page; things you attached are still sent. The choice is saved for you on every device.
The view a message carries is the one the assistant uses for that turn until you open another page. Before acting on a session it resolves the target from ids you wrote, then the page, then recent pages, and asks when more than one fits or you moved away from the session it last discussed. Only this assistant sees your page; assistants connected from outside Cloudfield, such as ChatGPT, do not.
Approve an action
An action that asks waits for you. The panel shows a card, Approve this action?, with a one-sentence summary, the exact parameters and when it expires:
Launch claude (acp) in api: "Fix the flaky login test"
Stop session run-8x2... ("Fix flaky login test")
Save your environment as a new image; new sessions and terminals start from itA launch card instead lists what starts: the kind, workspace, agent with model
and mode, the effort when set, the permission tier, the account, the fallback when that account's usage runs out, the
task, and how you hear back. Its title names the
permission tier when the launch sets one, from
your request or your saved choices, as in Launch claude (acp) in api, permission root, and the model and effort when the launch sets them. A template launch's card shows the whole task its
parameters fill in. When the assistant gives a one-line reason for a launch,
the card shows it as a Reason row above the rest. The assistant fills what you did not say from
your saved launch choices: From your saved
defaults names each choice that came from them, Saved mode not used (or
agent, fallback account) gives the reason a saved one was skipped, such as an
Enhanced mode not installed on that account, and Saved model not checked
says why a saved model could not be checked on the launch's account. A saved account a
teammate no longer shares with you fails the launch with the server's reason
rather than starting it on your own. With nothing saved, the assistant
launches on your own account with automatic usage
fallback: if your account is nearly out of quota, the
session starts on an account shared with you. With auto-approval
on, such a launch still asks while any account is shared with you, even when
you saved automatic fallback: it also covers accounts shared after you saved
it. One that names its account or its fallback order or sets no fallback, in
the request or in your saved choices, passes without a card. For automatic
fallback on one launch while you saved an order or no fallback, ask for it:
the assistant launches with saved_defaults: "ignore" and the other choices
spelled out.
When you ask it to keep a choice for next time ("from now on use codex"), the
assistant saves it with aether_save_launch_defaults, behind a card that
spells out every saved choice; a choice for one launch is never saved. The
launch dialog and Settings → Launch show the same choices.
Approve runs it. Decline or no answer before the card expires fails
the action with the reason, for example run.kill was not approved: the member declined this action. The assistant is told to report the failure and not
retry. The assistant cannot approve for you.
A card outlives the turn that raised it. The server stores it with the exact
call, so it shows after a reload, on your phone or desktop, after a server
restart and while the assistant itself needs sign-in, and any of them can
decide it (assistant.confirm); the first decision wins, and a second gets
assistant: no such pending confirmation. Its
push notification carries Review…, which opens the card, and Decline
where the device shows them (watches.md); only
the card itself approves.
- A card from a turn you started in Cloudfield keeps the call waiting for 10 minutes; approving it in that time hands the result to the assistant. Stop, the turn ending or the tool call hanging up stops the wait but leaves the card open until it expires.
- A card from a connector turn (ChatGPT, Claude) does not wait: the call
returns
Waiting for approval as card <id>; ...at once and the card stays open for 24 hours. In a connector turn, a call the connector's scopes do not cover always shows a card, even with auto-approval on. - The same call asked again while its card is open shares that card.
- Approving a card whose call no longer waits makes the server run it with the stored parameters, as you. It first builds the card again; when it would read differently, for example the session changed owner or the template changed, the card fails with what it reads now and nothing runs. The outcome is written into the conversation; the assistant is not woken.
- Each card runs at most once. A run cut off by a server restart is recorded
as
Failed: the server restarted while it ran; check before retrying, and is not run again. - New conversation withdraws every open card.
The card's chip names a turn that did not come from the dashboard, such as
via ChatGPT for a turn a connector started with
aether_ask_assistant. That connector can
also decide the card with aether_decide_assistant_card, by echoing its text. An approved card reads Approved, running… until its
outcome is in the conversation.
Every action is recorded in the transcript. The approval is written before the action runs; if it cannot be written, the action does not run. The outcome follows when the call returns:
| Record | When |
|---|---|
Approved: <summary> |
You approved the card |
Auto-approved: <summary> |
Auto-approval passed it |
Auto-approved by rule <id>: <summary> |
One of your approval rules passed it |
Declined, Expired, Withdrawn: <summary> |
You declined, did not answer before the card expired, or a new conversation withdrew it. Nothing ran |
Done: <summary> |
It succeeded, with the session it launched |
Failed: <summary> |
The server refused it, the card changed before it ran, the server restarted while it ran, or the approval could not be read or counted, with the exact error. In the last three cases nothing ran, or you check whether it did |
Pausing and resuming are recorded as Done or Failed without an approval.
Each record carries the target's session and workspace id, and the owner when the
session is another member's; the protocol reference gives the
fields. Resetting the conversation drops the records of actions still in
flight instead of writing them into the new one.
Approval rules
A card that could become a rule shows four buttons. The third is the server's wording of exactly what the rule covers:
Launch claude (acp) in api, no fallback: "Fix the flaky login test"
[Decline] [Approve]
[Always approve launches of Claude Code (Enhanced) in api on your account, permission default, no fallback, for any task]
[Approve everything from now on]Always approve … approves the card and saves the rule. Approve everything from now on approves the card, then asks to confirm turning on auto-approval; it is not shown while auto-approval is on. A later card with the same key passes without asking and is recorded as `Auto-approved by rule <id>:
| Card | The rule's key |
|---|---|
run.launch |
workspace, agent, account (yours or one named teammate's), mode, model, effort, permission tier, and whether fallback is off |
run.inject, run.kill |
workspace, your own sessions only |
env.save |
your environment |
The key is built by the server from the card's parameters, never from the task, the message or the assistant's reason, which a rule does not limit. An empty mode, model or effort is part of the key: the rule covers only launches that leave it to the agent's default.
These cards never offer a rule, and a rule never passes them:
- Messaging or stopping another member's session.
- A launch with automatic usage fallback while any account is shared with you, or with a fallback order, extra repositories, a subsession setting or resource limits.
- A card whose text holds one of your saved preferences.
- Everything auto-approval does not cover: template launches, merges, closes, handoffs, memory notes and pins, forgetting a preference, saving launch choices, and answering a session's question.
Only you create rules, by clicking Always approve on a card in the Cloudfield app. The assistant, its tool socket and connectors cannot create, list or revoke them.
Settings → Assistant → Approval rules lists each rule with its wording, the card it came from, when it was created and last used, and how many cards it passed. Revoke deletes it in one click and applies to the next card. The CLI does the same:
aether member assistant rules # list
aether member assistant rules --revoke <rule-id>rule-7k2m9q4xbd created 2026-11-03 14:02, 3 uses, last 2026-11-03 16:40
Always approve launches of Claude Code (Enhanced) in api on your account, permission default, for any task
from: Launch claude (acp) in api: "Fix the flaky login test"A rule whose workspace was removed, or whose teammate's account is no
longer shared with you, stops passing cards and is listed as Inactive: <reason>. Merging two members
keeps the survivor's rules and does not move the absorbed member's.
After you approve three cards of one kind in a row, the next card of that
kind highlights Always approve and says You approved this kind three times in a row.
See what it did
Each action appears in the conversation as a card. The card names the action
and its target ("Launched session on api with Claude Code", "Merged PR #42") and
shows its state: running, done, failed, declined by you, expired unanswered,
withdrawn by a new conversation, or did not finish. A
call waiting for your approval is one line above the approval card. It also
says whether you approved it or auto-approval passed it, and links to the session,
pull request or environment. A failure shows the server's error as is.
Retry adds Retry: <what it tried> to the message box for you to edit and
send. A launch card adds what started, such as run · api · Claude Code opus · your account. A session the assistant launched that is still going reads
Working in the background with how you hear back; it keeps running after
you close the panel. Reads fold
into one line, such as Read 3 sessions, that expands. The Actions button in
the panel header lists the conversation's actions, newest first.
Auto-approval
Settings → Assistant → Let the assistant act without asking lets the assistant launch sessions, message and stop your own sessions and save your environment without a card. It is off by default and applies only to your assistant. While it is on, the panel says Acts without asking. The dashboard asks you to confirm before turning it on. The CLI does not ask:
aether member assistant # show the setting
aether member assistant --auto-approve on
aether member assistant --auto-approve offauto-approve off: each action below waits for your approval on a card
covers launching sessions, messaging and stopping your own sessions, saving your environment
always asks messaging or stopping another member's session
not covered the assistant's own shell and file tools, which never ask- Messaging or stopping another member's session always asks, with the owner named on the card.
- A launch that names a teammate's shared account itself, to run on or in its fallback order, or uses the shared account you saved as your default, passes without a card; the transcript note names the account and its owner.
- A launch with automatic usage fallback while any account is shared with you always asks, since it may move to an account nobody chose, even when automatic is the fallback you saved.
- A change applies to the live session at once. The assistant cannot change the setting.
- Every auto-approved action is still recorded in the transcript as
Auto-approved: <summary>. If the note cannot be written, the action does not run.
[!WARNING] With auto-approval on, nothing checks a launch, a message to your own session or a save before it happens. Text the assistant reads from sessions, files and web pages can carry injected instructions. The assistant is told to treat it as data, and nothing enforces that. Any program in your environment can also call the assistant's tools and gets the same pass. See security.md.
After you approve three cards in a row that auto-approval would have passed, not all of one kind, the panel offers Skip approval cards for the assistant? when it is idle. Three of one kind highlight that kind's rule instead. Turn on auto-approval turns it on. Not now asks again in 7 days, then 30, then never. Don't suggest again stops it.
Shell and file tools never ask
The assistant's own shell and file tools run without asking, with or without
auto-approval. The session starts in the same mode Enhanced sessions use: Claude
Code bypassPermissions, Codex agent-full-access. Installing a tool, editing
a file or running a command in your environment needs no click. A question the
agent asks you still appears as a card.
Notifications
Cloudfield watches every session the assistant launches, relaunches or messages
for you: it
creates a watch with source assistant,
listed in Settings > Watches, where you pause it to stop the notices. If
the watch cannot be created, the conversation says so with the error. You do
not ask for updates. You are told when the session:
| Notice | When |
|---|---|
| Finished | The session's agent reported done, the session completed, failed or was stopped, or a member closed it as merged or abandoned |
| Needs input | The agent asks for a permission, or asks a question or a form in a session that is not Background |
| Needs attention | The session needs you with no question pending: it reports needs-input or blocked, hit a usage limit, had its turn interrupted, disconnected, or failed and you have not seen it. Waiting on agents, CI or a process never notifies. The reason is worded as in push notifications |
A notice appears in the assistant's transcript with a link to its watch, as a toast with a badge on the Assistant button, as an OS notification in the desktop app, and as a phone push. Your own sessions already push you when they need you, so the watch does not push those again (no double pushes). Each state is announced once; a need the session stood in when the assistant acted on it is not announced. The watch ends when the session reaches its final state, expires after 14 days, or goes with the session when it is deleted.
Conversations
Send with Enter (Shift+Enter inserts a newline). Stop cancels the turn in
progress; if the agent keeps going, press it again. If the server does not
answer within 10 seconds, Stop shows assistant.cancel got no answer within 10 seconds and can be pressed again. A message the server does not accept within
60 seconds shows assistant.prompt got no answer within 60 seconds and stays
in the box; Send retries it under the same idempotency key, so it runs at
most once.
The queue
A message sent while a turn runs is queued: the button reads Queue, and
the message shows at the end of the conversation, numbered under N queued,
run after this turn, until its turn starts. Queued messages run in that
order, each when the turn before it ends.
Stop cancels only the running turn; the next queued message then runs.
Remove takes a queued message off before it runs. At most 5 wait; a sixth
fails with assistant: 5 prompts are already queued; wait or remove one.
The queue is stored on the server, so it survives a reload and a restart. A
turn the server lost to a restart is marked Interrupted with the server restarted while this turn ran; it was not sent again, and is not rerun; the
waiting messages then run. A queued message that could not start shows
Not sent with the server's error, above the queued ones; Retry puts
its text back in the message box, once an agent is ready, and Dismiss
removes it. Each queued message names the door it came from. New conversation deletes the
queue with the conversation: waiting messages, and the stored text and
replies of earlier ones.
Every message records where it came from. A chip on each of the last 50 names any door other than the dashboard: from phone for the Android app, from desktop for the desktop app, from ChatGPT (connector) for a connector. The server stamps the origin from the connection that carried the message; the Cloudfield app only names which of its own clients it is, which labels the message and decides nothing. A connector origin is set only by the connector's own route, never by a request field.
There is one conversation per member. It survives page reloads and server restarts. If the agent stops, the next prompt starts it again. New conversation asks Start a new conversation?, then deletes the transcript, removes the assistant's container and deletes everything in its home but the sign-in files: sessions, history, todos, file history, shell snapshots and logs. The installed adapter is outside the home and stays. What the assistant already did stays done.
Earlier assistant state in your home
Before the assistant had its own container it ran in your environment, in
~/.aether/assistant, and kept its sessions in your home. That state, and the
login it borrowed from your home, are not moved, because any session could have
changed them. Delete the old state from aether terminal; the session
directory is named after your home's path, -root--aether-assistant when it
is /root:
rm -rf ~/.aether/assistant ~/.claude/projects/*--aether-assistantCodex sessions from that time are in ~/.codex/sessions together with your
sessions' sessions.
Preferences
A preference is a short instruction about how you work that you ask the assistant to remember, such as "remember that I prefer table output". Only you can read, change or forget your preferences; teammates, admins, your sessions and connected apps such as ChatGPT cannot reach them.
- Save one: say "remember", "from now on" or "always". The assistant
saves your own words from that message without a card, and the transcript
shows Saved or Updated with the text. A preference is at least 3
words and 12 characters and at most 500 characters; the assistant saves at
most 3 per message and you keep at most 200. Saving text you already keep
for the same workspace, or for all of them, fails with
already remembered as preference <id>. - What it can quote: only a session of whole words you typed in your latest
message, stored as you wrote them. It refuses paraphrases, anything
gitleaks flags as a secret, and text it treats as pasted: lines starting
with
>and the lines after them up to a blank line, fenced code blocks (up to a fence at least as long as the opening one, or to the end of the message), and lines indented by four columns or more, where a tab reaches the next multiple of four; an indented fence is such a line, not a fence. - See, edit and forget: Settings → Memory lists them. The assistant
can also forget one after you approve its card, even while preferences are
off or the conversation is temporary. Forgetting deletes the preference;
the assistant's next prompt tells it not to use the old text. If the
preference changes while its card waits, approving the card forgets
nothing and the call fails with
changed since you saw it. Undo on a Saved, Updated or Forgotten card restores the earlier text through Settings, so the preference then reads Added in Settings. It refuses, and says why, when the preference changed since the card. The Temporary chat switch appears only on servers that support it. - Turn off: switch off preferences in Settings → Memory
(
assistant.settingswithpreferences_enabled: false). The assistant then neither reads nor saves them, and each of your messages tells it not to use the preferences it read earlier in the conversation. A temporary conversation (assistant.settingswithtemporary: true) does the same until New conversation, which also deletes the agent's session files in the assistant's home, as it does for every conversation. - Precedence: your current message overrides a saved preference. A preference never changes a setting and never chooses an account, a fallback, a merge, a push or auto-approval. With auto-approval on, a launch or message whose text contains a saved preference still shows its card.
- Scope: a preference applies in all workspaces, or in one. A preference for one workspace takes the workspace of the page your message was sent from, which the message carries only while Share the page I am on with the assistant is on. It belongs to you on this server and is not synced to other servers.
The assistant never saves anything you did not ask it to, never imports your agent's own memory files or past conversations, and never stores pull request, CI or session state. What forgetting does not remove is listed in Privacy.
Limits
- One assistant per member, acting only for that member.
- It uses the account you signed it in to. Account sharing does not apply to it.
- Sending a prompt needs the permission to launch sessions (collaborator or admin).
- Nothing enforces that it treats text from sessions, files and web pages as data.
Troubleshooting
A failed start shows The assistant stopped with the error and Retry.
| Message | Fix |
|---|---|
assistant: no agent is ready; sign in to Claude Code or Codex for the assistant |
Sign in for the assistant |
scheduler: couldn't verify the assistant's sign-in with Anthropic: ... (or OpenAI) |
The server could not reach the vendor's sign-in service, or it answered with an error; the detail follows. Check the server's network access, then Retry |
scheduler: Anthropic answered 400 Bad Request: the sign-in service refused the assistant's sign-in. Sign in again |
The vendor refused the refresh token. Sign in again |
scheduler: not signed in for the assistant. Sign in for the assistant first |
No sign-in was recorded, or the sign-in wrote no usable file. Sign in |
scheduler: the assistant's sign-in changed since you signed in. Sign in again |
The sign-in file is not the one you made; only the assistant's own agent writes it. Sign in again |
scheduler: the assistant's sign-in held what Cloudfield does not keep, and it was removed: ... |
The keys follow the colon. Only the assistant's own agent writes that file. Retry, and sign in again if the agent then reports no sign-in |
scheduler: install Claude Code for the assistant exited 1: ... |
The adapter install failed; npm's output follows the colon. Fix the cause (often network access), then Retry |
assistant: 5 prompts are already queued; wait or remove one |
Five messages already wait. Remove one, or wait for the running turn |
the server restarted while this turn ran; it was not sent again |
The turn may have done part of its work. Check, then send it again |
assistant: open the claude session; stderr: ... |
The adapter failed to start. Read stderr, then Retry |
the member did not answer before the card expired |
The card timed out. Ask again |
The card changed after you approved it, so nothing was run. followed by You approved: ... and It now reads: ... |
The target changed while the card waited. Read the new text and ask again |
the server restarted while it ran; check before retrying |
The call may or may not have taken effect. Check the session before you ask again |
<method> was not approved: record the approval: <error> |
The approval could not be saved, so the action did not run. Try again |
the assistant is not configured on this server |
The server runs without the assistant |
assistant: the server is shutting down |
Try again after the restart |