Flux is an open-sourced CLI tool that lets developers build and deploy LangChain agents that connect to iMessage at no cost and under 5 seconds.

• Deploy with a single command: Export a LangChain agent and deploy it to iMessage with one command
• Text your agent from your phone: Send an iMessage to the Flux number and get responses from your running agent
• Testing mode: Test your agent through your terminal before connecting to the iMessage bridge
• Phone Number Authentication: Log in with just your phone number and iMessage
• Agent Validation: Automatically validate your LangChain agent in the CLI

Get started with Flux in seconds:

# No installation needed - use npx directly
npx @photon-ai/flux login

# Create your agent file
echo 'export default {
  async invoke({ message }: { message: string }) {
    return `You said: ${message}`;
  }
};' > agent.ts

# Test locally
npx @photon-ai/flux run --local

# Deploy to production
npx @photon-ai/flux run --prod

For the best experience, install Flux globally:

npm install -g @photon-ai/flux
# or
bun add -g @photon-ai/flux

Then run commands directly:

flux login
flux run --local
flux run --prod

You can use Flux without installing it by using npx or bunx:

npx @photon-ai/flux login
npx @photon-ai/flux run --local
// or
bunx @photon-ai/flux login
bunx @photon-ai/flux run --local

Note: When using npx or bunx, there's no need to install the package first. npx or bunx will download and execute it automatically.

If you're integrating Flux into a project:

npm install @photon-ai/flux
# or
bun add @photon-ai/flux

Create an agent.ts file with your LangChain agent. Make sure to have export default agent. Here's a simple example:

// agent.ts
export default {
  async invoke({ message }: { message: string }) {
    return `You said: ${message}`;
  }
};

Authenticate with your phone number and iMessage:

flux login
# or
npx @photon-ai/flux login

Example session:

Enter your phone number (e.g. +15551234567): +1234567890
[FLUX] Requesting verification code...
[FLUX] Verification code: d33gwu
[FLUX] Opening iMessage to send verification code...
[FLUX] Please send the code "d33gwu" to +16286298650 via iMessage.
[FLUX] Waiting for verification...
[FLUX] Successfully logged in as +1234567890

If already logged in:

[FLUX] Already logged in as +1234567890

To log out:

flux logout

[FLUX] Logged out.

Validate that your agent works and exports correctly:

flux validate
# or
npx @photon-ai/flux validate

Output:

[FLUX] Validating agent.ts...
[FLUX] Agent is valid!

Test your agent through your terminal (no iMessage connection):

flux run --local
# or
npx @photon-ai/flux run --local

Interactive session:

[FLUX] Welcome to Flux! Your agent is loaded.
[FLUX] Type a message to test it. Press Ctrl+C to exit.

You: Hello!
[FLUX] Thinking...
Agent: Hello! How can I assist you today?

Run your agent locally and connect it to the iMessage bridge. When you message the Flux number (+16286298650) from your registered phone, you'll receive responses from your LangChain agent:

flux run --prod
# or
npx @photon-ai/flux run --prod

Output:

[FLUX] Loading agent from agent.ts...
[FLUX] Agent loaded successfully!
[FLUX] Connected to server at fluxy.photon.codes:443
[FLUX] Registered agent for +1234567890
[FLUX] Agent running in production mode. Press Ctrl+C to stop.
[FLUX] Messages to +1234567890 will be processed by your agent.

Now text +16286298650 from your phone to interact with your agent!

Authentication is based on iMessage to ensure secure and simple access:

1. Code Generation: The server generates a unique UUID for each login attempt
2. Phone Verification: You send the verification code to the Flux number (+16286298650) via iMessage to prove phone ownership
3. Token Issuance: Once verified, the server issues an authentication token
4. Persistent Login: Credentials (token, phone, timestamp) are saved to credentials.json, so you only need to log in once

An agent with a weather tool (returns mock data).

import * as z from "zod";
import { createAgent, tool } from "langchain";

const getWeather = tool(
  ({ city }) => `It's always sunny in ${city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string(),
    }),
  },
);

const agent = createAgent({
  model: "claude-sonnet-4-5-20250929",
  tools: [getWeather],
});

export default agent

An advanced agent with memory:

// agent.ts
import "dotenv/config";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, AIMessage, SystemMessage } from "@langchain/core/messages";

const llm = new ChatOpenAI({ modelName: "gpt-4o-mini" });
const history: Array<HumanMessage | AIMessage> = [];

export default {
  async invoke({ message }: { message: string }) {
    history.push(new HumanMessage(message));
    
    const response = await llm.invoke([
      new SystemMessage("You are a helpful assistant. Be concise."),
      ...history,
    ]);
    
    const reply = response.content as string;
    history.push(new AIMessage(reply));
    
    // Keep last 20 messages to avoid token limits
    if (history.length > 20) {
      history.splice(0, 2);
    }
    
    return reply;
  }
};

Connecting agents to messaging platforms traditionally involves complex processes like setting up servers, configuring webhooks, and dealing with platform APIs. Most solutions rely on SMS or WhatsApp, which can be unintuitive for many users.

Flux solves these problems:

• Deploy in < 5 seconds — Link your LangChain agent to iMessage with a single command
• Fully iMessage native — Direct iMessage integration, not SMS or WhatsApp
• Zero Infrastructure — No servers to manage, webhooks to configure, or Apple Developer account needed
• Open source — Fully community-driven and transparent
• Free to use — No subscription fees or hidden costs

Important: Flux is designed for personal use and development. When you deploy an agent with Flux, only your registered phone number can interact with it via iMessage. This means:

• ✅ Perfect for personal assistants and prototypes
• ✅ Great for testing and development
• ✅ Simple single-user experience
• ❌ Not designed for multi-user conversations
• ❌ No enterprise-level user management

For enterprise-level iMessage agents with advanced features, consider our Advanced iMessage Kit:

• Multi-user support — Handle thousands of users simultaneously
• Dedicated phone line — Get your own iMessage number
• Enterprise features — Advanced conversation management and analytics
• Production-ready — Enhanced stability and performance
• More features — Additional tools and integrations

Explore Advanced iMessage Kit →

• Node.js 18+ or Bun (for the CLI)
• Python 3.9+ (for the agent, if using Python-based LangChain)
• LLM API Keys (e.g., OpenAI API key for GPT-powered agents)

We welcome contributions! Flux is fully open source and community-driven. Feel free to:

• 🐛 Report bugs
• 💡 Request features
• 🔧 Submit pull requests
• ⭐ Star the repository

• Discord: Join our community at discord.gg/bZd4CMd2H5
• Issues: Report problems on GitHub Issues
• Documentation: Check out this README for comprehensive guides

MIT License - see the LICENSE file for details.