Single-File Architecture
amux is One Python File (2026)

amux’s entire server, dashboard, and REST API live in a single Python file (amux-server.py). No external dependencies beyond Python 3 and tmux. Self-heals by restarting itself on file save. Deploy in under 2 minutes.

Last updated: July 11, 2026

What lives inside a single file

• Python HTTP server (stdlib only — no Flask, FastAPI, or Django)
• REST API (~60 endpoints: sessions, board, notes, CRM, email, calendar, scheduler, browser automation)
• SSE event streaming backbone (live dashboard updates, ping/pong health checks)
• Web dashboard: complete HTML, CSS, and JavaScript inline as string constants
• SQLite schema and query layer (board, sessions, notes, CRM, calendar, schedules)
• Self-healing watchdog (detects crashed agents, restarts them automatically)
• Email integration (Gmail API + Mail.app fallback), CRM, browser automation API
• iCal feed generator (syncs to Google Calendar and Apple Calendar)
• Tunnel client (connects to amux cloud relay for public HTTPS URLs)

Why single-file?

• No dependency hell — git clone && python3 amux-server.py just works. Nothing to pip install.
• Trivially deployable — copy one file to a new machine; no package manager, no virtualenv, no npm, no build step
• Forkable and diffable — diff the whole project at once; pull requests touch one file
• Self-restarting — the server watches its own mtime via os.execv; edit and save, it reloads automatically
• Auditable — every endpoint, every SQL query, every piece of business logic is visible in one place with no hidden framework magic

Technical implementation

amux uses Python’s http.server.BaseHTTPRequestHandler as the server base. Routing is a single if/elif chain on self.path. SQLite handles all persistent storage via Python’s stdlib sqlite3 module. Server-sent events (SSE) are streamed over persistent HTTP connections. The web dashboard — all HTML, CSS, and JavaScript — is stored as Python string constants and served inline.

Self-restart mechanism: A background thread checks the server file’s mtime every few seconds. When a change is detected, it calls os.execv(sys.executable, [sys.executable] + sys.argv), replacing the process with a fresh copy that picks up the new code. The ~/.amux/server.env file loads environment variables at startup via os.environ.setdefault, so they survive across restarts.

Deployment comparison

Contributing

Because amux is one file, contributions are a single PR touching amux-server.py. The pattern for a new REST endpoint:

elif self.path.startswith('/api/myendpoint'):
    data = json.loads(self.rfile.read(...))
    result = do_something(data)
    return self._json(result)

The file is organized into sections with clear comment headers: # ── SESSIONS ──, # ── BOARD ──, # ── EMAIL ──, etc. Most contributions are 10–50 lines. Verify syntax after editing: python3 -c "import ast; ast.parse(open('amux-server.py').read())"

Frequently asked questions

How many lines of code is amux?

amux is a single Python file (amux-server.py) containing the complete HTTP server, REST API, SSE backend, web dashboard (HTML/CSS/JS inline), SQLite layer, self-healing watchdog, and all business logic. The entire AI agent control plane is in one file.

Does amux require any Python packages?

No. amux uses only Python’s standard library. The only system requirements are Python 3.8+ and tmux. There is nothing to pip install.

How does amux auto-restart when the file changes?

The server uses os.execv to replace itself with a fresh process when it detects its own file has changed (mtime check every few seconds). This means touch amux-server.py or any file edit triggers a hot restart automatically — no service restart command needed.

Is it hard to contribute to a large single file?

The file is organized into sections with clear comment headers. Adding a new REST endpoint is a single if self.path.startswith(...) block. Most contributions are 10–50 lines. The entire codebase is visible at once — no jumping between modules.

Is this architecture production-grade?

For a developer tool running on a single machine managing a local agent fleet — yes. amux is designed to be reliable, fast to deploy, and easy to understand. It is not designed to serve thousands of concurrent requests, but it comfortably handles dozens of agent sessions and multiple browser tabs simultaneously.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822

Related guides

• Getting started with amux
• Self-healing watchdog — how amux auto-restarts crashed agents
• Web dashboard — the amux live agent monitoring UI
• amux REST API reference