From first prompt to system insight.

01. Quick start

You need Python 3.11 or newer and an interactive terminal. Install the package in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anomx

Start the agent in the directory you want to work in:

anomx

1. Connect a model provider during onboarding. Change it later with /config → Manage Backends.
2. Choose an available model with /model. By default, new sessions start in Auto Approve mode.
3. Describe your question, for example: “Inspect the CSV files in this directory. Which channels show unusual behavior?”

Local analysis does not require a platform connection. A configured model provider is required. Cloud providers may have their own access requirements and usage costs.

02. Models & backends

Connect providers in /config → Manage Backends. /model shows curated choices across your connected backends; successfully loaded provider catalogs filter out unavailable models. /effort adjusts reasoning effort where the selected model supports it.

These backend names and model IDs come from the Anomx 0.2.92 source catalog. Actual availability depends on your account and provider.

anomx --provider openai --model gpt-6.1-sol

For Ollama, start the local service and install the model you want to use. You can also supply a custom model ID when connecting a backend or with --model:

anomx --ollama --model qwen3.6

Startup flags: --provider, --model, --ollama, --home, --print-home, --no-color, --version. ANOMX_PROVIDER and ANOMX_MODEL supply startup defaults; explicit flags take precedence. --ollama always selects the Ollama backend.

03. Execution modes

Press Shift+Tab to cycle through three interactive modes in the CLI. The active mode appears in the prompt bar. In platform chats, select the mode in the message composer.

Approvals without stopping the whole task

In Request Approvals, approval requests remain open asynchronously by default. Only the gated action waits; the agent can continue independent work while you decide. The action executes only after you approve it. Denying it keeps it blocked.

When the decision is a critical prerequisite for the next step, the agent can explicitly wait synchronously for your response. An open request is not consent. Auto Approve makes these decisions through the evaluator; Autonomous skips command evaluation.

The tools run_command, start_process and mount_folder return an approval ID when a request is pending. The agent collects the decision with check_approval; an approved action executes when that decision is collected. Repeated checks do not execute the same action again. Setting wait_for_approval: true lets it wait directly instead. check_approval can wait up to 60 seconds for a decision using wait_seconds.

Modes do not change account permissions or grant additional access to the host filesystem. Sandbox boundaries remain in place. Background is a separate mode for scheduled platform runs.

04. Sandboxing with Docker or Podman

Choose where agent commands run independently of the execution mode. The optional container sandbox uses Docker or Podman and starts in a dedicated task folder. The CLI and model connection stay on the host. Sandboxing is off in a fresh configuration.

1. Prepare the container engine

Install Docker Desktop or Docker Engine and start the engine. Check that it is reachable with: Install Docker ↗

docker info

Alternatively, install Podman. On macOS and Windows, Podman needs a Linux VM. Initialize it once and start it if it is not already running; on Linux, normally just check podman info: Install Podman ↗

podman machine init  # Once, if no machine exists
podman machine start  # When the machine is stopped
podman info

2. Enable it in Anomx

1. Start anomx and open /config → Manage Settings. Find the Sandbox section.
2. Set Runtime to Docker or Podman and Enabled to On. Project Method: Mount uses persistent task storage; it does not automatically mount your project folder.
3. Send your first message. Anomx builds a runtime image for your package version when needed and starts the anomx-agent container. The first start may take a few minutes and needs access to image and dependency downloads.

On macOS, Anomx can start Docker Desktop when you send the first message. Start a Podman VM yourself. If the engine is unavailable, Anomx runs no agent commands; start the engine and retry your message.

3. Grant access to specific folders

The launch directory is not mounted automatically. When the agent needs local files, mount_folder requests access to a specific absolute folder path and explains why. In Request Approvals, you decide on this access expansion. In Auto Approve, the evaluator decides without prompting you; Autonomous skips approval evaluation. Granted read/write access applies to that task and is remembered when it resumes. Other tasks require their own access grant.

Edits inside a mounted folder change the real host files. Grant only the task folder you need. The entire home directory, filesystem root, and Anomx configuration directory cannot be mounted through this tool.

Storage, limits, and lifecycle

• Each session has a task folder at ~/.anomx/sessions/<id>/task/. Brain, skills, and session storage are mounted from the host. Tasks use a shared container; there is no separate VM for each chat.
• CPU and RAM limits are configurable in Manage Settings; defaults are 2 CPU cores and 4g RAM. The Disk field does not currently enforce a storage quota in the persistent container.
• Exiting the CLI leaves the container running. On a later turn, Anomx may replace it after an update or a change to approved folders. Saved task data and mounted files persist; extra packages installed only inside the container may be lost.
• To disable it, set Enabled to Off and confirm removal of the container. Saved task files remain. The sandbox separates the execution environment, but does not disable network access or replace approval policies.

The runtime menu also offers Python as a software workspace sandbox. Choose Docker or Podman for the container workflow described here.

05. Commands & skills

In /config → Manage Settings, configure the display, standard models by task difficulty, context limit, sandbox, debugging, and Manage Commands for remembered approvals and denials.

Repeatable work as a skill

Manage your own skills with /config → Manage Skills. Bundled skills include create-dataset, retrieve-data, manage-acquisition, train-models, write-work, browse-files, edit-workspace, manage-integrations, manage-data, manage-jobs, manage-systems, manage-recommendations, and use-anomx-api. Their availability depends on the platform connection.

Interrupt work

While the agent is working, Ctrl+X, or Ctrl+C with an empty input, requests an interruption. Press the same key again within three seconds to confirm. Ctrl+C clears a nonempty input first. Esc returns to the previous view without cancelling running work.

06. Connect the platform

1. Open /config → Manage Platform.
2. Enter your Anomx instance URL and sign in with your platform account.
3. The platform issues a dedicated CLI-agent token. Requests stay linked to your user and organization context.

The connected agent can retrieve platform data, investigate jobs and systems, and work through permitted APIs. The local CLI and background agent share the agent foundation but have different execution policies.

07. Background agent

Configure a scheduled prompt in the platform. Describe what to monitor, the cadence, and the results that would be useful. Background remains a separate mode: the evaluator automatically allows or denies actions within existing background permissions. Background runs never ask interactive questions or request human approvals.

What the agent can do

• Read data, investigate system state, and inspect previous background runs.
• Create recommendations by default, instead of making operational changes directly.
• Directly create, update, or delete platform objects only when the team explicitly allows that operation for the object type.

Permissions, budgets, and history

Existing access permissions still apply. Background agents cannot change credentials or automation permissions. Hourly and daily token limits can pause runs; paused work is rechecked later. Earlier runs help avoid duplicate findings.

Background is not unattended full control of machines. File and process changes and arbitrary host commands are outside this mode. Direct control requires appropriate integrations and explicitly authorized execution paths.

08. Sessions & storage

The agent stores state under ~/.anomx by default. ANOMX_HOME or --home overrides this location.

anomx --print-home

auth.json and session transcripts may contain sensitive data. Keep them out of public repositories and unredacted support uploads.

09. Python API

Datasets, models, scorers, detectors, and local execution now have dedicated documentation with a quick start and an automatically generated API reference.