mainplane

module

v0.5.2-rc.4 Latest Latest Go to latest Published: Oct 9, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mainplane-ai/mainplane

Links

Open Source Insights

README ¶

Mainplane, with the biplane flying over the clouds

Mainplane is an open-source agent harness built for performance at scale.

> Run hundreds of durable agents with computer/browser use
> Connect your own devices, your agents can drive them remotely
> Secrets and controls stay safely isolated
> Chat from anywhere, everything syncs

Quickstart

1. Install mainplane-server on any machine.

# Linux, macOS
curl -fsSL https://mainplane.ai/install | sh -s -- server

# Windows
& ([scriptblock]::Create((irm https://mainplane.ai/install.ps1))) server

It prints commands with your network name and device code, and an API key (mp_key_...), save these.

2. Optional: connect more machines. Your agents can use them.

# Linux, macOS - use network name and device code from step 1
curl -fsSL https://mainplane.ai/install | sh -s -- your-network XXXX-XXXX

# Windows - use network name and device code from step 1
& ([scriptblock]::Create((irm https://mainplane.ai/install.ps1))) your-network XXXX-XXXX

3. Log in from anywhere and start a session. A logged-in machine can message agents.

# Linux, macOS - use api key from step 1
curl -fsSL https://mainplane.ai/install | sh -s -- mp_key_...

# Windows - use api key from step 1
& ([scriptblock]::Create((irm https://mainplane.ai/install.ps1))) mp_key_...

Add an LLM key (openai, anthropic or google), then start a session on admin:

mainplane key openai sk-...
echo '{"model":"openai/gpt-6.1-sol","context_limit":200000,"workers":[{"name":"admin"}],"params":{"reasoning":{"effort":"medium","summary":"auto"}}}' | mainplane new
mainplane chat

FAQ

Do I need more than one device?

No. Everything can run on one device.

Does mainplane-server need Linux?

No. mainplane-server runs on macOS, Windows and Linux.

Do you take contributions?

We welcome feedback as GitHub issues. Pull requests are open to collaborators only.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mainplane command mainplane is the device binary: the worker, and the plainest connector.	mainplane is the device binary: the worker, and the plainest connector.
mainplane-server command mainplane-server is the server binary: the harness, and the credentials that reach it.	mainplane-server is the server binary: the harness, and the credentials that reach it.
e2e e2e is the release gate.	e2e is the release gate.
pkg
auth Package auth is the two credentials a harness checks.	Package auth is the two credentials a harness checks.
coordinator Package coordinator is the harness's side of the Tailscale coordination protocol: ts2021, Noise inside a WebSocket at /ts2021, the one upgrade the tunnel passes.	Package coordinator is the harness's side of the Tailscale coordination protocol: ts2021, Noise inside a WebSocket at /ts2021, the one upgrade the tunnel passes.
elevate Package elevate makes a command that needs root or admin work without the user typing sudo or opening an elevated shell first.	Package elevate makes a command that needs root or admin work without the user typing sudo or opening an elevated shell first.
harness Package harness steps a session: load the file, build the context, call the provider, append what comes back, execute the calls, repeat until the model stops calling tools.	Package harness steps a session: load the file, build the context, call the provider, append what comes back, execute the calls, repeat until the model stops calling tools.
mesh Package mesh puts this worker on its project's Mainplane Network: tailscale's engine (wireguard-go, magicsock, the DERP client) on a TUN of its own, with its own state, UDP port, and router, so it runs beside a user's own Tailscale.	Package mesh puts this worker on its project's Mainplane Network: tailscale's engine (wireguard-go, magicsock, the DERP client) on a TUN of its own, with its own state, UDP port, and router, so it runs beside a user's own Tailscale.
pointer Package pointer is how a worker or connector finds its harness from the key its token carries, or the network name a person types.	Package pointer is how a worker or connector finds its harness from the key its token carries, or the network name a person types.
provider Package provider turns a context of state file records into one LLM request and the streamed response back into records.	Package provider turns a context of state file records into one LLM request and the streamed response back into records.
relay Package relay is the DERP relay on the harness's one port.	Package relay is the DERP relay on the harness's one port.
release Package release is how a binary becomes another release's.	Package release is how a binary becomes another release's.
server Package server assembles the roles a mainplane-server process runs.	Package server assembles the roles a mainplane-server process runs.
statefile Package statefile reads and writes the append-only files that hold an agent session.	Package statefile reads and writes the append-only files that hold an agent session.
tunnel Package tunnel is a self-hosted harness's front door: a cloudflared child that carries one public HTTPS URL to the harness's loopback port, so the harness opens no inbound port and needs no domain.	Package tunnel is a self-hosted harness's front door: a cloudflared child that carries one public HTTPS URL to the harness's loopback port, so the harness opens no inbound port and needs no domain.
version Package version is the release a binary was built from.	Package version is the release a binary was built from.
worker Package worker is the side of a worker that runs code and moves files for a harness over one connection.	Package worker is the side of a worker that runs code and moves files for a harness over one connection.