Formicx
Formicx is an open-source Linux-based operating environment designed specifically for developing, deploying, running, and coordinating persistent autonomous AI agents.
Core Philosophy: Linux manages processes. Formicx manages agents.
While Linux handles processes, memory, CPU scheduling, filesystems, networking, and hardware, Formicx provides an agent operating layer managing operational identities, lifecycles, framework-independent process management, developer CLI control planes, multi-agent teams, reusable service integrations, and agent nodes.
Why Formicx?
Traditional operating systems like Linux, macOS, and Windows were engineered for web servers, static binaries, and human-driven applications. They were never designed for autonomous, non-deterministic AI agent fleets.
Formicx fills the architectural gap between high-level LLM agent frameworks (LangChain, AutoGen, CrewAI) and low-level operating system kernels.
| Problem / Issue in Current OS | Impact on AI Agent Fleets | How Formicx Solves It |
|---|---|---|
| Anonymous Process Model | The kernel sees every agent as generic python3 processes with zero logical context or agent identity. |
1:1 Kernel PID Mapping: Assigns a first-class operational identity and kernel process mapping to every agent. |
| Opaque Resource Telemetry | OS monitors container black-boxes, making it impossible to detect agent-specific memory leaks or LLM retry spikes. | Agent-Aware Telemetry: Collects non-blocking CPU, RAM (psutil), thread count, and uptime per agent via CLI and API. |
| No Inter-Agent Access Control | Prompts attempt to enforce rules ("do not invoke tool X"), leading to rogue agent executions and security breaches. | Authoritative Control Plane ACLs: Enforces strict policy envelopes defining authorized agent-to-agent communication paths. |
| Manual Network Configuration | Inter-agent coordination across local devices requires hardcoded IP addresses or centralized cloud webhooks. | Zero-Config mDNS Peer Discovery: Automatically discovers agent nodes across local networks over peer-to-peer mDNS. |
| Fragile Runtime Lifecycles | An unhandled exception or OOM error crashes the parent Python process, killing the entire agent swarm without trace. | Dedicated Supervisor Daemon (formicxd): Provides daemonized background lifecycle governance (start, stop, restart, recover). |
Quickstart
Prerequisites & Installation
Formicx requires Python 3.11+.
Clone the repository and install Formicx in editable mode with development dependencies:
git clone https://github.com/Abbilaash/Formicx.git
cd Formicx
pip install -e ".[dev]"
This registers the global CLI executables formicx and formicxd.
Starting the Daemon
Launch the formicxd supervisor daemon on your host machine:
formicxd
By default, formicxd starts the local HTTP control API at http://127.0.0.1:8642, initializes resource monitoring, and starts local mDNS peer discovery.
Example
Create, register, and execute a Calculator Agent with an add capability using Formicx.
1. Create the Calculator Agent Project
Create a directory named calculator-agent containing agent.yaml and main.py:
calculator-agent/agent.yaml (Manifest):
name: calculator-agent
version: 0.1.0
runtime:
language: python
framework: custom
entrypoint: main.py
capabilities:
- add
calculator-agent/main.py (Implementation):
import sys
from formicx import Agent
class CalculatorAgent(Agent):
def on_start(self):
print(f"[{self.name}] Calculator Agent started with ID: {self.id}", flush=True)
def on_message(self, message):
payload = message.payload or {}
action = payload.get("action")
if action == "add":
a = float(payload.get("a", 0))
b = float(payload.get("b", 0))
result = a + b
print(f"[{self.name}] Calculating {a} + {b} = {result}", flush=True)
self.reply(
message,
{
"action": "add",
"a": a,
"b": b,
"result": result,
"status": "success",
},
)
def on_stop(self):
print(f"[{self.name}] Stopping cleanly.", flush=True)
if __name__ == "__main__":
CalculatorAgent().run()
2. Start the Daemon
In Terminal 1, run:
formicxd
3. Register & Start the Agent
In Terminal 2, run:
# Register the agent project manifest
formicx agent register ./calculator-agent
# Start the agent process
formicx agent start calculator-agent
# Check agent status
formicx agent list
4. Send a Message & Receive Response
Send an add request message to the agent:
formicx message send calculator-agent calculator-agent "{\"action\":\"add\",\"a\":15,\"b\":27}"
Terminal Output:
[calculator-agent] Calculating 15.0 + 27.0 = 42.0
Alternatively, query the agent via the Python DaemonClient SDK:
import time
from formicx import DaemonClient
client = DaemonClient()
# Send calculation request
client.send_message(
sender="calculator-agent",
recipient="calculator-agent",
message_type="REQUEST",
payload={"action": "add", "a": 25, "b": 17},
)
time.sleep(0.5)
# Fetch calculation response from history
history = client.get_inbox("calculator-agent", history=True)
for msg in reversed(history):
payload = msg.get("payload", {})
if "result" in payload:
print("Result:", payload)
break
Command Line Guide
The formicx CLI provides complete operational control over agents, daemon states, network nodes, communication policies, and MCP servers.
| Command Group | Command Syntax | Purpose |
|---|---|---|
formicx agent |
formicx agent <subcommand> |
Create, validate, register, start, stop, restart, inspect, and monitor agent processes. |
formicx daemon |
formicx daemon <subcommand> |
Check status, ping health, start, or stop the formicxd background supervisor server. |
formicx node |
formicx node <subcommand> |
Inspect local node identity and list active mDNS discovered peer nodes across local networks. |
formicx message |
formicx message <subcommand> |
Send messages, read/peek inboxes, view history, or broadcast events across agents. |
formicx policy |
formicx policy <subcommand> |
Manage authoritative communication access control lists (ACLs) between agents. |
formicx mcp |
formicx mcp <subcommand> |
Launch the Model Context Protocol (MCP) server for integration with AI coding agents. |
formicx agent
Commands for managing agent definitions and OS process lifecycles.
create
Scaffold a new Formicx agent project directory from a template.
formicx agent create research-agent
formicx agent create hello-agent --template basic
validate
Validate an agent project's agent.yaml manifest schema and Python entrypoint syntax without running code.
formicx agent validate ./calculator-agent
register
Register an agent directory or agent.yaml manifest with formicxd.
formicx agent register ./calculator-agent
list
List all registered Formicx agents, their operational status, and active OS process IDs (PIDs).
formicx agent list
status
Display detailed runtime status, entrypoint path, language runtime, PID, and uptime for an agent.
formicx agent status calculator-agent
start
Start a registered agent as an independent OS child process supervised by formicxd.
formicx agent start calculator-agent
stop
Gracefully terminate a running agent process.
formicx agent stop calculator-agent
restart
Restart a running or stopped agent process cleanly.
formicx agent restart calculator-agent
resources
Inspect real-time CPU %, RAM (RSS memory), thread count, and OS process metrics per agent or across all agents.
formicx agent resources
formicx agent resources calculator-agent
formicx daemon
Commands for managing the formicxd supervisor service.
start
Start the background formicxd supervisor daemon server.
formicx daemon start
status
Display daemon operational status, total managed agents count, and running agents count.
formicx daemon status
health
Perform a fast HTTP health check ping against formicxd.
formicx daemon health
stop
Stop the formicxd daemon and gracefully terminate all active agent child processes.
formicx daemon stop
formicx node
Commands for inspecting local host node identity and peer discovery.
info
Display local node name, host IP address, control port, and unique node identifier.
formicx node info
peers
List active Formicx daemon peer nodes automatically discovered over mDNS on local networks.
formicx node peers
formicx message
Commands for sending and reading inter-agent messages.
send
Send a payload message from a sender agent to a target recipient agent.
formicx message send agent-a agent-b "{\"action\":\"ping\"}"
inbox
Receive or peek the next unread message from an agent's inbox queue.
formicx message inbox calculator-agent
list
List inbox messages or historical delivered messages for an agent.
formicx message list calculator-agent --history
broadcast
Broadcast an event payload to all active running agents across the node.
formicx message broadcast admin-agent "{\"event\":\"system_alert\"}"
formicx policy
Commands for managing inter-agent communication security policies (ACLs).
allow
Grant permission for a source agent to send messages/invoke actions on a target agent.
formicx policy allow worker-agent database-agent
deny
Revoke communication permission between a source agent and target agent.
formicx policy deny worker-agent database-agent
list
Display all active communication access control rules.
formicx policy list
reset
Reset all policy rules to default permissions.
formicx policy reset
formicx mcp
Commands for managing Model Context Protocol integration.
start
Launch the formicx-mcp server to connect Formicx directly to AI coding agents.
formicx mcp start
MCP Integration for AI Coding Agents
Formicx includes a built-in Model Context Protocol (MCP) server (formicx-mcp or formicx mcp start) that enables AI coding assistants (Antigravity, Cursor, Claude Desktop, Copilot) to inspect, manage, and communicate with Formicx agents directly inside your IDE environment.
MCP Features
- Native Tools:
formicx_list_agents,formicx_register_agent,formicx_start_agent,formicx_stop_agent,formicx_send_message,formicx_get_inbox,formicx_daemon_status. - Complete Context & Documentation: AI assistants can invoke
formicx_get_documentationor readformicx://docs/*MCP resources to get full context on Formicx SDK usage, manifests, CLI commands, and architecture.
IDE Configuration (mcpServers)
Add Formicx to your IDE's MCP configuration settings file:
{
"mcpServers": {
"formicx": {
"command": "formicx-mcp",
"args": []
}
}
}
For detailed IDE setup guides and documentation, see the MCP Integration Guide.
Running Tests
Execute the complete Formicx test suite using pytest:
pytest
Or using uv:
uv run pytest
Contributing
Formicx welcomes open-source contributions! Whether you are fixing a bug, extending CLI commands, or building new agent templates, check out our guides:
- Contributing Guide — Setup local dev environment, run tests, and submit pull requests.
- Good First Issues Guide — Curated beginner-friendly tasks with clear pointers and acceptance criteria.
License
Formicx is released under the MIT License.
Made with ❤️. If you encounter any issues, please open an issue/thread along with a detailed description.
Metadata
Release files for formicx 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| formicx-0.1.0.tar.gz | 85.4 kB | Without provenance | Details for formicx-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| formicx-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for formicx-0.1.0-py3-none-any.whl |
Total release size: 162.6 kB
Release files / formicx-0.1.0.tar.gz
| Download URL | formicx-0.1.0.tar.gz |
|---|---|
| Size | 85.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a92088ab2b8d16323fbaf036d5961f022729a895d2504166de4f7e23ec4edea3
|
|
BLAKE2b-256 checksum How to use checksums |
a1d5f7053b26619db89b046f82f55320bb453b1fefe6a4749f8928d9e9998d62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / formicx-0.1.0-py3-none-any.whl
| Download URL | formicx-0.1.0-py3-none-any.whl |
|---|---|
| Size | 77.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d10c54729649ef1d1bdce7b2a6d6ff05a59711c66b9760afc15ebb960c44d29c
|
|
BLAKE2b-256 checksum How to use checksums |
2131003bda620793af546061003753aa3b4ae3e17d54863347f0715f2871d3b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for formicx 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.