Getting Started

Antimatter is split into two halves — the Gateway + Adapter running on your desktop, and the Mobile App in your pocket — linked by a secure, encrypted WebSocket tunnel.

New to Antimatter?

Start here and follow the steps in order. The whole setup takes less than 5 minutes.

Prerequisites

Requirement	Details
Python 3.11+	Required by the antimatter-gateway Gateway
Node.js 22+	Required if using the ag or cc adapters
Android 8.0+ or iOS 16+	Mobile companion app
uv (recommended)	Modern Python package manager — faster installs

---

Step 1 — Install the Mobile App

Android

Currently, the latest versions are only available via GitHub.

1. Go to GitHub Releases.
2. Download the latest antimatter-vX.X.X.apk.
3. Enable Install from Unknown Sources on your Android device.
4. Open the APK to install.

(Note: The F-Droid version is currently outdated).

iOS

The iOS app is currently in early scaffolding stages. It will eventually mirror the full Android feature set. Build from source:

cd ios/
open AntimatterApp.xcworkspace  # Open in Xcode 16+

See the iOS App page for detailed build instructions.

---

Step 2 — Install & Start the Gateway

The Antimatter Gateway (antimatter-gateway) is the secure infrastructure daemon. It manages Cloudflare tunnels, cryptographic keys, and routes messages between your phone and your AI adapters.

Install via uv (recommended)

uv tool install antimatter-gateway

Or via pip

pip install antimatter-gateway

Then start the Gateway:

Start the gateway

antimatter-gateway start

When you run this command, you will be prompted to choose a connection mode:

1. Local Network (LAN) — Best for local testing over WiFi.
2. Cloudflare Tunnel — Connect from anywhere over the internet.
3. Both — Available everywhere.

The Gateway will then start a local IPC server at http://127.0.0.1:8765, generate keys, and optionally start a Cloudflare tunnel.

Runs in the Background

antimatter-gateway start automatically detaches and runs silently in the background. Use antimatter-gateway status to check if it is running, and antimatter-gateway stop to kill it.

---

Step 3 — Pair Your Phone

With the Gateway running, generate a QR pairing code:

Terminal on your desktop

antimatter-gateway pair

1. You will be prompted to choose which connection method to pair with (LAN or Cloudflare).
2. A QR code will appear in the terminal.
3. In the Antimatter app, tap the Scan QR Code button and point your camera at the code.

✅ You are now cryptographically paired! Even without any AI agents running, you can now instantly browse your workspace files from your phone.

---

Step 4 — Install Your Adapters

Now you can attach your AI agents. The Gateway will automatically detect them. You can run multiple at once.

Antigravity IDE (ag) — Recommended

1. Install the antimatter-ag extension via OpenVSIX in your IDE.
2. The extension automatically connects to the running Gateway on activation.

Antigravity 2.0 (ag2) — Python Daemon

pip install antimatter-ag2
antimatter-ag2 init  # Run once

Then start it:

antimatter-ag2 start       # Background daemon
# OR
antimatter-ag2 run_server  # Foreground process

Claude Code (cc) — Node.js Daemon

Experimental

The Claude Code adapter is currently under heavy development and may not function fully.

npm install -g antimatter-cc
antimatter-cc start

Connecting without Cloudflare (Local Network)

If your devices are on the same local network, you can bypass Cloudflare and connect directly over WebSockets. The Gateway listens on 0.0.0.0, meaning it accepts connections from any device on your local network.

Security Note: Although the raw transport (http://) is unencrypted, Antimatter applies Application-Layer End-to-End Encryption (Ed25519 authentication + X25519 ECDH) to every payload, so it remains completely secure over your local WiFi.

When entering the manual connection URL, use the format http://<IP_ADDRESS>:8765, where <IP_ADDRESS> depends on your device:

• Desktop/Web (Same Machine): Use http://localhost:8765 or http://127.0.0.1:8765.
• Android Emulator: Use http://10.0.2.2:8765 (this special IP automatically routes to your computer’s localhost).
• Physical Android (Same WiFi/Router): Use your computer’s local IP address (e.g., http://192.168.1.X:8765). Find it using ipconfig (Windows) or ip a / ifconfig (Mac/Linux).

---

Features Overview

AI Chat Interface

• Live trajectory streaming — watch tool calls, file edits, and thinking steps happen in real-time.
• Rich Markdown rendering — AI responses render with full syntax highlighting, tables, and code blocks.
• Remote prompting — type a message or attach an image and it’s injected directly into the active agent.
• Thinking indicator — animated typing bubble when the agent is generating.

Workspace Explorer

• Live file tree — browse your IDE workspace in real-time.
• File viewer — tap any file to read its contents.
• File writing — make quick edits on the go.

Workspace Whitelisting

By default, the gateway allows access only to the directory from which the adapter was started. If you want to explicitly allow the Android App to browse and switch between specific workspace directories, you can whitelist them by adding an allowed_workspaces array to your daemon config file (~/.antimatter_daemon/config.json):

{
    "allowed_workspaces": [
        "/home/user/my-project",
        "/home/user/another-project"
    ]
}

Security

• Biometric auth gate — Face Unlock or fingerprint required before any connection.
• Ed25519 verification — cryptographic identity verification on every connection.
• Zero port exposure — no firewall rules, no port forwarding. Everything goes through Cloudflare.

---

Troubleshooting

Phone can’t connect

Invalid token (close 4001)

The pairing token on the phone doesn’t match the Gateway. Fix: Re-run antimatter-gateway pair and scan the new QR code.

Gateway not running

If you see “Connection refused”:

1. Run antimatter-gateway start
2. Check if port 8765 is in use: lsof -i :8765

No agent activity shows up

• Make sure an adapter (antimatter-ag2, etc.) is running.
• Make sure an agent conversation is actively running in the IDE/CLI.
• Check the Gateway logs: cat ~/.antimatter_daemon/gateway.log

FAQ

Is Antimatter affiliated with Google? No. It’s an unofficial, community-driven project, not affiliated with Google or the AntiGravity IDE project.

Do I need a custom domain? Yes. For security reasons, Antimatter requires a stable Cloudflare Zero Trust tunnel with your own domain name. Temporary trycloudflare tunnels are not supported.

Where are my keys stored? In your OS keychain — never written to plain-text config files. They persist across restarts.

What data does Antimatter collect? None. It’s fully local + tunnel. No telemetry, no analytics, no cloud services beyond Cloudflare.

---

Saif Mukhtar

Creator & Lead Developer of Antimatter · Android, iOS & Python engineer

🌐 saifmukhtar.dev⭐ GitHub👤 Gravatar❤️ Sponsor