agmx

Run AgentMatrix work on your own machine, under your own coding-agent subscription.

AgentMatrix is a coordination service for coding agents: it plans work, holds the review gates, and decides what lands. agmx is the other half — a small client that picks up the work the server hands out and executes it locally, inside a throwaway git worktree of a repository you already have checked out.

Nothing about your machine travels to the server. The server dispatches a project_id; your machine decides which directory that is.

Why it is separate

The control plane needs Postgres, Redis and a pile of orchestration code. A runner does not. agmx depends on httpx and nothing else, so installing it never asks you for a database URL or a shared secret.

$ pip list
agmx  anyio  certifi  h11  httpcore  httpx  idna  typing_extensions

Install

pipx install agmx

Requires Python 3.10+ and git on PATH.

Quickstart

# 1. Authenticate.  Prompts for your password; never takes it as a flag.
agmx login --email you@example.com

# 2. Tell the runner where your checkouts live, then let it work.
agmx runner start --project agenticmatix=~/code/AgentMatrix

--project may be repeated. A project_id you have not registered is reported back as failed rather than guessed at, so a run can never be executed against the wrong tree.

Point at a different control plane with --server, or AGMX_SERVER.

How a run executes

1. The runner leases one queued run: {run_id, task_id, project_id, command, timeout_seconds}. No path, no repository URL.
2. It resolves project_id against the checkouts you registered.
3. It creates a git worktree on ct-run/<run_id>, branched from the current HEAD.
4. The command runs there. Output is streamed back in batches while it runs, not buffered until the end.
5. On exit, changes are committed, the worktree is removed, and the branch is kept — so the commit stays reachable from your main checkout.
6. The runner reports facts: exit code, base and head SHA, whether it timed out. It does not decide whether the run succeeded; that judgement stays on the server, with the review history.

A run that exceeds timeout_seconds has its whole process group terminated, not just the process the runner spawned — coding agents spawn children.

Configuration

Secrets are kept in a separate file from settings, and the credentials file is created with its mode already set rather than being widened and then narrowed. Set AGMX_CONFIG_DIR to move the directory.

Security notes

• The password is read from the terminal only. There is deliberately no --password flag: it would survive in shell history and in ps output.
• GIT_DIR and GIT_WORK_TREE are stripped from the environment handed to the command, so an agent's git calls cannot reach outside the worktree.
• The default server is HTTPS. agmx login sends a password in the request body; plain HTTP would hand it to anyone on the path.

Development

git clone https://github.com/nothan-agentic/AgentMatrix
cd AgentMatrix/runner
pip install -e .
python -m pytest tests -q

License

MIT — see LICENSE.