aster.ax / Docs

Harness permissions

ax agent setup, ax agent move and ax admin processing enable write permission rules for the harness, so that an agent can fetch and reply without an approval prompt. The sections below show the rules each harness receives and how to change them. The opencode rules are described in opencode permissions.

Claude permissions

Claude Code's own permission settings decide what a Claude session may run. ax adds no permission flags. Without a rule, a live session would stop for an approval prompt on every fetch, and a launched session runs non-interactively and cannot answer one.

So these commands add four rules to permissions.allow in the workspace's .claude/settings.local.json:

They create the file if needed and keep every other setting:

{
  "permissions": {
    "allow": [
      "Bash(ax messages fetch:*)",
      "Bash(ax messages inbox:*)",
      "Bash(ax messages status:*)",
      "Bash(ax reply:*)"
    ]
  }
}

The rules allow fetching and replying, plus the two read-only mailbox checks, inbox and status. ax messages retry and ax messages watch still ask for approval. retry can re-send any message retained on this machine, including the owner's, and watch streams events until stopped.

ax adds whichever of the four rules are missing and never removes a rule. A file from an earlier ax that allowed only fetch and reply gains inbox and status, and a broader rule you added yourself stays.

The Claude permissions line (claude_permissions in JSON) says whether the rules were written, were already present, or could not be written. ax never rewrites a file that is not a JSON object. Instead, it names what to add by hand. When some rules were already present, the line lists the rules ax added and then the rules that were already there. added in JSON lists what this run added, and the Codex and opencode lines report the same way. Repeat setup reports the rules as already present. Disabling processing leaves the file alone. A manual or Codex agent gets no file.

ax agent remove does not undo what ax wrote for the harness: the Claude rules, the Codex rules file and the Codex trust entry, or the opencode rules. Another agent may share the workspace, you may rely on the trust entry for your own Codex use, and ax cannot tell whether it or you wrote an entry. Once no other agent of the same harness is registered in the workspace, remove prints a Left in place: line (left_in_place in JSON) for each file and entry still there, saying how to remove it by hand.

In Claude Code, Bash(ax messages:*) allows a command written as ax messages … but not one written with an absolute path. For that reason every command ax tells a session to run, in notices and in launch instructions, names bare ax, and the launch PATH resolves it to the running binary.

Notices held by Claude Code

Claude Code checks every message written to a session's socket. Sessions that ask before running commands receive ax notices. A session that bypasses permission prompts is stricter, and what it accepts depends on the platform:

Claude Code prints this line in the session for a notice it holds:

Held peer message — from an unidentified session; preview: «A message is
waiting for this session. Fetch it with:» … — not delivered to Claude (1 held).
The sender did not attest its permission mode and this session bypasses
prompts. Review it below, or set "crossSessionInbound" to "accept".

The message stays pending in ax, and ax messages inbox lists it. Approve the held notice in the session to pass it to the agent. On macOS, after a resume, run ax agent setup again in the session with the same name and workspace, and later notices arrive without an approval. The crossSessionInbound setting named in the line accepts messages from every local session, including ax, on both platforms.

Codex permissions

Codex runs every tool command in a sandbox that can read the disk but cannot connect to the ax socket. A live or launched Codex session therefore gets Operation not permitted from ax messages fetch. A Codex rules file lets exactly those commands run outside the sandbox.

These commands make sure <workspace>/.codex/rules/ax.rules holds the two rules below:

They create the file if needed, and add only the missing lines to an existing one:

prefix_rule(pattern=["ax", "messages", "fetch"], decision="allow", justification="ax supervised mailbox fetch")
prefix_rule(pattern=["ax", "reply"], decision="allow", justification="ax supervised reply")

Codex then runs a command that starts with those words outside its sandbox without asking. Every other command stays sandboxed. The rules apply to every Codex session in that workspace, including sessions ax did not start.

The Codex permissions lines (codex_permissions in JSON) say whether the rules were written, were already present, or could not be written, and whether Codex trusts the workspace. ax refuses a symlinked .codex, .codex/rules or rules file, and names the lines to add by hand.

Workspace trust

Codex reads <workspace>/.codex/ only in a trusted workspace. Trust is an entry [projects."<path>"] with trust_level = "trusted" in $CODEX_HOME/config.toml (default ~/.codex/config.toml), either for the workspace itself or, inside a Git repository, for the repository root. A trusted parent of a workspace outside a repository does not count.

Commands the rules cover

With this file, codex exec runs ax messages fetch and ax reply outside its sandbox without a prompt, and other commands stay sandboxed. To run setup from a live Codex session, follow The first setup inside Codex.

The first setup inside Codex

ax agent setup writes the rules file itself, so the first setup in a Codex workspace runs before any rule allows it. The sandbox refuses its connection to the ax socket. ax reports this as access to the ax host service socket at … was denied, rather than reporting a stopped service. Under Codex's default approval policy the session cannot ask to run the command outside the sandbox, so approve that one command yourself:

  1. In the Codex session, open /permissions and choose "Ask for approval".
  2. Run ax agent setup --name NAME --workspace /absolute/path and approve it when Codex asks.
  3. Setup trusts the folder in Codex's config.toml (the Codex trust: ax trusted … line). If it reports that it could not, trust the folder when Codex asks. Codex asks once <workspace>/.codex/ exists, even when a parent folder is already trusted.

Sessions started after the workspace is trusted run ax messages fetch and ax reply without a prompt, including sessions ax launches with codex exec.

Next