Running the platform

Where do nodes live?

Nodes can run on literally any device that can run C code and connect to a network. This includes:

Hardware collageleg-hardware

Four devices arranged in a 2x2 grid, each with a small 'legion node' badge: (top-left) a smartphone, (top-right) a laptop, (bottom-left) a Raspberry Pi, (bottom-right) a small server tower or cloud server icon. Each device has a small Legion logo or badge in the corner. Clean product photography style, white/light gray background, consistent lighting. Think 'hardware showcase for a tech product'.

• Smartphones — the default starting point. Always on, always connected, with cameras and microphones.
• Laptops and desktops — powerful enough for most tasks, great as interface devices.
• Raspberry Pi — low power, always-on, perfect for home servers.
• Rented cloud servers — powerful, always-on, accessible from anywhere.
• Embedded devices — ESP32 microcontrollers with small screens, for minimal interfaces.
• Docker containers — ephemeral workers that spin up, do a task, and shut down.

Every device type runs the same core Legion software. The difference is which modules (capabilities) it loads.

Installation formats

Legion software is distributed in several ways:

Notice that an interface device (your smartphone or laptop) doesn't need the AI modules. It only needs the core package. The AI work happens on the orchestrator node.

Three ways to get hardware

Option 1: Your own devices

You already have some of these. Your smartphone, your laptop, maybe a Raspberry Pi gathering dust in a drawer. These are your personal nodes — zero cost, full control, zero dependencies.

To start:

1. Install the legion package.
2. Run legion-node-runner to start your node.
3. Pair it with your smartphone (your main device).
4. Done. You're in the network.

Option 2: Rent a slot

If you need more power than your personal devices can provide, you can rent compute from a provider. Providers are independent operators who rent out hardware slots.

The process:

1. Browse the provider directory on legios.cloud.
2. Pick a package (e.g., “GPU Worker — AI language model + speech”).
3. Pay the provider directly (Legion doesn't handle payments).
4. Scan a QR code with your smartphone to approve the connection.
5. The rented server starts and joins your group automatically.

Flow illustrationleg-rent-slot

A simple four-step horizontal flow. Step 1: 'Browse packages' (shopping icon). Step 2: 'Pay provider' (credit card icon). Step 3: 'Scan QR with smartphone' (QR code icon). Step 4: 'Server joins your group' (server icon with a green check). Arrows between steps. Clean, flat design, white background. Think 'e-commerce checkout flow'.

Key security points:

• The provider never sees your keys or your data.
• The provider just rents you compute. Your identity and data stay on your devices.
• You can revoke the rented server at any time from your smartphone.

Option 3: Self-hosted bridge

If you want to enable internet access for your home network (so you can reach your servers from a hotel, a cafe, etc.), you need a bridge node.

You can use a public bridge (listed on legios.cloud), or run your own:

1. Install the bridge daemon on a publicly accessible server (VPS, cloud instance, etc.).
2. Your home nodes register with the bridge on startup.
3. When you connect from anywhere, the bridge routes your connection to your home nodes.

This is like having your own private VPN server, but Legion handles the routing automatically. You don't configure IP addresses or firewall rules.

Deployment scenarios

Here are the most common setups:

The “Just My Phone” setup

Minimal architectureleg-phone-only

A single smartphone centered on a white background. Small labels around it: 'audio.in', 'audio.out', 'display.gui', 'identity.auth'. No other devices. Minimal, clean, white background. Think 'single device illustration'.

Your smartphone is everything. It captures audio, displays output, handles authentication. If you have no other devices, this is your complete cohort. You can still use Legion — just with fewer capabilities.

The “Home Server” setup

Home network diagramleg-home-server

A simple house outline. Inside: a smartphone icon, a laptop icon, and a small server box labeled 'Home Server (Raspberry Pi)'. Lines connect all three. Outside the house, a small cloud icon labeled 'Bridge / Internet'. Clean, minimal house diagram. White background, light blue lines. Think 'home network diagram for non-technical people'.

Your smartphone + a Raspberry Pi or mini PC running at home. The home server runs AI modules (orchestrator), and your smartphone is the interface. Simple, private, fast (local network).

The “Full Setup” setup

Complete architectureleg-full-setup

A complete Legion setup diagram: smartphone (left), home server / Raspberry Pi (center-left), bridge node cloud (center), rented cloud server with GPU (center-right), laptop/desktop (right). All connected in a mesh-like pattern. The bridge cloud acts as the internet connector. Each device has small capability labels. Clean, comprehensive but not cluttered. White background, soft color coding for different device types.

Phone + home server + rented cloud power + laptop. The home server handles everyday tasks. The rented server handles heavy computation. The bridge connects everything across the internet. Your laptop is a seamless extension of your smartphone.

Running as a service

On Linux, Legion runs as a system service (using systemd). This means:

• It starts automatically on boot.
• It restarts automatically if it crashes.
• Logs are managed by the system journal.

On Docker, it runs as a container:

FROM legios/node-runner:latest
COPY my-node.cert /etc/legion/node.cert

The container starts, loads its certificate, joins your cohort, and runs. If the container is replaced (e.g., after an update), the same identity is preserved because the node key is stored as a Docker secret.

What providers need to do

If you want to become a Legion provider (renting out your hardware):

1. Run a public bridge node (port 7575 accessible).
2. Implement the Legion Installer API (the protocol for onboarding new users).
3. Run the signed Legion node runner binary.
4. Provide an uptime guarantee (recommended: 99.9%).
5. Register on the legios.cloud provider directory (optional — you can also be added manually by users).

Anyone can be a provider. Legion doesn't approve or vet providers — the marketplace is federated, meaning trust comes from user reviews and reputation, not from a central authority.

Offline operation

Legion works fully offline. If your devices are all on the same local network with no internet connection:

• Discovery works via multicast (Layer 1).
• Communication works via direct LAN connections.
• Consensus works normally.
• Apps run from cache.
• AI models run locally on your orchestrator.

The bridge and seed nodes are only needed for remote access — reaching your home devices from outside your network.

Summary

The beauty of Legion is that you can start at any point and grow organically. There's no “right” setup. Your setup is whatever you need it to be.

What comes next

Now that you know how to deploy Legion, you might want to know: how do you build applications that run on it? Read Building apps to find out.