
Orchestrates coding agents via a ticket board, running each task on its own git branch/worktree with mail, weighted routing, Lua scripting and plugin extensibility.
Run a whole team of coding agents from one ticket board.
Website · Downloads · Live demo · Plugins
Windows · Android · macOS (beta) · Headless server (Docker or plain archive)
Features · Quickstart · Server setup · FAQ · Known issues · Help · Sponsor
Beta. Infantry AI is in Beta. It works and we use it every day, but not every part is fully tested yet: you are an early tester. Please report anything that breaks on GitHub.
Report a problem
This branch is the Rust framework.
mainnow holds the Rust rewrite of Infantry AI: the daemon and core crates live inrust/, the desktop, web and Android app inapp/. The earlier Java/Kotlin implementation is kept, unchanged, on thelegacy-javabranch. Parts of the text below still describe the Kotlin version (Gradle builds,superiorSoftLibrary/) and are being updated.
Infantry AI running against a demo project: the agent sidebar, the PM's chat, plan-usage pacing and a worker on its ticket. Dark and light themes. Click a picture to open it full size.
Board
|
Mail
|
A worker on its ticket
|
Health
|
More shots: Settings, Plugins, Triggers, Notes, Board, light theme.
Your AI doesn't just run your workflow. It builds your workflow.
Infantry AI is an AI framework. It is no longer only a project-management app: it is the components to build something else. You can build a completely new application with it, or use the platform itself to build the application you want. The AI is no longer just the builder: the agents are the cells of the body, and they evolve the application into something else. The project-management board is one app built on this framework. See docs/VISION.md.
Infantry AI (formerly AgentHQ) is a command post for coding agents. You file tickets on a board, give each one a role (full-stack engineer, QA, PM, ...) and a provider (Claude Code, opencode, pi, or any CLI you describe in a JSON file), and Infantry AI starts the agent on its own git branch and worktree, keeps its mail, progress and shared project knowledge in one daemon, and lets you watch, steer and merge the work from your desktop or your phone. The daemon runs on your machine or on your own server: your code, keys and agent output never pass through a third-party service.
Foundation and free, on purpose. The core (the daemon) is the foundation: it is licensed MPL-2.0 to protect its integrity, so apps and plugins can rely on a stable base that does not break, with backward compatibility as the promise. Everything built on top (the SDKs, the UI core, the apps and every plugin) is free under Apache-2.0: build, fork, sell and extend it without copyleft. See Licensing (draft, not yet in effect).
Status: early preview. The app is used daily by its own team, but it is not 1.0. Read Roadmap and known issues before you rely on it.
Live updates (new versions delivered to the app as they ship) will be available shortly. Today the Windows app and the headless server check GitHub Releases and update on request (see Updates); Android and Docker are updated by hand.
tickets.weightExecutors), unless the ticket or its role already pins one. Richer routing rules are planned.infantry ask) without blocking. You see the question with its
options and the agent's recommended pick, answer once, and the answer reaches the agent as mail.Figure: clients talk to one orchestrator; the orchestrator places every agent session on a runner (this machine, or a Docker container anywhere). Agent mail between runners always travels through the orchestrator.
A runner is where an agent actually runs. The orchestrator is the daemon that holds your board, tickets and mail.
docker run the runner image, then paste its endpoint into Settings > Runners. See the runners guide.wss with a per-runner key; you can Rotate or Detach it. Update runner keeps a runner on the app's version (the image infantry-runner:<tag> must match the app).Full guide: Runners: concepts, setup, update, troubleshooting.
You can see the whole loop without a paid subscription by using opencode with one of its free models:
infantry harness-install opencode, needs Node 20+) or by hand, and check it with
infantry harness-status.opencode models shows what your install offers; availability of free
models is decided by opencode, not by Infantry AI).The board. Tickets move through To Do, In Progress, Pending and Done (plus Backlog). A ticket carries a role, a type, a weight and optionally a provider and model. Starting it cuts its own branch and worktree and runs the agent there; its report lands as a ticket comment. Pending is set by the daemon while a blocking ticket is open. Order in a column is priority.
Scripts. Your process lives in Lua scripts in <project>/.infantry/scripts/, not in anyone's memory: what happens
when a ticket is done, when mail arrives, when a build ends. Hooks run a script on a lane change, on incoming mail, on
a timer or on a named event, and a script can call every tool an agent has. See Scripting.
Plugins. The app is the OS, plugins are the programs: every tab, panel, board card and daemon tool, and every
agent CLI harness, is a plugin with a module.json. Write your own in a few minutes. See
Plugins and Harnesses and providers.
module.json, UI and daemon halves, config, building, installing, signing, a hello pluginmodule.json fieldBuild and preview the wiki site locally (MkDocs + Material, strict: a broken link fails; nothing is published):
infantry script run wiki --args '{"mode":"serve","port":8899}' (or "mode":"build" to write
<dist>/wiki/<sha8>). Needs scripting.exec.enabled and a venv with docs/requirements-wiki.txt
(pinned) at <dist>/wiki-venv; the script installs it. Without the script:
python -m mkdocs build --strict -f docs/mkdocs.yml -d <out>.
Screenshots the docs link are listed in docs/img/README.md.
Every release is on the latest Release page, built by the tag workflow
(.github/workflows/release.yml) and listed with its SHA-256 in SHA256SUMS (and latest.json).
| Platform | File | Notes |
|---|---|---|
| Windows (x64) | InfantryAI-<version>.msi |
The full desktop app with its own daemon. Per-user install, no admin prompt. Not code-signed yet: SmartScreen warns, choose More info > Run anyway. Updates itself in place. InfantryAI-<version>-windows.zip is the same app unpacked (do not update a zip copy with the MSI). |
| Android |
InfantryAI-<version>.apk (or -debug.apk) |
Beta. A phone client for a daemon on your PC or a server; sideloaded (allow "install unknown apps"). Today's APK is signed with a test or debug key: when the permanently signed APK ships, Android refuses it over this one, so you uninstall (the app's local data goes with it) and install again. |
| macOS (Apple silicon, beta, unsigned) |
InfantryAI-<version>-macos-arm64-beta.dmg (desktop app) and InfantryAI-server-<version>-macos-arm64.tar.gz (headless server) |
Beta. The .dmg ships in releases from 1.1.0 on. Built by CI and not yet tested on a real Mac. Intel Macs: not supported; use the web client from another machine. First launch: macOS warns about an unidentified developer, so right-click the app and choose Open, or run xattr -d com.apple.quarantine /Applications/InfantryAI.app. |
| Web | InfantryAI-web-<version>.zip |
The browser client's static files. You rarely need it: every daemon (desktop app, server archive, Docker) already serves it at http://<host>:<port>/. To serve your own copy, unpack it and point the daemon at the folder with INFANTRY_WEB_DIR=<folder>. See Web. |
| Headless server | InfantryAI-server-<version>-<os>-<arch>.{zip,tar.gz} |
The daemon + CLI with a bundled Java runtime: linux-x64, windows-x64, and macos-arm64 (beta). See Plain archive. |
The macOS server build is new and no one on the team runs a Mac every day. If you have an Apple silicon Mac, please run the headless server archive, create a project and run one ticket, then open an issue with what worked and what did not: your macOS version, the step that failed, and the error text you saw. The macOS desktop app (.dmg) ships in releases from 1.1.0 on (beta, unsigned).
| Client | What it is | How to get it |
|---|---|---|
| Windows desktop | The full app: board, agents, mail, knowledge. It runs its own daemon, so it works on its own with no server. |
InfantryAI-<version>.msi from the latest Release (or the -windows.zip app image). |
| Android | A phone client for a daemon running elsewhere (your PC or a server): watch agents, answer questions, move tickets. |
InfantryAI-<version>.apk from the latest Release, installed by hand (not on Google Play yet). |
| Web | A browser client (Kotlin/WASM) served by the daemon itself: board, agents, transcripts, messages, ticket starts. File, QR and camera features stay in the desktop and phone apps. | Open http://<host>:<port>/ on a daemon that has a token. See Web. |
CLI (infantry; agenthq is a deprecated alias) |
Every board, ticket, mail and knowledge command, for scripts and for the agents themselves. | Ships inside the desktop app and the server archive. |
| Headless server | The daemon with no UI, for a home server, a VM or a cloud box. | Docker image (build it yourself for now) or InfantryAI-server-<version>-<os>-<arch> archive from the Release. |
There is no Linux desktop app yet. The macOS desktop app is beta (Apple silicon, in releases from 1.1.0). On Linux or an Intel Mac, use the headless server plus the web client, the Android app or the CLI.
InfantryAI-<version>.msi from the latest Release and run it. It installs per
user (no admin prompt). The installer is not code-signed yet, so Windows SmartScreen will warn: choose
More info > Run anyway.npm install -g @anthropic-ai/claude-code, then run claude once to log in). The app can also install the supported
CLIs for you (infantry harness-install claude, also opencode and pi; needs Node 20+).allowEdits lets it edit files without asking, allowAll lets it
run anything, deny refuses every tool that is not pre-allowed). A tool that was refused shows on the ticket's card
as "blocked: denied".
Your data lives in %LOCALAPPDATA%\SuperiorSoft\InfantryAI, apart from the program, so upgrades and uninstalls keep it.
Details: docs/INFANTRY-INSTALL.md.
The Android app is a client: it needs a daemon to connect to (your Windows app or a headless server).
InfantryAI-<version>.apk from the latest Release on the phone and install it
(allow "install unknown apps" for your browser when Android asks).infantry remote on on the PC and restart the app; it prints the address and a token. See
ANDROID-TAILSCALE.md.ws://<host>:<port>/ws address and the token by hand). See Pairing.The daemon serves a browser client at http://<host>:<port>/ (the server archive, the Docker image and the desktop app
ship it). Open that address, enter the daemon's token once (the browser keeps it in its localStorage), and you get the
board, the agents, their transcripts, messages and ticket starts. The browser only connects to a daemon that has a token
(INFANTRY_TOKEN / INFANTRY_TOKEN_FILE, or remote access turned on), and only from the same origin. If you reach the
daemon by a host name it cannot see (a domain, or Docker), list it in INFANTRY_WEB_HOSTS (comma-separated). An offline
demo with fake data is on the token screen.
See Headless server below: build the image, create a token, docker run, then connect the
Android app, the web client or the CLI. From the CLI alone: infantry project create "<name>" <repo dir>, then
infantry ticket create --project <id> --title "..." --role fullstack and infantry ticket start <ticket id>.
The same daemon as the desktop app, with no UI. Use it on a home server, a VM or a cloud machine, then connect from Android or the CLI.
Security first: the token is the only credential, and it grants command execution through agents. Never expose the raw port to the internet. Bind to loopback and put a TLS reverse proxy (Caddy, nginx) or a VPN/SSH tunnel (Tailscale works well) in front; it must pass WebSocket upgrades.
The image (infantryai/infantry-ai) is not published yet; build it locally:
./gradlew :superiorSoftLibrary:infantry:dockerContext
docker build -t infantryai/infantry-ai:dev superiorSoftLibrary/infantry/build/docker
Run (the token is mandatory, at least 32 characters: the daemon refuses a non-loopback bind without one):
openssl rand -hex 32 > infantry_token
openssl rand -hex 32 > infantry_keystore_key
docker run -d --name infantry-ai -p 127.0.0.1:8787:8787 \
-e INFANTRY_TOKEN_FILE=/run/secrets/infantry_token \
-v ./infantry_token:/run/secrets/infantry_token:ro \
-e INFANTRY_KEYSTORE_KEY_FILE=/run/secrets/infantry_keystore_key \
-v ./infantry_keystore_key:/run/secrets/infantry_keystore_key:ro \
-v infantry-data:/data infantryai/infantry-ai:dev
infantry --url ws://127.0.0.1:8787/ws --token-file ./infantry_token board
(Git Bash on Windows rewrites /run/... into a Windows path: prefix the docker run with MSYS_NO_PATHCONV=1.)
/data holds the database, logs and state (INFANTRY_STATE_DIR). Keep the same volume across image upgrades.INFANTRY_PORT (default 8787), INFANTRY_HOST (default 0.0.0.0), INFANTRY_TOKEN or INFANTRY_TOKEN_FILE
(e.g. a Docker secret at /run/secrets/infantry_token); other INFANTRY_* variables are read as usual.HEALTHCHECK polls GET /health (the one path open without a token).-e INFANTRY_REPO=/work/repo -e INFANTRY_BASE_BRANCH=main (see docker/README.md).infantry --url ... --token-file ... harness-install claude (also opencode, pi); they land in
/data/harness-tools, so they survive container upgrades, and harness-status shows them. Sign-in is per CLI: pass the
provider's API key (-e ANTHROPIC_API_KEY=...) or log in once with docker exec -it infantry-ai claude and keep the login with
-v infantry-home:/home/infantry. A CLI you already have can be mounted instead (-v /path/to/cli:/usr/local/bin/<name>:ro)./data/keystore.json. A container has no OS keychain, so mount the master
key and point INFANTRY_KEYSTORE_KEY_FILE at it (as above; INFANTRY_KEYSTORE_KEY also works). Without it the daemon falls
back to /data/keystore.key, which is only as safe as the volume. Keep the key file outside the volume and back it up.The same daemon with its own Java runtime bundled (nothing to install), one per OS on the Release:
InfantryAI-server-<version>-windows-x64.zip, InfantryAI-server-<version>-linux-x64.tar.gz,
InfantryAI-server-<version>-macos-arm64.tar.gz (beta). Unpack it and start the daemon (README.txt inside lists every setting):
# Linux / macOS
INFANTRY_TOKEN_FILE=./infantry_token INFANTRY_HOST=0.0.0.0 ./InfantryAI-server-<version>-linux-x64/bin/infantry-server.sh
# Windows (cmd)
set INFANTRY_TOKEN_FILE=%CD%\infantry_token& set INFANTRY_HOST=0.0.0.0& InfantryAI-server-<version>-windows-x64\bin\infantry-server.bat
Without INFANTRY_HOST it binds to 127.0.0.1 only. State goes to ~/.infantry unless INFANTRY_STATE_DIR says otherwise, so do
not run it next to an installed desktop app on the same state dir and port. bin/infantry in the archive is both the CLI and
the update supervisor, on the same bundled runtime: a command word (bin/infantry board, health, --help) runs the CLI;
no argument or serve starts the daemon under the supervisor (the first run copies the folder to <parent>/versions/ and
writes <parent>/infantry, the entry point from then on; see README.txt). Agent CLIs are the machine's own (infantry harness-install <id> needs Node 20+).
A client connects to a daemon with two things: its address (ws://<host>:<port>/ws, or wss:// behind TLS) and its
token. Pairing hands both over in one step:
infantry://connect?url=...&token=...&name=....The QR code and the link contain the token: treat them like a password. Show them only to devices you own, and never
post a screenshot of them. To revoke access, change the token (infantry remote off / on, or a new token file) and
restart the daemon.
SHA256SUMS (a mismatch is refused and deleted), asks first if
agents are still running, then upgrades in place and restarts. Your data is kept.infantry update (or Configuration > Server > Update) installs the archive for its own OS from
the same Release, checks it against SHA256SUMS, keeps the previous version, and infantry rollback returns to it. The
data dir is never touched.docker pull to run;
recreate the container on the same /data volume.InfantryAI-<version>.apk (release-signed) builds; a -debug.apk cannot upgrade a release install.Details: docs/RELEASING.md and UPDATES.md.
Which agents does it run? Claude Code, opencode and pi out of the box. Any other command-line agent can be added with a JSON descriptor; see QUICKSTART.md.
Do I need an account with you? No. There is no Infantry AI cloud service. You bring your own agent CLIs and their logins or API keys; the daemon runs on your hardware.
Where is my data? Windows app: %LOCALAPPDATA%\SuperiorSoft\InfantryAI. Server: ~/.infantry or INFANTRY_STATE_DIR
(/data in Docker). Secrets (tokens, keys) are sealed in a keystore there.
Does it cost anything? The app is free to download. The agents use your own subscriptions or API keys with their providers, billed by those providers.
Can several people share one server? One daemon has one token today; anyone with it has full access. Per-user accounts are not built yet.
Why do some names say AgentHQ? That was the project's earlier name. The old names still work so nothing breaks on
upgrade: AGENTHQ_* variables are read as fallbacks for INFANTRY_*, the .agenthq folder is read when .infantry
has no copy, and agenthq is a deprecated alias of the infantry command.
Is it safe to expose to the internet? Not directly. See the security note under Headless server.
| Symptom | What to check |
|---|---|
| SmartScreen blocks the installer | Expected for now: the MSI is not code-signed yet. More info > Run anyway. |
| An agent provider is missing from the picker | The CLI must be installed and on the daemon's PATH (infantry harness-status), then restart the app. |
| A ticket refuses to start: "no directory configured" / "no base branch configured" | Set the project's repository and its base branch (Git tab > "Base branch for new tasks", or infantry project base <projectId> <branch>; Docker: INFANTRY_REPO and INFANTRY_BASE_BRANCH). A ticket also needs a role. |
| Phone says it cannot connect | Same network or Tailscale? Firewall open for the daemon port? Address ends in /ws? A 401/403 means a wrong token. |
| Server refuses to start: "refusing to start" | A non-loopback bind needs a token of at least 32 characters. |
| "Check for updates" says updates are off | Set INFANTRY_UPDATE_REPO=owner/repo (or repo= in update.properties). |
| Anything else | Open Configuration > Logs > Open logs folder and attach infantry.log to a bug report. Read it first: logs can hold project paths and agent output. |
More: QUICKSTART.md troubleshooting and INSTALL logs.
What is not finished, stated plainly:
Planned next: published Docker image, signed Windows builds, macOS/Linux desktop packages, multi-user access. Priorities can change; watch the Releases page.
infantry.log).Bug reports and feature requests are welcome now: open an issue. Pull requests from outside the team are not accepted yet; for now, please send ideas and fixes as issues. How to build, branch, test and commit: CONTRIBUTING.md. Everyone taking part follows the Code of Conduct.
The core (MPL-2.0) is the community foundation. Sponsorship and donations pay for keeping it stable and backward compatible.Starring the repository and filing good bug reports help too.
The core is a community effort; the rest is yours.
Infantry AI is licensed per directory. Every source file names its license in an SPDX-License-Identifier header.
| License | What it covers |
|---|---|
| MPL-2.0 (the core) |
superiorSoftLibrary/infantryProtocol, superiorSoftLibrary/infantryCore, superiorSoftLibrary/infantryRunner, superiorSoftLibrary/infantry, and the reserved plugins/core/
|
| Apache-2.0 (everything else) | the plugin API and host, the SDKs, the board, the UI core, the apps, samples/, plugins/, docs/, docker/, scripts/ and the build files |
| Neither (trademark) | the name "Infantry AI", the logo and the emblem |
LICENSE.Draft. The split is applied but not official until the public launch. Not legal advice.
Requires JDK 21 (Gradle toolchain resolution via foojay) and, for the Android module, an Android SDK. Run only one Gradle build at a time.
./gradlew :superiorSoftLibrary:infantry:compileKotlin :superiorSoftLibrary:infantryUi:compileKotlin
./gradlew :superiorSoftLibrary:infantry:installDist # build/install/infantry/bin/infantry (and the agenthq alias)
./gradlew :superiorSoftLibrary:infantryUi:packageReleaseMsi # Windows installer
./gradlew :superiorSoftLibrary:infantry:headlessDist # server archive for this OS
Modules (all under superiorSoftLibrary/; the prefix keeps :superiorSoftLibrary:* paths stable):
infantry: daemon + infantry CLI (JVM; agenthq stays as a deprecated alias)infantryUiCore: shared UI core (Compose Multiplatform)infantryUi: desktop UIinfantryAndroid: Android shellinfantryHeadless: test-only guard that the daemon runs with no UISecrets guard: ./gradlew verifySecretsNotTracked fails if keys, keystores or tokens are tracked. Signing secrets belong in
secrets.local.properties (gitignored) or environment variables. More in CONTRIBUTING.md.
INFANTRY_* variable is also read under its old name AGENTHQ_* (AGENTHQ_PORT, AGENTHQ_TOKEN, ...). The old
names keep working; when both are set the INFANTRY_* one wins.© SuperiorSoft LLC. Infantry AI is a product of SuperiorSoft LLC.
Daemon: what the core is and the orchestrator/runner split are in docs/DAEMON-CORE.md.
Run a whole team of coding agents from one ticket board.
Website · Downloads · Live demo · Plugins
Windows · Android · macOS (beta) · Headless server (Docker or plain archive)
Features · Quickstart · Server setup · FAQ · Known issues · Help · Sponsor
Beta. Infantry AI is in Beta. It works and we use it every day, but not every part is fully tested yet: you are an early tester. Please report anything that breaks on GitHub.
Report a problem
This branch is the Rust framework.
mainnow holds the Rust rewrite of Infantry AI: the daemon and core crates live inrust/, the desktop, web and Android app inapp/. The earlier Java/Kotlin implementation is kept, unchanged, on thelegacy-javabranch. Parts of the text below still describe the Kotlin version (Gradle builds,superiorSoftLibrary/) and are being updated.
Infantry AI running against a demo project: the agent sidebar, the PM's chat, plan-usage pacing and a worker on its ticket. Dark and light themes. Click a picture to open it full size.
Board
|
Mail
|
A worker on its ticket
|
Health
|
More shots: Settings, Plugins, Triggers, Notes, Board, light theme.
Your AI doesn't just run your workflow. It builds your workflow.
Infantry AI is an AI framework. It is no longer only a project-management app: it is the components to build something else. You can build a completely new application with it, or use the platform itself to build the application you want. The AI is no longer just the builder: the agents are the cells of the body, and they evolve the application into something else. The project-management board is one app built on this framework. See docs/VISION.md.
Infantry AI (formerly AgentHQ) is a command post for coding agents. You file tickets on a board, give each one a role (full-stack engineer, QA, PM, ...) and a provider (Claude Code, opencode, pi, or any CLI you describe in a JSON file), and Infantry AI starts the agent on its own git branch and worktree, keeps its mail, progress and shared project knowledge in one daemon, and lets you watch, steer and merge the work from your desktop or your phone. The daemon runs on your machine or on your own server: your code, keys and agent output never pass through a third-party service.
Foundation and free, on purpose. The core (the daemon) is the foundation: it is licensed MPL-2.0 to protect its integrity, so apps and plugins can rely on a stable base that does not break, with backward compatibility as the promise. Everything built on top (the SDKs, the UI core, the apps and every plugin) is free under Apache-2.0: build, fork, sell and extend it without copyleft. See Licensing (draft, not yet in effect).
Status: early preview. The app is used daily by its own team, but it is not 1.0. Read Roadmap and known issues before you rely on it.
Live updates (new versions delivered to the app as they ship) will be available shortly. Today the Windows app and the headless server check GitHub Releases and update on request (see Updates); Android and Docker are updated by hand.
tickets.weightExecutors), unless the ticket or its role already pins one. Richer routing rules are planned.infantry ask) without blocking. You see the question with its
options and the agent's recommended pick, answer once, and the answer reaches the agent as mail.Figure: clients talk to one orchestrator; the orchestrator places every agent session on a runner (this machine, or a Docker container anywhere). Agent mail between runners always travels through the orchestrator.
A runner is where an agent actually runs. The orchestrator is the daemon that holds your board, tickets and mail.
docker run the runner image, then paste its endpoint into Settings > Runners. See the runners guide.wss with a per-runner key; you can Rotate or Detach it. Update runner keeps a runner on the app's version (the image infantry-runner:<tag> must match the app).Full guide: Runners: concepts, setup, update, troubleshooting.
You can see the whole loop without a paid subscription by using opencode with one of its free models:
infantry harness-install opencode, needs Node 20+) or by hand, and check it with
infantry harness-status.opencode models shows what your install offers; availability of free
models is decided by opencode, not by Infantry AI).The board. Tickets move through To Do, In Progress, Pending and Done (plus Backlog). A ticket carries a role, a type, a weight and optionally a provider and model. Starting it cuts its own branch and worktree and runs the agent there; its report lands as a ticket comment. Pending is set by the daemon while a blocking ticket is open. Order in a column is priority.
Scripts. Your process lives in Lua scripts in <project>/.infantry/scripts/, not in anyone's memory: what happens
when a ticket is done, when mail arrives, when a build ends. Hooks run a script on a lane change, on incoming mail, on
a timer or on a named event, and a script can call every tool an agent has. See Scripting.
Plugins. The app is the OS, plugins are the programs: every tab, panel, board card and daemon tool, and every
agent CLI harness, is a plugin with a module.json. Write your own in a few minutes. See
Plugins and Harnesses and providers.
module.json, UI and daemon halves, config, building, installing, signing, a hello pluginmodule.json fieldBuild and preview the wiki site locally (MkDocs + Material, strict: a broken link fails; nothing is published):
infantry script run wiki --args '{"mode":"serve","port":8899}' (or "mode":"build" to write
<dist>/wiki/<sha8>). Needs scripting.exec.enabled and a venv with docs/requirements-wiki.txt
(pinned) at <dist>/wiki-venv; the script installs it. Without the script:
python -m mkdocs build --strict -f docs/mkdocs.yml -d <out>.
Screenshots the docs link are listed in docs/img/README.md.
Every release is on the latest Release page, built by the tag workflow
(.github/workflows/release.yml) and listed with its SHA-256 in SHA256SUMS (and latest.json).
| Platform | File | Notes |
|---|---|---|
| Windows (x64) | InfantryAI-<version>.msi |
The full desktop app with its own daemon. Per-user install, no admin prompt. Not code-signed yet: SmartScreen warns, choose More info > Run anyway. Updates itself in place. InfantryAI-<version>-windows.zip is the same app unpacked (do not update a zip copy with the MSI). |
| Android |
InfantryAI-<version>.apk (or -debug.apk) |
Beta. A phone client for a daemon on your PC or a server; sideloaded (allow "install unknown apps"). Today's APK is signed with a test or debug key: when the permanently signed APK ships, Android refuses it over this one, so you uninstall (the app's local data goes with it) and install again. |
| macOS (Apple silicon, beta, unsigned) |
InfantryAI-<version>-macos-arm64-beta.dmg (desktop app) and InfantryAI-server-<version>-macos-arm64.tar.gz (headless server) |
Beta. The .dmg ships in releases from 1.1.0 on. Built by CI and not yet tested on a real Mac. Intel Macs: not supported; use the web client from another machine. First launch: macOS warns about an unidentified developer, so right-click the app and choose Open, or run xattr -d com.apple.quarantine /Applications/InfantryAI.app. |
| Web | InfantryAI-web-<version>.zip |
The browser client's static files. You rarely need it: every daemon (desktop app, server archive, Docker) already serves it at http://<host>:<port>/. To serve your own copy, unpack it and point the daemon at the folder with INFANTRY_WEB_DIR=<folder>. See Web. |
| Headless server | InfantryAI-server-<version>-<os>-<arch>.{zip,tar.gz} |
The daemon + CLI with a bundled Java runtime: linux-x64, windows-x64, and macos-arm64 (beta). See Plain archive. |
The macOS server build is new and no one on the team runs a Mac every day. If you have an Apple silicon Mac, please run the headless server archive, create a project and run one ticket, then open an issue with what worked and what did not: your macOS version, the step that failed, and the error text you saw. The macOS desktop app (.dmg) ships in releases from 1.1.0 on (beta, unsigned).
| Client | What it is | How to get it |
|---|---|---|
| Windows desktop | The full app: board, agents, mail, knowledge. It runs its own daemon, so it works on its own with no server. |
InfantryAI-<version>.msi from the latest Release (or the -windows.zip app image). |
| Android | A phone client for a daemon running elsewhere (your PC or a server): watch agents, answer questions, move tickets. |
InfantryAI-<version>.apk from the latest Release, installed by hand (not on Google Play yet). |
| Web | A browser client (Kotlin/WASM) served by the daemon itself: board, agents, transcripts, messages, ticket starts. File, QR and camera features stay in the desktop and phone apps. | Open http://<host>:<port>/ on a daemon that has a token. See Web. |
CLI (infantry; agenthq is a deprecated alias) |
Every board, ticket, mail and knowledge command, for scripts and for the agents themselves. | Ships inside the desktop app and the server archive. |
| Headless server | The daemon with no UI, for a home server, a VM or a cloud box. | Docker image (build it yourself for now) or InfantryAI-server-<version>-<os>-<arch> archive from the Release. |
There is no Linux desktop app yet. The macOS desktop app is beta (Apple silicon, in releases from 1.1.0). On Linux or an Intel Mac, use the headless server plus the web client, the Android app or the CLI.
InfantryAI-<version>.msi from the latest Release and run it. It installs per
user (no admin prompt). The installer is not code-signed yet, so Windows SmartScreen will warn: choose
More info > Run anyway.npm install -g @anthropic-ai/claude-code, then run claude once to log in). The app can also install the supported
CLIs for you (infantry harness-install claude, also opencode and pi; needs Node 20+).allowEdits lets it edit files without asking, allowAll lets it
run anything, deny refuses every tool that is not pre-allowed). A tool that was refused shows on the ticket's card
as "blocked: denied".
Your data lives in %LOCALAPPDATA%\SuperiorSoft\InfantryAI, apart from the program, so upgrades and uninstalls keep it.
Details: docs/INFANTRY-INSTALL.md.
The Android app is a client: it needs a daemon to connect to (your Windows app or a headless server).
InfantryAI-<version>.apk from the latest Release on the phone and install it
(allow "install unknown apps" for your browser when Android asks).infantry remote on on the PC and restart the app; it prints the address and a token. See
ANDROID-TAILSCALE.md.ws://<host>:<port>/ws address and the token by hand). See Pairing.The daemon serves a browser client at http://<host>:<port>/ (the server archive, the Docker image and the desktop app
ship it). Open that address, enter the daemon's token once (the browser keeps it in its localStorage), and you get the
board, the agents, their transcripts, messages and ticket starts. The browser only connects to a daemon that has a token
(INFANTRY_TOKEN / INFANTRY_TOKEN_FILE, or remote access turned on), and only from the same origin. If you reach the
daemon by a host name it cannot see (a domain, or Docker), list it in INFANTRY_WEB_HOSTS (comma-separated). An offline
demo with fake data is on the token screen.
See Headless server below: build the image, create a token, docker run, then connect the
Android app, the web client or the CLI. From the CLI alone: infantry project create "<name>" <repo dir>, then
infantry ticket create --project <id> --title "..." --role fullstack and infantry ticket start <ticket id>.
The same daemon as the desktop app, with no UI. Use it on a home server, a VM or a cloud machine, then connect from Android or the CLI.
Security first: the token is the only credential, and it grants command execution through agents. Never expose the raw port to the internet. Bind to loopback and put a TLS reverse proxy (Caddy, nginx) or a VPN/SSH tunnel (Tailscale works well) in front; it must pass WebSocket upgrades.
The image (infantryai/infantry-ai) is not published yet; build it locally:
./gradlew :superiorSoftLibrary:infantry:dockerContext
docker build -t infantryai/infantry-ai:dev superiorSoftLibrary/infantry/build/docker
Run (the token is mandatory, at least 32 characters: the daemon refuses a non-loopback bind without one):
openssl rand -hex 32 > infantry_token
openssl rand -hex 32 > infantry_keystore_key
docker run -d --name infantry-ai -p 127.0.0.1:8787:8787 \
-e INFANTRY_TOKEN_FILE=/run/secrets/infantry_token \
-v ./infantry_token:/run/secrets/infantry_token:ro \
-e INFANTRY_KEYSTORE_KEY_FILE=/run/secrets/infantry_keystore_key \
-v ./infantry_keystore_key:/run/secrets/infantry_keystore_key:ro \
-v infantry-data:/data infantryai/infantry-ai:dev
infantry --url ws://127.0.0.1:8787/ws --token-file ./infantry_token board
(Git Bash on Windows rewrites /run/... into a Windows path: prefix the docker run with MSYS_NO_PATHCONV=1.)
/data holds the database, logs and state (INFANTRY_STATE_DIR). Keep the same volume across image upgrades.INFANTRY_PORT (default 8787), INFANTRY_HOST (default 0.0.0.0), INFANTRY_TOKEN or INFANTRY_TOKEN_FILE
(e.g. a Docker secret at /run/secrets/infantry_token); other INFANTRY_* variables are read as usual.HEALTHCHECK polls GET /health (the one path open without a token).-e INFANTRY_REPO=/work/repo -e INFANTRY_BASE_BRANCH=main (see docker/README.md).infantry --url ... --token-file ... harness-install claude (also opencode, pi); they land in
/data/harness-tools, so they survive container upgrades, and harness-status shows them. Sign-in is per CLI: pass the
provider's API key (-e ANTHROPIC_API_KEY=...) or log in once with docker exec -it infantry-ai claude and keep the login with
-v infantry-home:/home/infantry. A CLI you already have can be mounted instead (-v /path/to/cli:/usr/local/bin/<name>:ro)./data/keystore.json. A container has no OS keychain, so mount the master
key and point INFANTRY_KEYSTORE_KEY_FILE at it (as above; INFANTRY_KEYSTORE_KEY also works). Without it the daemon falls
back to /data/keystore.key, which is only as safe as the volume. Keep the key file outside the volume and back it up.The same daemon with its own Java runtime bundled (nothing to install), one per OS on the Release:
InfantryAI-server-<version>-windows-x64.zip, InfantryAI-server-<version>-linux-x64.tar.gz,
InfantryAI-server-<version>-macos-arm64.tar.gz (beta). Unpack it and start the daemon (README.txt inside lists every setting):
# Linux / macOS
INFANTRY_TOKEN_FILE=./infantry_token INFANTRY_HOST=0.0.0.0 ./InfantryAI-server-<version>-linux-x64/bin/infantry-server.sh
# Windows (cmd)
set INFANTRY_TOKEN_FILE=%CD%\infantry_token& set INFANTRY_HOST=0.0.0.0& InfantryAI-server-<version>-windows-x64\bin\infantry-server.bat
Without INFANTRY_HOST it binds to 127.0.0.1 only. State goes to ~/.infantry unless INFANTRY_STATE_DIR says otherwise, so do
not run it next to an installed desktop app on the same state dir and port. bin/infantry in the archive is both the CLI and
the update supervisor, on the same bundled runtime: a command word (bin/infantry board, health, --help) runs the CLI;
no argument or serve starts the daemon under the supervisor (the first run copies the folder to <parent>/versions/ and
writes <parent>/infantry, the entry point from then on; see README.txt). Agent CLIs are the machine's own (infantry harness-install <id> needs Node 20+).
A client connects to a daemon with two things: its address (ws://<host>:<port>/ws, or wss:// behind TLS) and its
token. Pairing hands both over in one step:
infantry://connect?url=...&token=...&name=....The QR code and the link contain the token: treat them like a password. Show them only to devices you own, and never
post a screenshot of them. To revoke access, change the token (infantry remote off / on, or a new token file) and
restart the daemon.
SHA256SUMS (a mismatch is refused and deleted), asks first if
agents are still running, then upgrades in place and restarts. Your data is kept.infantry update (or Configuration > Server > Update) installs the archive for its own OS from
the same Release, checks it against SHA256SUMS, keeps the previous version, and infantry rollback returns to it. The
data dir is never touched.docker pull to run;
recreate the container on the same /data volume.InfantryAI-<version>.apk (release-signed) builds; a -debug.apk cannot upgrade a release install.Details: docs/RELEASING.md and UPDATES.md.
Which agents does it run? Claude Code, opencode and pi out of the box. Any other command-line agent can be added with a JSON descriptor; see QUICKSTART.md.
Do I need an account with you? No. There is no Infantry AI cloud service. You bring your own agent CLIs and their logins or API keys; the daemon runs on your hardware.
Where is my data? Windows app: %LOCALAPPDATA%\SuperiorSoft\InfantryAI. Server: ~/.infantry or INFANTRY_STATE_DIR
(/data in Docker). Secrets (tokens, keys) are sealed in a keystore there.
Does it cost anything? The app is free to download. The agents use your own subscriptions or API keys with their providers, billed by those providers.
Can several people share one server? One daemon has one token today; anyone with it has full access. Per-user accounts are not built yet.
Why do some names say AgentHQ? That was the project's earlier name. The old names still work so nothing breaks on
upgrade: AGENTHQ_* variables are read as fallbacks for INFANTRY_*, the .agenthq folder is read when .infantry
has no copy, and agenthq is a deprecated alias of the infantry command.
Is it safe to expose to the internet? Not directly. See the security note under Headless server.
| Symptom | What to check |
|---|---|
| SmartScreen blocks the installer | Expected for now: the MSI is not code-signed yet. More info > Run anyway. |
| An agent provider is missing from the picker | The CLI must be installed and on the daemon's PATH (infantry harness-status), then restart the app. |
| A ticket refuses to start: "no directory configured" / "no base branch configured" | Set the project's repository and its base branch (Git tab > "Base branch for new tasks", or infantry project base <projectId> <branch>; Docker: INFANTRY_REPO and INFANTRY_BASE_BRANCH). A ticket also needs a role. |
| Phone says it cannot connect | Same network or Tailscale? Firewall open for the daemon port? Address ends in /ws? A 401/403 means a wrong token. |
| Server refuses to start: "refusing to start" | A non-loopback bind needs a token of at least 32 characters. |
| "Check for updates" says updates are off | Set INFANTRY_UPDATE_REPO=owner/repo (or repo= in update.properties). |
| Anything else | Open Configuration > Logs > Open logs folder and attach infantry.log to a bug report. Read it first: logs can hold project paths and agent output. |
More: QUICKSTART.md troubleshooting and INSTALL logs.
What is not finished, stated plainly:
Planned next: published Docker image, signed Windows builds, macOS/Linux desktop packages, multi-user access. Priorities can change; watch the Releases page.
infantry.log).Bug reports and feature requests are welcome now: open an issue. Pull requests from outside the team are not accepted yet; for now, please send ideas and fixes as issues. How to build, branch, test and commit: CONTRIBUTING.md. Everyone taking part follows the Code of Conduct.
The core (MPL-2.0) is the community foundation. Sponsorship and donations pay for keeping it stable and backward compatible.Starring the repository and filing good bug reports help too.
The core is a community effort; the rest is yours.
Infantry AI is licensed per directory. Every source file names its license in an SPDX-License-Identifier header.
| License | What it covers |
|---|---|
| MPL-2.0 (the core) |
superiorSoftLibrary/infantryProtocol, superiorSoftLibrary/infantryCore, superiorSoftLibrary/infantryRunner, superiorSoftLibrary/infantry, and the reserved plugins/core/
|
| Apache-2.0 (everything else) | the plugin API and host, the SDKs, the board, the UI core, the apps, samples/, plugins/, docs/, docker/, scripts/ and the build files |
| Neither (trademark) | the name "Infantry AI", the logo and the emblem |
LICENSE.Draft. The split is applied but not official until the public launch. Not legal advice.
Requires JDK 21 (Gradle toolchain resolution via foojay) and, for the Android module, an Android SDK. Run only one Gradle build at a time.
./gradlew :superiorSoftLibrary:infantry:compileKotlin :superiorSoftLibrary:infantryUi:compileKotlin
./gradlew :superiorSoftLibrary:infantry:installDist # build/install/infantry/bin/infantry (and the agenthq alias)
./gradlew :superiorSoftLibrary:infantryUi:packageReleaseMsi # Windows installer
./gradlew :superiorSoftLibrary:infantry:headlessDist # server archive for this OS
Modules (all under superiorSoftLibrary/; the prefix keeps :superiorSoftLibrary:* paths stable):
infantry: daemon + infantry CLI (JVM; agenthq stays as a deprecated alias)infantryUiCore: shared UI core (Compose Multiplatform)infantryUi: desktop UIinfantryAndroid: Android shellinfantryHeadless: test-only guard that the daemon runs with no UISecrets guard: ./gradlew verifySecretsNotTracked fails if keys, keystores or tokens are tracked. Signing secrets belong in
secrets.local.properties (gitignored) or environment variables. More in CONTRIBUTING.md.
INFANTRY_* variable is also read under its old name AGENTHQ_* (AGENTHQ_PORT, AGENTHQ_TOKEN, ...). The old
names keep working; when both are set the INFANTRY_* one wins.© SuperiorSoft LLC. Infantry AI is a product of SuperiorSoft LLC.
Daemon: what the core is and the orchestrator/runner split are in docs/DAEMON-CORE.md.