Skip to main content

Formicx Logo

License Open Source Views Forks Stars

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_documentation or read formicx://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:


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)

Source distribution for formicx 0.1.0
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)

Table of built distributions (wheels) for formicx 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page