Skip to content

Profiles

A profile says what a session may use (tools, network, files, credentials, user settings) and where it runs. Remote clients, such as the iPhone app and the Wingman side panel, ask for a session by profile name; aimux holds each client to the profiles its client scope allows.

Profiles are v2 manifests. They replace the v1 profiles (aimux profile save, a provider, directory, model and mode under a name), which keep working until you migrate them.

Builtin profiles ship with aimux and cannot be edited. Your own are YAML files, one per profile, named <name>.yaml, in $AIMUX_PROFILE_DIR or, when that is unset, ~/.config/aimux/profiles. A missing folder means no user profiles. remote serve reads the folder each time it lists or resolves a profile, so a new file shows up without a restart.

A bad file is skipped and reported (one line on stderr per file, or in the remote serve log); the good ones still load. A file is refused when it:

  • has a field aimux does not know,
  • has a name that differs from its file name,
  • has the name of a builtin (builtin:<name> always reaches the builtin),
  • has no extends. User profiles must extend another profile; defining a new root is not supported yet.
name: my-notes
extends: builtin:work-readonly
tools: [wiki:readonly] # narrower than the parent's five sets
network: { default: deny, allow: [model, gateway] }
settings: { inherit_user: false }
FieldMeaning
nameMust equal the file name without .yaml. A profile that runs in a sandbox (runs: sandbox) gets the sandbox aimux-<name>, which must be lowercase ASCII letters and digits in dash-separated runs (no leading, trailing or doubled dash) and at most 19 characters (OpenShell’s limit), so the name is at most 13 characters; check, policy compilation and every session refuse another. A run profile has no sandbox of its own: its stages run under its roles’ profiles
extendsThe profile this one narrows: builtin:<name> or the name of another user profile
harnessThe agent harness; claude-code (the default for a root, and the only one with an adapter). A child cannot change it
modelprovider and name; a child may set either. For acp sessions, name (sonnet or opus) is the default when a request names no model
runsWhere it runs: host (the Mac itself, with your settings), acp (a no-tools agent session on the Wingman adapter), sandbox (an OpenShell sandbox), run (research-with-work: a planner and a writer under its roles, a reader always under the built-in research, and a query check aimux runs itself). Default host for a root
dirA working directory carried over from a v1 profile; not a permission
toolsExact tool names or reviewed sets such as jira:readonly; [] is none. A set whose server has no approved tools (none approved yet with aimux tools approve, its backend was down, or the name is misspelled) is left out and grants nothing; a profile whose sets all lack pins fails to compile
networkdefault (deny or allow) and allow, a list of model, gateway or web
filesread and write: paths the session may see or change
credentialsNames of credentials the session may use
settingsinherit_user: load your own harness settings (default false)
unsafe_patternstrue allows * and ? in tools; without it a pattern is rejected
rolesRole to profile name, for profiles that run several roles (research-with-work: planner: work-readonly, writer: page). Every target, and its own roles, must resolve and validate, and a target that runs in a sandbox must have a valid sandbox name. A missing target is refused with role <role>: profile <name> not found; a target that extends a missing profile, is invalid or has an invalid sandbox name is refused with its own error. Roles have a shape: a planner must run in a sandbox without web, a writer on the page engine (acp) with no tools and no web; another shape is refused naming the role (role writer: profile research runs sandbox, want acp). Only planner and writer are used by the run; other role names are not shaped or used. The planner’s turn also refuses a profile that compiles with web when it launches (profile_unavailable), so a profile edited after admission cannot give it the web; the client sees run_planner_failed, with profile_unavailable as the cause in the remote serve log. A cycle of roles between valid profiles is accepted. A child that sets roles replaces its parent’s whole map; one that leaves it out inherits it. Roles are checked where a profile is admitted: aimux profile check exits 1, and GET /v1/profiles leaves the profile out (its server log says why). aimux profile show, list, aimux sandbox status and doctor do not check roles. While a role is invalid, a turn already running finishes or can be cancelled, a later message to that session answers 403 profile_not_allowed, a message queued before the role broke ends in a turn_error naming the role, and a new session 400 unknown_profile

A child inherits every field of its parent and may only narrow it:

  • A list the child leaves out is inherited. A list it writes must be a subset of the parent’s (an empty list is always a subset).
  • network.default may not go from deny to allow.
  • settings.inherit_user may not go from false to true.
  • harness cannot change.
  • runs may only move toward more isolation: host, then acp, then sandbox. run stays run.

A child that widens is an error naming the profile and the field, for example child widens parent: profile "widener" adds "jira:readonly" to tools. Cycles and unknown parents are errors too.

Every resolved profile has a digest: sha256: and the hash of its canonical JSON (fixed field order, lists sorted). It changes whenever any resolved field does. Sessions and audit lines record it, and GET /v1/profiles shows it, so a client can tell that a profile changed since it last looked.

ProfileRunsToolsNetworkAvailable
basehostnonedeny, allow modelyes
pageacpnonedeny, allow modelyes
work-readonlysandboxwiki:readonly, jira:readonly, slack:readonly, google:readonly, gh:readonly (opt-in: used once you run aimux tools add cli gh and approve it)deny, allow model and gatewayyes
codinghostnone declaredallowyes
researchsandboxnonedeny, allow model and webyes
research-with-workrunnone (its stages run under its roles)deny, allow modelyes

research reaches the public web read only: WebSearch, and WebFetch with GET only on a reviewed list of top-level domains and apex hosts, with private addresses blocked. It has no tools and no gateway, so it holds no private data. research-with-work answers a question from your workspace and the web together, in four stages; the planner, reader and writer each run in their own child session, the check in aimux itself: a planner under its planner role (work-readonly: your private tools, no web) looks things up and proposes up to 5 public search queries; a heuristic check drops a query that looks like it carries private detail, naming only the reason; it catches the shapes below, not every leak. It folds look-alike dots and Unicode dashes to ASCII first and checks the query as written and percent-decoded once (a query that does not decode is dropped as encoding), then refuses a URL, an email, an IP, any dotted name of two or more labels whatever its suffix (a numeric version such as v1.2.3 is exempt; node.js is not), an issue key with any dash (RHAIENG-1234, RHAIENG 1234 with a key of 4 or more characters and a number of 4 or more digits, or in any case rhaieng-1234 when the number has 4 or more digits; and any key the planner saw (dashed in any case, or spaced with an upper-case key), matched in the query in any case, dashed or spaced; gpt-4, sha-256, TLS 1.3, HTTP 2 and RHEL 10 pass unless the planner saw them), a token, AWS access key id or credential (password=..., the password is ...), a UUID, high-entropy text, or 8 consecutive words, in the query or its decoded form, copied from the question, the page, the page’s earlier questions (the request’s prior, given or computed), the planner’s private notes or its tool calls and results. A span of fewer than 8 words, or the same words reordered, passes that last check: a known residual risk; a reader always under the built-in research profile (web only, no private data; a reader role is not used) answers the accepted queries and nothing else, and is skipped when none is accepted; a writer under its writer role (page: no tools, no web) writes the answer from the labeled results. Only the writer’s text reaches the client, with a progress notice per stage, and the answer’s turn_done carries the pages the reader fetched as its only links. It takes no image. Through the remote API, coding and base (runs: host) are listed with available: false and refused with 409 profile_not_available, since remote serve has no engine for them yet: start a host session without a profile instead. aimux profile list shows the manifest’s own available.

Builtins other than page are roots: they have no extends. base is the narrowest root, and page extends it. A user profile can extend any builtin and narrow it. Extending base or page gives a profile with no tools that can only stay as it is or move to a more isolated runs.

coding is the profile a session without a profile counts as: it runs on the Mac with your settings. Wingman is never allowed it.

A profile names tool sets such as google:readonly, never tool names. What a set contains is decided by review, in two files:

  • ~/.config/aimux/tool-sources.yaml holds the sources and the sets: for each set, its source and the tools you reviewed and allowed (package internal/toolreg; format in Tool sources). aimux setup (and aimux browser setup) writes the defaults, or migrates ~/.aimux/wingman/readonly.json once; so does the first start of aimux remote serve, which logs one line and renames the old file readonly.json.migrated. Pins made before (version 1) stay valid: nothing needs approving again. Add and remove sources with aimux tools add and aimux tools remove (below) rather than by hand.
  • ~/.aimux/tools/pins.json holds a pin for each approved tool (internal/toolgateway/pin.go). A pin is a sha256 over the tool’s name, input schema, output schema and annotations. The tool’s top-level description and title are left out, because backends reword them without changing what the tool does. The file is version 2: per source and tool it keeps hash, definition (the canonical JSON that was hashed, so a later change can be shown field by field), approved_at and source (the URL or notes folder the tool was listed from). A version 1 file (hashes only) is still read and is rewritten as version 2 on the next approve.

google:readonly resolves through the registry to its source, google, which is the server name, and to the tools the set lists that are also pinned for that server. wiki:readonly, which the built-in work-readonly asks for, falls back to notes:readonly when the registry defines no wiki:readonly. The gateway serves a tool only while its live definition still matches its pin. Three cases change the result:

  • A set the registry does not define, or dropped as malformed, is left out of the profile, as is a set none of whose tools is pinned: no endpoint, no tools, no token entry.
  • A set name that is not <name>:<kind> fails the compile.
  • A profile whose sets are all left out fails to compile, and the error says to run aimux tools status, then aimux tools approve; when the registry itself does not load, the error carries its reason (RegistrySets and Compile in internal/profile/compile.go).

Only aimux tools approve writes pins on the Mac; a client allowed to (Wingman by default) can also approve from its panel through POST /v1/tools/approve, and each such approval waits for you to click Approve in a dialog aimux shows on the Mac, naming the set, each tool and what changed (see Approving tools from a client). Three commands, each with --json:

CommandWhat it does
aimux tools statusLists the live tools of every source (read-only) and gives each set tool a status: active (pinned and unchanged), unpinned (never approved), changed (its definition differs from the approved one, or the backend no longer lists it), unavailable (the backend is down, or lists no such tool), source_changed (approved from another URL or notes folder than tool-sources.yaml now names; pins made before version 2 record no source and are never flagged) not_in_registry (pinned, but no set lists it) or new_on_server (a source offers it live, but no set lists it and no pin covers it, so a tool added on the server shows up; nothing grants it), with its approval time and the source’s authorship class (self, internal or outside) in the CLASS column (authorship in --json; - for a pin whose source is no longer in the registry). URLs compare as written: localhost and 127.0.0.1, or a trailing slash, count as a different source. It exits 0, and when something needs review it prints a Next: line on stderr; a pins file that does not parse is an error naming the file.
aimux tools diff [set|set/tool]Shows what approving would change: added, removed and changed tools (a source_changed tool is listed as changed, with a note naming the old and the new endpoint), and for a changed tool each field that differs (inputSchema.properties.q.type: "string" -> "number"). A tool pinned before version 2 has no stored definition, so the diff says so and shows the live definition only.
aimux tools approve <set|set/tool>... or --allPins the live definitions of the named tools only, and drops the pin of a tool the backend no longer lists. A source_changed tool is re-pinned with the current endpoint as its source. A tool already approved as it is live keeps its record (no new approved_at), so running it twice changes nothing; with nothing to change the file is not rewritten. A tool whose backend is down is skipped and the command exits non-zero naming it. Each tool it pins is printed with the short hash of the definition it pinned (approved jira:readonly/search 3f2a9c01b7e4; hash in --json). It pins what the source lists when you run it, which can differ from what aimux tools diff showed a moment before: diff prints each tool’s live hash ((live 3f2a9c01b7e4)), and --expect <hash> with one set/tool refuses, writing nothing, when the live definition is another one. The file is written atomically, mode 0600; the first write over a version 1 file keeps that file as pins.json.v1-backup for a downgrade. When the approved sets include a cli or http-openapi source, approve then updates aimux-tools from the new pins (policy and providers); if that update fails it exits 1 with the reason and the pins it wrote stay saved. Once the cause is fixed, running approve again updates the runner for a cli source (listing it ensures the runner); for an http-openapi source the gateway updates it on that source’s next call. A tool a source offers that no set lists (new_on_server) is added and pinned in one step: aimux tools approve <source>/<tool> --add-to-set <set> (exactly one <source>/<tool>, not with --all or --expect) prints its live definition (on stderr with --json, so stdout stays one JSON document), adds it to the set in tool-sources.yaml (keeping your comments), then pins exactly the definition it printed (a definition that changed in between is refused, and the set is put back); it warns when the tool does not declare readOnlyHint, since the set name promises read-only and the server does not, and refuses a set of another source or a tool the source does not offer now.

aimux browser setup approves nothing: it prints Tools need review (N): ... with the aimux tools diff and aimux tools approve commands to run, also on a first run with no pins at all. aimux browser setup --accept-pins approves every set’s live tools without review, for automation, and prints a warning line saying so.

aimux tools add and aimux tools remove edit tool-sources.yaml in place: every other entry and comment is kept (a broken entry too), the file is replaced atomically (mode 0600), and an edit that would not load cleanly is refused with nothing written. When the registry does not exist yet they first migrate readonly.json, or start from the defaults. Neither approves or changes a pin.

Terminal window
aimux tools add notes --folder ~/notes # source notes, set notes:readonly (wiki_search, wiki_read)
aimux tools add notes --folder ~/work/wiki --name work # source work, set work:readonly
aimux tools add mcp --name github --url http://127.0.0.1:8004/mcp --tools get_issue,list_pull_requests
aimux tools add cli gh # source gh, set gh:readonly (every gh_* command of the pack)
aimux tools add http --name api --spec /abs/openapi.yaml --base-url https://api.example.com/v1
aimux tools remove work # asks first on a terminal; --yes to skip
  • --authorship self|internal|outside sets who writes what the source returns (see Tool sources). The default is self for add notes and outside for add mcp; outside is written as no key. Any other value is an error and nothing is written.
  • add notes needs an existing folder (a relative path is made absolute). add mcp takes only an http or https URL on this Mac’s loopback (127.0.0.1, ::1 or localhost, no userinfo) and the exact tool names. Each adds the source and its set <name>:readonly, refuses a name the file already has as a source or set, and prints the next step on stderr: Next: aimux tools diff <name>:readonly, then aimux tools approve <name>:readonly. Until then the new tools are unpinned and hidden.
  • add cli <pack> takes a built-in pack (today gh; an unknown name lists the packs). The source is named after the pack unless --name is given, and the set holds every command of the pack as <pack>_<command> unless --tools a,b narrows it (each must be a pack command). add http --name N --spec <file> --base-url https://... stores the absolute path of an OpenAPI 3 file (nothing is copied; a relative path is refused) and an https base URL without userinfo, query or fragment, whose host is a plain public hostname (no IP literals, localhost, .internal or .local names, not the model host) and not a host a credentialed built-in pack uses (api.github.com: use aimux tools add cli gh). Its set holds every GET operation with an operationId as <name>_<operation id> (--tools narrows it), and the command prints how many it found, such as 3 GET operations, 2 others ignored; a spec with no such operation is refused. --credential is refused: credentialed HTTP sources are not supported yet. Both default to outside authorship. After the next-step line they print Then run aimux sandbox setup if the aimux-tools runner image or a provider is missing: cli and http tools run in the aimux-tools sandbox.
  • remove <source> removes the source and every set that names it. Without a terminal it needs --yes; --json gives schema_version, source, sets, path and kept_pins. Its pins stay in pins.json, unused: aimux tools status lists them as not_in_registry (“source … is not in tool-sources.yaml; the pin is kept but unused”), and adding the source back under the same name and endpoint reuses them.
  • The built-in work-readonly profile asks for wiki:readonly; with no set of that name it gets notes:readonly, so aimux tools add notes with the default name is all a new install needs for notes.
  • A pin detects schema changes; it does not prove a tool is read-only. Read-only comes from your review of what each tool in a set does. aimux tools approve prints this line every time.
  • A tool that changed since it was approved, or whose source now points elsewhere (source_changed), is hidden and refused until you approve it again.
  • remote serve rereads tool-sources.yaml and the pins on the next turn after either file changes (and once a minute regardless), so an approval or a registry edit takes effect on the next turn without a restart. Each turn compiles against one snapshot of both (logged as tool snapshot <version>). The gateway applies that snapshot before the turn’s token is used; if another turn’s refresh is still running, the gateway refuses what it has not applied yet, so a call gets at most what both the turn’s snapshot and the served one allow.
  • A session keeps working across edits: when its turn was granted under another snapshot than the gateway serves (older, or newer while the gateway’s refresh is still pending), the gateway refuses only the tools whose pin differs between the two or is missing from one; tools whose pins did not change stay usable. A registry edit restarts only the mcp-http and local-notes backends whose URL or folder changed or that were removed, each after its calls in flight finish. cli and http-openapi backends (the tool runner) restart on every new snapshot, a pin change included, because the runner’s policy is compiled from the snapshot.
  • A pins file that does not parse fails closed: no tool is granted or served, the gateway log names the file and the error, and aimux tools status reports it; fixing the file restores service on the next turn.
WallWhat it doesStrength
HarnessThe agent is only told about the allowed tools (--allowedTools, --strict-mcp-config)Cooperative
OpenShell policyMCP rules allow tools/call only for the pinned tool namesEnforced outside the agent
Read-only tool gateway on 127.0.0.1:7390Checks the session token and the pin on every callEnforced by aimux on the Mac

See Pinned tools for the setup output and what happens when a backend is down.

Terminal window
aimux profile list # builtins first, then yours: name, runs, available, digest
aimux profile show work-readonly # the resolved manifest and its digest
aimux profile check my-notes # resolve, validate, check the sandbox name and roles; exit 1 with the reason if any fails
aimux profile migrate # write each v1 profile as a v2 file

show prints the full digest; the list table shortens it to 12 characters. All four accept --json. check exits 1 when the profile does not resolve (its message names the field that widens), when its sandbox name is over 19 characters with the aimux- prefix or is not lowercase ASCII letters and digits in dash-separated runs (no leading, trailing or doubled dash), or when a role it names does not check (the message names the role and the cause). list prints a profile that does not resolve with - as its digest and the reason on stderr.

A profile that does not resolve (it widens its parent or extends a missing profile) stays in aimux profile list with empty runs, available: false and digest -; the reason is printed on stderr and the command still exits 0. aimux profile show and aimux profile check exit 1 with the reason. aimux profile check also exits 1 for a sandbox profile whose sandbox name is invalid (aimux-<name> must be lowercase ASCII letters and digits in dash-separated runs, with no leading, trailing or doubled dash, at most 19 characters; policy compilation refuses it too) and for a role that does not check (see roles above), naming the role and its cause.

check validates the manifest; it does not say whether the profile is available. A profile can check ok while available is false in list.

A profile that runs in a sandbox (runs: sandbox, such as research and work-readonly) gets one OpenShell sandbox, aimux-<profile>. aimux remote serve creates it on the profile’s first turn and, when the compiled policy changes (a new approval, an edited profile), updates its policy on the next turn. The digest of the policy it last applied is in ~/.aimux/sandboxes/<sandbox>.digest.

Terminal window
aimux sandbox status # both images, providers, gateway, the policy state of each available runs: sandbox profile and of the tool runner, sources left out of the runner; read-only
aimux sandbox status --json
aimux sandbox setup # build both images and create the providers when missing; creates no sandbox
aimux sandbox verify # egress checks inside aimux-work-readonly (was aimux browser verify)

For each sandboxed profile, status compiles the profile now (reading the registry and pins without writing) and compares that digest with the recorded one:

PolicyMeaning
currentThe sandbox runs the policy compiled now
stale (applies on next turn)The sandbox exists with another policy, or none recorded; the next turn applies the new one
missing (created on first use)No sandbox yet; the first turn creates it
unknown (gateway unreachable)The OpenShell gateway did not answer, so existence is unknown
error: ...The profile does not compile (for example no approved tools); the reason follows

After the profiles, status lists the tool runner aimux-tools as (tool runner), with the same states: its policy compiled from the approved cli and http-openapi sources, and the digest it last recorded. error: ... there means the runner does not compile at all (for example a pins file that does not parse), and its Next: line names the tool runner. cli tool calls (the gh pack) and http-openapi GET operations (as curl requests, only for operations whose pin matches) run in aimux-tools. A cli source whose provider is missing on the gateway, and an http-openapi source whose spec cannot be read, that names a credential, or whose base URL or paths the compiler refuses, are left out of the runner’s policy without putting the runner in error; aimux tools status shows why, and status lists each one under Left out of the tool runner: with its reason; status compiles the runner for the providers the gateway lists too, so the two digests match. The gateway restarts every cli and http-openapi backend on each new tool snapshot (an approval, a pins or registry edit), even when its source did not change: the runner’s policy is compiled from the snapshot’s pins, so the sandbox is ensured again before the next call. A cli backend also reads its binary’s version again; an http-openapi backend has no version probe and ensures the runner on its first call.

setup builds localhost/wingman-sandbox:2.1.319 and then the tool runner image localhost/aimux-tools:2.103.3 (that image plus a pinned gh), and creates the wingman-claude provider. aimux sandbox setup also creates the optional aimux-github provider (aimux setup only when an approved source needs it) (the gh tools’ GitHub token) only when the platform’s secret store has the item aimux-github: the Keychain on macOS, the Secret Service on Linux (through secret-tool). Otherwise, or on a platform with no supported store, it prints how to add a fine-grained, read-only token and carries on: a missing GitHub token is never a setup failure, but a store that cannot be read (locked, timed out) is.

Profiles that do not run in a sandbox (page runs over acp) and profiles that are not available are not listed. status never starts the gateway, builds, creates or changes anything, and always exits 0; each action it suggests is a Next: line on stderr (and in next with --json). The text output has two Image: lines, the sandbox image and the tool runner image localhost/aimux-tools:2.103.3 (present, missing or unknown; missing gets Next: aimux sandbox setup), and two Provider: lines, wingman-claude and the tool runner’s aimux-github (present, missing or unknown); a missing aimux-github gets a Next: aimux sandbox setup line only when an approved source needs it. The JSON has schema_version, image, runner_image, provider, runner_provider (with needed: an approved source needs it) and gateway (each name, status, error), runner_dropped (each source left out of the runner: source, reason), profiles (profile, sandbox, exists, which is null when the gateway is unreachable, state, recorded_digest, compiled_digest, error) and runner, the same fields for aimux-tools without profile.

The v1 commands save, get and delete still work on the old store, ~/.aimux/profiles.json, and each prints note: v1 profiles are replaced by ~/.config/aimux/profiles; run aimux profile migrate on stderr. list shows the v2 profiles only.

aimux profile migrate writes one file per v1 profile into the profile folder, extending builtin:base with runs: host and the old provider, directory and model. The v1 mode has no v2 equivalent (profiles v2 have no mode field yet) and is not carried; for each profile that had one, migrate prints warning: <name>: v1 mode "<mode>" is not carried; profiles v2 have no mode field yet on stderr. A file that already exists is skipped (skip <name>: <path> already exists), never overwritten, so the command is safe to repeat. A v1 profile named like a builtin is renamed <name>-v1 (then <name>-v1-2, and so on) and the rename is printed. With nothing to migrate it prints No v1 profiles to migrate.

A profile is compiled into several things, and they are not equally strong.

PartWhat it doesStrength
OpenShell policyNetwork egress, which MCP methods and tool names the sandbox may call at the gateway, files the sandbox can read and write, and which binaries may connectEnforced by OpenShell outside the agent. The model cannot talk its way around it
Tool gatewayServes only the tools pinned for the profile, to a session token that reaches only that profile’s toolsEnforced by aimux on the Mac
Harness configThe agent’s own launch options: the --allowedTools list, --strict-mcp-config, the tool list, no user settingsCooperative. It mirrors the policy so the model is never offered a tool it cannot use, but the agent applies it to itself

A prompt injection that talks the agent into calling a tool the profile does not allow reaches OpenShell’s policy or the gateway, and stops there. The harness config is what keeps the agent from trying.

Only profiles with runs: sandbox compile to a policy. Their network.allow must include model, and tools need gateway. web compiles to one read-only policy, public_web_readonly: a **.*.<tld> endpoint for each reviewed top-level domain (com, org, net, io, dev, ai, app, edu, gov, co, me, info, uk, de, eu) and an exact endpoint, limited to public addresses, for each reviewed apex host such as github.com, all on port 443 with GET only. The tool sets resolve against the pinned tools. A tool changed since it was pinned is hidden until you pin it again.