Metadata-Version: 2.4
Name: agmx
Version: 0.1.1
Summary: Run AgentMatrix work on your own machine, under your own coding-agent subscription.
Author: lupca
License-Expression: MIT
Project-URL: Homepage, https://github.com/nothan-agentic/AgentMatrix
Project-URL: Source, https://github.com/nothan-agentic/AgentMatrix/tree/main/runner
Keywords: agmx,agentmatrix,coding-agent,runner
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# agmx

[![PyPI](https://img.shields.io/pypi/v/agmx.svg)](https://pypi.org/project/agmx/)
[![Python](https://img.shields.io/pypi/pyversions/agmx.svg)](https://pypi.org/project/agmx/)
[![License](https://img.shields.io/pypi/l/agmx.svg)](https://github.com/nothan-agentic/AgentMatrix/blob/main/runner/LICENSE)

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.

```console
$ pip list
agmx  anyio  certifi  h11  httpcore  httpx  idna  typing_extensions
```

## Install

```bash
pipx install agmx
```

Requires Python 3.10+ and `git` on `PATH`.

## Quickstart

```bash
# 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

| Path | Mode | Contents |
| --- | --- | --- |
| `~/.agmx/.credentials.json` | `0600` | login token |
| `~/.agmx/settings.json` | `0644` | `server`, `email`, `runner_id` |

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

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

## License

MIT — see [LICENSE](LICENSE).
