Skip to the content
docs

Running Cloudfield with a team

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 / Teams

One Cloudfield server can serve several people. Each person is a member with a role, and everyone's agents run side by side in the same workspaces (a workspace is one repository plus its settings). A solo setup is a team of one, so there is nothing to switch on: you add members.

You need a running server and a first member, who is its super admin. See quickstart.md. New terms are in the glossary.

Join the server

There are three ways to join. Pick the one that matches how your team reaches the server.

Method Use it when Who approves
Tailnet Everyone is on your Tailscale network An admin or super admin, once per person
Edge People sign in with GitHub through an edge (a relay that lets people reach the server without sharing a network) The invitation, then a device approval
Invite code A person has neither, and you can send a code Nobody: the code is the approval

Over a tailnet

The server must have tailnet sign-in on. aether-server setup turns it on when you answer yes to its tailnet question (install.md). The teammate joins your tailnet and sessions:

CODE
aether link my-server

Tailscale proves who they are, and the server adds them as a pending collaborator with no workspaces. aether link prints linked to <server> as <name> (collaborator, pending); an admin runs: aether member approve <member-id>. Until an admin does, their commands fail with membership pending admin approval; ask an admin to run: aether member approve <member-id>.

CODE
aether member list              # the PENDING column marks who waits
aether member approve mem-rbekp4h6fx

Start the server with --tailnet-auto-join to skip approval when your tailnet already is your team. networking.md covers tailnet identity and revocation.

Through an edge

An admin or super admin invites a teammate by GitHub login, or by the verified primary email of their GitHub account. --workspace names a workspace the teammate is granted on joining, by name or id, and repeats (Workspace access):

CODE
aether invite --github dana --role collaborator --workspace web --workspace api
aether invite --email dana@example.com --role viewer --workspace web

--role is viewer, collaborator (the default), admin or, from a super admin, super_admin. An admin may invite only a collaborator or viewer, into at least one workspace they own and only into workspaces they own; a super admin may invite any role into any workspaces, or none. The command prints an invite link of the form https://<edge host>/join/<server id>/<invitation id>#<secret>. It is shown once. In the dashboard, Members → Invite… shows it with Copy link. Send it to the teammate, who opens it and selects Join in the desktop app, or in a terminal runs:

CODE
aether login            # or aether login --json, for a script or coding agent
aether link '<invite link>'

What happens next depends on the server's edge-access policy (edge.md). Under approved-devices (the default), the teammate's device waits until an admin approves it from a Needs you card or the commands below, and aether link prints waiting for an admin of <server> to approve this device (<label>, <fingerprint>)…. Under account, signing in admits the device and creates the member at once.

An invitation expires after 7 days, and an invited login or email matches only within 24 hours of the teammate's last GitHub sign-in at the edge. If you see open this edge in a browser to confirm them, open any edge page to sign in again. List and revoke invitations with aether invite list and aether invite revoke <invitation-id>.

Error Meaning
<account> is invited to this server; open the invitation link the admin sent, or run: aether link <link> They ran aether link <server id> instead of using the link
the invitation link is not valid for this server: wrong, revoked or expired; ask the admin for a new one The link was used, revoked or expired

Joining creates the member and their grants together. A member who joins with no workspaces sees none until someone grants them one.

Approve devices

Each client install is a device with its own key. Under approved-devices, every new device waits for approval, a member's own second laptop included. Approve from the dashboard's Needs you card, or:

CODE
aether device list                         # yours; a super admin sees everyone's
aether device approve <code or device-id>
aether device revoke <device-id>
sudo aether-server device review           # on the server

aether device approve shows who the device would be admitted as and asks approve it? [y/N]. Check the member and role first: whoever holds an approved device gets that member's access. There is no flag that skips the question. Any answer other than y, or no answer on stdin, fails with device approve: not approved; a person must check the device shown above and confirm with y in their own terminal: aether device approve <code or device-id>, or approve it from the dashboard's Needs you card. If the only super admin has no approved device, the refusal includes a code, and they run sudo aether-server device approve <code> on the server. At most 10 devices wait per account.

By invite code

For someone with neither a tailnet nor a GitHub sign-in. An admin mints a one-time code, and the teammate redeems it, which registers their SSH key. The code carries the same --workspace grants as an invitation:

CODE
aether invite --ttl 3600 --workspace web   # seconds; default 86400
aether link my-server:2222 --invite <code> --name "Dana"

The member is a collaborator at once, because the code was the approval. A code stops working when the member who minted it stops being an admin or super admin.

One person can reach the server through a tailnet login, an SSH key and GitHub accounts. They join one member only through an explicit step, never by matching emails or names. Add a GitHub account to your own member with Profile → Sign-ins → Link a GitHub account or aether member link --github dana. Open the link it prints while signed in with that account, then approve the new device from your existing sign-in.

Someone who already became two members can merge them. Run aether member merge start on one sign-in, which prints a code valid for 10 minutes. On the other, run aether member merge <code> (options --keep <member id>, --keep-admin, --yes), then aether member merge accept back on the first. Both show what is discarded before you confirm. The survivor takes the other member's sessions, schedules, devices and accounts, and the lower of the two roles. The absorbed member's home moves to <data-dir>/merged/<merge id>/home and their private signing key to signing-key beside it. Both hold credentials, so remove the directory with sudo rm -r once nothing in it is needed. A merge is refused, with the reason, when either member is pending or has an unfinished session or terminal. It is also refused when the merged role would be below admin and either member owns workspaces: reassign them with aether workspace owner <workspace> <member-id>, or keep the admin role with --keep-admin. Nothing undoes a merge.

Remove access

aether member remove <id> deletes a member, their environment and their private signing key, and closes their connections. aether device revoke <id> refuses a device key everywhere. aether member unlink <member-id> github:<user id> unbinds one GitHub account, revokes the devices that signed in with it and deletes the connectors its sign-in authorized. aether invite revoke <id> kills a link.

aether member remove fails with in use while sessions or schedules still belong to the member. Delete those first. It is also refused while the member owns workspaces, with an error that names them and the command to reassign them (aether workspace owner, below). Only super admins remove members. Only a super admin runs aether member transfer <member id>; it makes another admin or super admin the server's owner at its edge.

Single sign-on

Cloudfield has no identity provider settings of its own: sign your tailnet in through yours, such as Okta, Google Workspace, Microsoft Entra ID or GitHub (Tailscale's providers), and have people join over the tailnet. Each such member is a login from your provider, and the tailnet-auto-join setting (install.md) admits them without approval. A user you share the server's machine with signs in through their own provider.

Removing someone in your provider stops new sign-ins, not devices already signed in. Those reach the tailnet until the user is suspended in Tailscale or their keys expire. Suspend them in the Tailscale admin console, or let user and group provisioning do it when you deactivate them in Okta, delete them in Microsoft Entra ID, or suspend them in Google Workspace.

That closes the tailnet path only. Their SSH key, approved devices (which also work on the direct SSH port), GitHub sign-ins at the edge and ChatGPT or Claude connectors stay open. Remove the member to close them all:

CODE
aether member list                 # their member id
aether member remove <member-id>   # deletes their SSH key, devices, GitHub sign-ins and connectors

It fails with in use until their sessions and schedules are gone (Remove access).

Roles

A member has one server role. Where that role applies depends on the workspace: a role is never wider than the workspaces the member owns or was granted (Workspace access).

Role Where In those workspaces
super_admin Every workspace Everything an admin does, in all of them. Also members, roles, aether server update and the release channel, run limits, the edge and audit history of everyone
admin Workspaces they own Everything: settings, budgets, templates, schedules, mirrors, delete, and granting members
admin Workspaces they were granted Acts as a collaborator
collaborator (default) Workspaces they were granted Launch sessions, push, use templates, set schedules, add memory notes; view, message, steer and stop others' sessions
viewer Workspaces they were granted Read the feed; view sessions; cannot launch

Steering a session means typing into its terminal, messaging its agent, answering its permission prompts and pausing or resuming it. Pushing means writing to the workspace's git repository. Everyone who joins is a collaborator unless invited otherwise, so teammates can message and stop each other's agents in a shared workspace with no setup. Every such act is recorded in the workspace timeline with who did it.

Only a super admin changes a role or removes a member. An admin may approve or deny a pending member or device only when it admits a member below admin, or is their own, and may list the sign-ins of a member below admin. Renaming, recoloring or setting the git identity of another member, revoking their approved device, unlinking their sign-in or revoking their connector is for that member and super admins only. An admin revokes only invitations they created. An approval code for a device you may not approve fails as an unknown code does, and another member's connector as an unknown connector id.

CODE
aether member role <id> super_admin|admin|collaborator|viewer
sudo aether-server member role <id> super_admin   # on the server

aether-server member role <member-id> <role> writes the role straight to the server's database, like aether-server device approve. Use it from a script or to restore a locked-out server. The role applies to connections that are already open: a demoted member's live attach drops with detached: you can no longer control this session. An approval, removal, role or owner change, grant, revocation or session limit change that was already running re-reads its caller's role as it writes, so a demotion landing first refuses it with aether: rpc error -32003: store: conflict: member <id> is no longer a super admin (or ... no longer an admin, ... no longer administers workspace <id>). Member approvals, removals and role changes, account shares and connector writes are kept in the audit history; aether audit shows yours, or everyone's to a super admin (connectors.md).

The last super admin cannot be removed or demoted. A member who owns workspaces cannot be removed or demoted below admin until a super admin reassigns the workspaces. Commands your role may not run in a workspace fail the way an unknown workspace does (below); a command no workspace can allow fails with aether: rpc error -32001: <method> requires the admin role.

After an upgrade

A server that predates workspace access migrates once, when it first starts the new version:

  • The earliest approved admin becomes the super admin and owns every existing workspace.
  • Every approved member, other admins included, keeps every workspace as a grant, so nobody loses access. Members still pending get no grants.
  • Other admins keep the admin role but administer no existing workspace: in one they don't own they act as a collaborator, with no settings, budget, grants or delete. The super admin hands each workspace to its admin with aether workspace owner <workspace> <member-id>, and trims access with aether workspace revoke.
  • Invitations and invite codes created before the upgrade carry no workspaces: whoever joins with one gets no grants until an owner or super admin grants them.

A server with no approved admin before the upgrade gets no super admin. Every member keeps their access, but nobody can administer the server until you promote an approved member on the server itself. Find their member id with aether member list from that member's own sign-in, then run:

CODE
sudo aether-server member role <member-id> super_admin

To limit who can control sessions:

CODE
aether protect <session>                                    # owner and admins only
aether workspace settings --message-others admins-only  # every member's sessions
aether workspace settings --message-others everyone     # the default

A refused member sees workspace restricts steer of others' sessions to their owner and admins. aether unprotect <session> lifts a protection. A lock marks a protected session in the sidebar, on the board and in the lanes, and closing one lists the protection among its close warnings.

Workspaces

A workspace is a repository plus its settings. Sessions, the activity feed, templates, schedules, costs and the budget all belong to one. A session and its shells use the launching member's saved image, or the server's standard image (environments.md).

An admin or super admin creates a workspace, and owns it. In the dashboard, open Manage workspaces from the workspace selector, select Add workspace, choose GitHub, pick a repository you can read and accept its first revision. From the CLI:

CODE
aether workspace import ~/code/myproject
aether workspace import https://github.com/acme/myproject
aether workspace add myproject [--base <branch>]

import and add refuse a name already in use and print its id. aether workspace list prints each workspace you reach with its OWNER and your ROLE there.

Each member links their own clone, which adds an aether git remote. aether workspace import <path> links a clone whose origin matches the workspace's publish destination; otherwise run aether link my-server --repo ~/code/myproject --workspace myproject. The client keeps one linked clone per workspace: linking another clone of it replaces the first, and aether status lists them.

Branches named aether/run-* belong to the server and cannot be force-pushed or deleted. Every other branch behaves like a normal git remote. aether pull <session> brings a session's branches into the linked clones.

Setting Default What it does
Base branch main New sessions branch from it. Set with --base at creation
Publish destination (Publish changes to) The origin of the first clone linked The git URL each session checkout gets as origin, where session branches are pushed for review
Source mirror Off (local-only) Follows an upstream repository read-only
Message-others policy everyone Whether collaborators can message and stop each other's sessions

A session can also check out other workspaces beside its own; see Working across repos. The launcher must reach every one of them.

A later clone that points elsewhere does not overwrite the publish destination. Change it on purpose; a change reaches new sessions only:

CODE
aether workspace origin --workspace myproject https://github.com/acme/myproject.git
aether workspace origin --workspace myproject --clear

A git@github.com: address is stored as its HTTPS form, because sessions can authenticate over HTTPS only.

Source mirror

A local-only workspace lets collaborators push the base branch directly. A mirror makes an upstream repository own it instead. The workspace's admin configures one:

CODE
aether workspace mirror configure --workspace myproject \
  --source https://github.com/acme/myproject.git --branch main --auth github
aether workspace mirror refresh --workspace myproject

--auth is public, github (your own GitHub login on the server, read access is enough) or deploy-key (Cloudfield prints a public key to add as a read-only deploy key). A new mirror starts pending: verify it and adopt its first revision before the first session. While it is pending, refresh, status and every refused launch print the exact aether workspace mirror adopt command for the observed revision. Fast-forward updates apply on their own. If upstream rewrote history, the base stays put until an admin reviews the candidate and sessions aether workspace mirror adopt --workspace myproject --generation <n> --commit <reviewed-sha> --yes. aether workspace mirror status shows where it stands.

Pushing a mirrored base branch is rejected. Update the upstream and refresh:

CODE
aether: rejected write to protected ref refs/heads/<base>: this mirrored base is owned by the upstream; use the configured upstream to update it

A scheduled session refreshes the mirror first and creates no session if that fails. See security.md.

Workspace access

A workspace has one owner, the admin or super admin who created it. A grant lets one member into one workspace, with the role they already have: a granted collaborator acts as a collaborator in it, a granted viewer as a viewer. A grant carries no role of its own, and a member who is neither owner nor granted cannot reach the workspace.

Role Reaches
super_admin Every workspace, as admin
admin Workspaces they own as admin; workspaces they were granted as collaborator
collaborator, viewer Workspaces they were granted
CODE
aether workspace access <workspace>               # the owner and every grant
aether workspace grant <workspace> <member-id>... # owner or super admin
aether workspace revoke <workspace> <member-id>
aether workspace owner <workspace> <member-id>    # super admin only

<workspace> is a name or an id. access lists who reaches the workspace; a super admin reaches every workspace without a grant, so none is listed. An admin grants and revokes collaborators and viewers in workspaces they own. A super admin grants any member into any workspace and changes its owner, which must be an admin or super admin. Revoking is refused while the member has a live session or a schedule in the workspace, counting a session handed off from them that still runs on their home or agent account. A live session whose home member loses the workspace another way, such as a role change, is stopped; one on a shared account whose owner loses it moves off that account. A git fetch or git push over SSH in progress stops when its member loses the workspace, with aether: git receive-pack: stopped: access ended: ... on stderr.

Invitations and invite codes carry --workspace grants (Join the server). The dashboard's Manage workspaces, in the sidebar above Members, shows each workspace's owner, and each row's Access button opens a searchable list of members to tick or untick; a super admin changes the owner there too.

Members see each other through workspaces. A super admin sees every member. Anyone else sees themselves, the super admins, and every member who owns, was granted or has a session in a workspace they reach, or whose account or home such a session uses; an admin also sees members waiting for approval. A member you do not see is absent from aether member list, device lists and attention. Naming them in aether workspace grant, aether account share, aether member identities or aether member unlink fails as for an id that never existed. An admin therefore grants only members they see: to bring in someone new, invite them with --workspace or ask a super admin to grant them.

What an unreachable workspace looks like

A workspace you cannot reach does not exist for you. It is absent from your workspace list, sessions, attention, insights, changes, search, memory, counts and the event feed. A command that names it, by id, fails exactly as for an id that never existed:

CODE
aether: rpc error -32000: store: not found

The same holds for git fetch and git push to its remote. This is on purpose: the error never says whether the workspace is real.

A session with an extra repository in a workspace you cannot reach does not exist for you either: it is absent from aether sessions, attention, the recent sessions in insights, the overlap column, watches and your event feed, aether timeline and aether changes, and a command that names it fails as above. Insights and cost totals still count it. A session's wait on a pull request whose repository no workspace has any more, because the origin it named was changed or cleared, and the wait's wake message, reach only super admins and the member whose session waits. Once a session is deleted, its remaining events reach only super admins, apart from its deletion notice, which reaches everyone who reached the session. Events about a member you do not see, such as a rename, a device change or a merge, are left out the same way.

Delete a workspace

The owner or a super admin runs aether workspace delete myproject --yes, which removes the workspace with its sessions, checkouts, transcripts, templates, budget and costs. Member accounts, local clones and the upstream repository stay. It never stops work: stop active sessions and remove schedules first. The error names what blocks it. A session in another workspace that mounted this one as an extra repository stays, and from then on only super admins see it.

Work together

Commands that depend on a workspace take --workspace <name-or-id> and default to the only workspace. With several, they insist: --workspace is required when more than one workspace exists. aether sessions lists sessions from every workspace.

Command What it does
aether sessions Every session you can see, colored by owner, with an overlap column. --needs-you lists only sessions that need you
aether who Who is online and which sessions they watch
aether attach [--read-only] <session> Attach to a session's terminal. Several people can attach at once
aether message <session> "..." Message a session's agent. It shows as a banner in your color
aether pause, resume, kill <session> Suspend, thaw or stop a session. The checkout and transcript survive a kill
aether sessions --needs-you Sessions waiting on you. aether sessions <session-id> shows what one needs and the command that answers it
aether timeline The workspace history. aether timeline <session-id> shows one session's. Filter with --member, --type, --limit. --jsonl exports
aether changes Session changes since a cursor: status, reports, mail, pull requests and lifecycle. --follow keeps polling (coordination.md)
aether cost --runs Token spend per member and run

The dashboard shows each session as Needs you, Finished: review the result, Working, Paused, Done or Failed. Needs you means something blocks the session that you can resolve, such as a permission or question or a stalled session of yours. A session whose agent reported success is Finished: review: it blocks nothing, so check its work before you close it. Everyone else sees that session as Working with "Waiting for Alice" (failure-handling.md).

Answer an agent's plan or permission prompt in the session's Chat view (Enhanced) or its terminal (Standard).

Hand off and finish sessions

aether handoff <session> <member> changes the session's owner and notifications at once, with no acceptance step. The agent account, cost attribution and the container's home stay the launcher's.

When a session is handed off or finishes, Cloudfield saves an evidence packet: the objective, base and final git revisions, changed files and a transcript copy. It records what Cloudfield observed and does not prove a command succeeded or that anyone reviewed the result. Packets expire after 30 days, and a session whose checkout exceeds 64 MiB gets no finish packet. If saving fails, Cloudfield keeps the checkout and transcript instead of deleting them.

CODE
aether close <session> --outcome merged|abandoned   # close a finished session after reviewing it
aether archive <session>                            # hide a finished session; unarchive restores it
aether delete <session>                             # stop it and remove its checkout and records

These need the same permission as stopping a session. A published session branch stays in the workspace repository after delete.

Task templates and schedules

A template is a saved launch: agent, task, mode, model, effort and parameters. An admin saves and deletes templates. Any collaborator launches them and sets schedules.

CODE
aether template save nightly-triage --agent claude --task "triage new issues" \
  [--mode standard|enhanced|background] [--model <model>] [--effort <level>] \
  [--param key=value] [--budget <usd>]
aether session --template nightly-triage [--param key=value]
aether schedule set nightly-triage "0 6 * * *"

--mode defaults to background, and --budget is an advisory per-session cost hint in USD. Use {{name}} in the task for a parameter. The dashboard's Templates page fills parameters inline before Launch and edits their defaults; any session's composer can insert a filled-in template as a draft. Cron is five-field syntax or an @descriptor, in UTC. A schedule that was due while the server was down waits for its next occurrence. aether template list|delete and aether schedule list|delete manage the rest. A --model the agent has no flag for fails with scheduler: agent "<agent>" has no model flag; launch it without a model, and an --effort it does not take fails with the error in harnesses.md.

Attribution

Each member has a color, shown on session rows, message banners and timeline dots. Change yours with aether member color <#rrggbb> and your display name under Profile → Display name. Every privileged act (message, stop, approve, hand off, change settings) is recorded in the timeline with who did it.

Set your git identity under Profile → Git identity, or aether member git --name "Dana Lee" --email dana@example.com. The agent in a session commits as the member who launched it, fixed when the container starts. Cloudfield's own commits (when a session finishes, is stopped or is recovered) use the session's current owner. With no identity set, commits use your display name and <member-id>@aether.local, which matches no GitHub account. Signed commits show Verified on GitHub only if the commit email is verified there (security.md).

Anyone who messages a session is added to its co-authors. Cloudfield's commits end with a Co-authored-by: line for each, and the session's agent finds the list in /run/aether/co-authors (coordination.md).

Conflict radar

When two sessions change the same file, aether sessions shows it in the OVERLAP column and the dashboard puts a warning on both cards that opens the shared files. It warns and does not block. Changes merged in from main do not count.

Agents in one workspace can also message each other. aether-internal status inside a session lists the sessions it can reach, and protection and the message-others policy limit this the same way. Every message appears in Activity as an Agent message (coordination.md).

Budgets

CODE
aether budget                                  # show
aether budget set --limit 25 --warn 20         # hard cap and soft warning, in USD
aether budget set --override                   # admit new sessions past the cap
aether budget set --override=false             # and stop again

An omitted flag keeps its value, and --limit 0 clears the budget. At the cap, new sessions are refused and running sessions finish. Claude Code reports spend in Background and Enhanced sessions, and OpenCode and omp in Enhanced sessions and Background sessions over ACP. An Enhanced session's spend counts as each turn ends. Every other session is unmetered, so totals are a floor. Deleting a session or a member keeps their spend in the totals. Only the workspace's admin sets a budget. The workspace's admins and super admins are notified once when spend reaches the warning and once at the cap; a budget change that puts spend back below either re-arms it.

Team memory

Sessions and members keep shared notes, and every new session is given the pinned ones. See memory.md.

Agent accounts

Each member signs in to each agent once, in their own environment (aether agent add <name>, then aether terminal). That home is mounted into every session they launch. A member's agent account is that vendor login and the subscription behind it. One member can let a collaborator launch sessions on theirs.

The owner turns on Share my account on the recipient's row in Members. The recipient picks the owner under New session → Account, below the agent. Each row there is marked You or Shared and says what a launch of the chosen agent on that account meets:

Status Meaning
<n>% used Launches; the fullest usage window, · stale when the last read failed
Ready Launches; no usage is measured for it
Sign in after launch Your own account has no login file for the agent; it launches and the agent asks you to sign in
Needs <owner>'s login The owner has no login for the agent; the launch is refused
Not installed, Your account only, Unavailable The launch is refused; hover Unavailable for the reason
Not checked The dashboard could not read the account's agents; hover for the error

Only your own account and accounts shared with you are listed, and the server refuses any other with permission denied: member <id> has not shared their account with you. From the CLI:

CODE
aether account share <member-id>      # owner
aether account list
aether session "triage the failures" --agent codex --account <owner-member-id>   # recipient
aether account revoke <member-id>     # owner

A session on a shared account belongs to whoever launched it and uses their image, home, git identity and GitHub login. The shared account supplies the agent login, the vendor quota and the cost attribution. The recipient needs neither the agent nor a login of their own, but must connect their own GitHub first, because the session pushes and opens pull requests as them. security.md lists exactly what is shared.

[!WARNING] omp shares the owner's whole ~/.omp/agent directory. A recipient's session can plant code that runs in the owner's own omp sessions with the owner's home, gh token and signing key. Share an omp account only with someone you would give your home to.

  • Sharing is one-way. Admins get no implicit access to anyone's account.
  • Revoking blocks new launches and moves the recipient's running sessions on the account to another account they may use, as usage fallback picks one. A session that cannot move fails with account share revoked: <owner> revoked access to their account; no other account can run <agent>, or another reason security.md lists.
  • An agent you defined with aether agent add runs only on your own account. A shared account shows it disabled as Your account only.
  • An owner with no login shows Needs <owner>'s login. A CLI launch fails with Grace is not logged in to claude: no login at ~/.claude/.credentials.json in their home; Grace logs in to claude in their own environment terminal.
  • Every member's containers mount their own Claude Code and Gemini login files in place, so a token refresh rewrites the file instead of replacing it. A server on Docker Engine older than 26.0 mounts none, and cannot share either. Recipients see the owner's refreshed login, and a session on a shared account keeps the owner's login mounted. A container started before v0.7.7-beta.1 can still replace its member's login file, which detaches the owner's login from that member's sessions on shared accounts: those sessions then sign in as the member. Restart such environments with Stop environment in Profile, or aether terminal stop, and relaunch such sessions.
  • Before the agent starts, the server checks that the container sees the owner's login file itself, not the recipient's own. Otherwise the launch, or the move to the account, fails with runtime: /root/.claude/.credentials.json in the container is inode <n>, not .claude/.credentials.json in <owner's home> (inode <m>); Docker lists the mount, so container runtime "<name>" did not apply it, or ...; Docker did not mount it (container runtime "<name>").
  • Shared accounts need Docker Engine 26.0 or newer on the server, or the launch fails with runtime: docker engine API "1.44" cannot mount a path beneath a member home; that needs API 1.45 (Docker Engine 26.0) or newer.

Usage fallback

When a claude or codex launch's account has used 95% or more of its subscription quota, Cloudfield starts the session on another account with usage left. Other agents always launch as requested, and so does an account whose usage cannot be read (an API-key login, signed out, or a vendor read over 3 seconds).

Candidates are your own account and every account shared with you whose owner is logged in to the agent. The one with the most usage left wins. In the launch dialog, Fallback → Fall back to another account turns it off and lists Fallback accounts, which you untick or reorder; an account a launch could not run on reads Skipped: and the reason. Your own account with no login file for the agent reads No saved login: a launch may still fall back to it, last, and the agent asks you to sign in, but a running session moves there only if an API key (ANTHROPIC_API_KEY, or CODEX_API_KEY in Background) signs the agent in. From the CLI:

CODE
# If Grace's account is exhausted, try Lin's, then your own
aether session "triage the failures" --agent claude --account <grace-member-id> \
  --fallback <lin-member-id>,<your-member-id>

# Launch on the requested account even when it is exhausted
aether session "triage the failures" --agent claude --no-fallback

Passing both flags fails with --fallback and --no-fallback cannot be used together. With no qualifying account the session launches on the requested one. A session that fell back stays owned by its launcher. Its header reads On <name>'s account (fallback), and aether sessions appends (fallback) to the ACCOUNT column.

A session also moves to another account mid-session when its agent reports the usage limit. Cloudfield starts a new container on the next account and resumes the agent's session there. The session keeps its ID, checkout and branch, but processes in the old container, terminals included, end. This works for Enhanced and Background sessions of claude and codex and Standard claude sessions (harnesses.md). Cost stays with the account that spent it. The account that ran out is not read again: the agent's report counts as exhausted. The move picks an account with usage left as a launch does; when none has, it tries one whose usage cannot be read, in the same order, since the session would stop anyway. Your own account qualifies there only with a login, or an API key the agent signs in with in that mode: ANTHROPIC_API_KEY for Claude, CODEX_API_KEY for a Background Codex run (per-agent setup). An account the session already used is never tried again: your own, or a shared one whose login the server confirmed in the session's sandbox. A shared account whose login never reached the container spent none of its quota, so it stays a candidate. A session that cannot move parks or fails with a reason that says why (Usage limit mid-session).

Saved launch choices

The server keeps one set of saved launch choices per member, so every device and the built-in assistant can start from the same ones. They hold the agent to preselect, each agent's mode and model (at most 32 agents, names up to 64 bytes with no control characters), the account to launch on, the fallback policy: automatic (every account you may launch on), ordered (at most 8 member IDs, your own allowed), or off, and the permission tier the launch form preselects. They hold no credentials and grant nothing. run.launch does not read them: a client fills a launch from them, and the launch is authorized as if nothing were saved. The built-in assistant's and the connectors' launch tools fill each field a launch leaves out from them (Launch options).

The dashboard's launch panel opens on them, the right half of New session launches the last agent, mode, model and permission tier at once, and the panel saves the agent, mode and model of each launch, and the permission tier as soon as you change it. It saves the account and fallback only when you select Save as my default under Account. Settings → Launch shows them, with each invalid choice and its reason, and changes or clears them.

launch.defaults.get returns your choices with a revision, which is 0 when none are saved. It also checks each choice now. invalid lists the choices a launch could not use, with the reason: an agent not installed on the account, an Enhanced mode that is not installed, or an account or fallback member who stopped sharing with you. unknown lists what it could not check:

  • a model with no current model list for that agent and account;
  • a model not in that list: it may be a full model ID for a listed alias, which launches accept;
  • a model for your own agent definition, which a launch passes only if the definition sets model arguments;
  • an agent with no login file, which still launches if an API key in the environment signs it in;
  • every saved agent, when the account's agents could not be listed.

Choices that fail a check stay saved until you replace them.

launch.defaults.set replaces all your choices (defaults) or deletes them (clear: true). It takes the revision you last read. If someone saved since then, it fails with code -32003, and the error's data holds the current choices. Saving an account or fallback member who has not shared with you fails with account_member_id: permission denied: member <id> has not shared their account with you. Both methods act only on the caller, admins included. A save records whether the built-in assistant or the member made it (source). The built-in assistant saves only after you approve a card that spells out every choice, naming the account and each fallback member.

A member merge keeps the survivor's saved choices. Any account or fallback member that names the absorbed member, in anyone's choices, is moved to the survivor, and those choices get a new revision.

Subsessions

An agent can start a subsession: a session with a completely fresh context on any agent and model you have installed, such as Codex reviewing what Claude wrote. A subsession can orchestrate its own subagents. Agents keep most tasks in one session, split across their own subagents or workflows, and start a subsession only for a large, independent stream of work that needs its own branch or pull request, would run for hours, or needs another agent, model, or harness, and whenever you ask for subsessions. A subsession of the parent's agent starts on the parent's account, so a session you launched on an account shared with you delegates on it too; any other agent starts on your own account. A session handed to you refuses subsessions, because it still runs the previous owner's agent on their home; launch a session of your own to use them. The agent can pick your account or any account shared with you whose owner reaches the session's workspaces instead. The subsession appears under its parent in the dashboard, with its purpose, agent, model, account and state, and you open, message, take over or stop it like any session. Its result reaches the parent's inbox, as does a notice when it has sat idle or waiting for over an hour, or stopped on an error such as a signed-out login for a minute, so the parent can wake or stop it. Its success or failure is for the parent alone: it never shows as Needs you or Finished: review and never notifies you, though its requests of a person still do (failure-handling.md). The agent commands are in coordination.md.

Subsessions go one level deep: a subsession cannot start subsessions. A parent must be a Standard or Enhanced session that wakes when mail arrives; subsession start from a Standard session of an agent with no idle wake is refused with <agent> in Standard mode has no idle wake; start it in Enhanced. A Background session cannot start subsessions.

Turn subsessions off

Subsessions are on for every Standard or Enhanced session you own. Settings → Subsessions or:

CODE
aether subsessions off                         # every session you own
aether subsessions on
aether session "fix the login bug" --agent claude --children off   # this session only

Choose the agents subsessions use

Subsessions may use every agent you have installed, on your own account and on each account shared with you. To keep them off an agent you do not want, or an account whose subscription no longer works, open Subsession agents under the Subsessions switch in the launch panel, or in Settings → Subsessions, and untick it. An agent available on several accounts lists each account under it; unticking the agent turns it off on every account, those shared with you later included. An agent on one account is one row: unticking it on your own account turns the agent off everywhere, on a teammate's only that account. Each change is saved at once and applies to every session you own, however it was launched. From the CLI:

CODE
aether subsessions                                        # what is on and off
aether subsessions off --agent codex                      # on every account
aether subsessions off --agent claude --account <member-id>
aether subsessions on --agent codex

An agent's subsession start on a choice you turned off fails with -32001 claude on <name>'s account is off for subsessions in the owner's settings ..., subsession options lists it as off, and a subsession queued before you turned its choice off is refused when its turn comes. A subsession's usage fallback, at launch or while it runs, never moves it onto an account you turned its agent off on, even one turned off after it started.

A subsession uses its parent's launch fallback policy: when its Claude or Codex account has used 95% of its quota, the subsession moves to the account with the most usage left among yours and those shared with you, as usage fallback does for every launch, unless the parent was launched with --no-fallback. The agent and model never change.

Allow subsessions in a session's More menu, or the Subsessions switch in the launch panel, allows or stops them for that one session without changing your setting. Only the session's owner allows it, and a handoff to another member voids it. An admin can turn it off. Handing a session to another member detaches it from its parent and from its subsessions, so no lineage spans two owners.

The quick-launch button beside New session launches your last agent again with no task, and always allows subsessions for that session.

When a parent is closed (merged, abandoned, or completed and accepted), its subsessions are closed with it: finished ones are relabeled the same way and working ones are stopped first. A subsession its parent cancels ends completed with the reason stopped by parent session <id>.

Limits and usage

A workspace admin sets how many subsessions each parent may have busy at once:

CODE
aether workspace settings --child-max-live 8

--child-max-live (default 8, at most 64) counts a parent's busy subsessions; more wait in a queue and start as slots free, oldest first. A subsession that reported or waits on a human holds no slot. A queued subsession is cancelled with its parent. Every subsession is also admitted against the workspace budget when it is queued and when it starts.

Each subsession's spend counts once, on the account that paid. aether subsessions <session-id> and the parent's Subsessions section add up the parent and its subsessions, split by account. A session that reports no cost (Codex, Gemini, pi) is counted as unmetered, so totals read "at least".

  • A budget admits sessions; it does not stop running ones. A parent can pass the cap by what its live subsessions spend.
  • A parked parent woken by other mail can work beside its busy subsessions, so it can briefly exceed --child-max-live.
  • A subsession gets the workspace's environment and secrets like any session of yours, but not its parent's transcript. It works in the parent's repositories, extra --repo ones included, from the parent's last commit, and inherits the parent's permission tier.
  • Deleting a subsession takes its spend out of the parent's total; the workspace totals and aether cost keep it.
  • Turning subsessions off stops queued subsessions from starting; running ones continue. Kill them from the parent's Subsessions section or with aether kill <session-id>.

Limits

  • Roles are viewer, collaborator, admin and super admin. There are no custom roles, and a grant has no role of its own.
  • The permissive default lets any collaborator stop any session. Use aether protect or --message-others admins-only to narrow it.
  • A session's extra repos (aether session --repo) share its primary workspace's environment, account and budget. Templates take one workspace.
  • Evidence packets expire after 30 days.
  • A merge of two members cannot be undone.