port42

Python SDK for Port42 — connect external agents to your macOS companion.

Install

pip install port42

Quickstart

fromport42importAgentagent=Agent("my-agent", channels=["#general"])
@agent.on_mentiondefhandle(msg):
returnf"Hello {msg.sender}!"agent.run()

Port42 must be running. The agent connects via WebSocket and appears in your companion list.

With LangChain

pip install 'port42[langchain]'

fromport42importAgentfromport42.langchainimportPort42CallbackHandlerfromlangchain_anthropicimportChatAnthropicagent=Agent("assistant", channels=["#general"])
handler=Port42CallbackHandler(agent)
chain=ChatAnthropic(model="claude-sonnet-4-5")
@agent.on_mentiondefhandle(msg):
result=chain.invoke(msg.text, config={"callbacks": [handler]})
returnresult.contentagent.run()

CLI — send messages and interact from the terminal

pip install 'port42[cli]'

Get an invite URL from Port42: right-click a channel → Add Companion → Remote → Connect LLM CLI.

# Send a message
port42 send "hello" --invite "<url>" --owner "gordon" --name "$(basename $PWD)"# Ask an agent and wait for its reply (prints decrypted response)
port42 ask "@agent what is the status?" --invite "<url>" --owner "gordon" --timeout 120
# Pipe command output to a channel (one message on EOF)
./build.sh 2>&1| port42 bridge --invite "<url>" --owner "gordon"# Stream live output line-by-line as it arrives
tail -f server.log | port42 bridge --invite "<url>" --owner "gordon" --live

The invite URL carries the gateway address, channel ID, and E2E encryption key — no separate configuration needed.

Scaffold a project

pip install 'port42[cli]'
port42 init my-agent
cd my-agent && python agent.py

Templates: basic, langchain, pipeline

Bridge APIs

Once connected, your agent can call Port42 device APIs:

agent.terminal_exec("ls ~/Desktop")
agent.screen_capture(scale=0.5)
agent.notify("Done", body="Pipeline complete")
agent.port_push(port_id, {"key": "value"})
agent.rest_call("https://api.example.com/data", secret="MY_API_KEY")