Installing the `myc-cli` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install mycelium-cli

It will make the myc-cli command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall mycelium-cli uninstalls.

Back to the crate overview.

Readme

🚀 Mycelium: The Ultimate API Gateway

Mycelium is an open and free API Gateway, designed to operate in modern, multi-tenant, and API-oriented environments. The project prioritizes architectural clarity, security, and extensibility, maintaining an explicit separation between technical concerns and organizational aspects of the project.

This repository documents the fundamentals of Mycelium, with special focus on its authorization model, which combines declarative controls at the gateway with contextual decisions close to the resource.

📖 Documentation

📚 View Complete Documentation →

Access the full documentation website with guides, tutorials, and API reference.

Quick Links

📚 Complete Documentation - Full documentation guide

🚀 Installation Guide - Get started with installation

⚡ Quick Start - Up and running in minutes

⚙️ Configuration - Configure Mycelium

🔐 Authorization Model - Deep dive into security

Overview

Mycelium acts as the entry layer for downstream services, being responsible for authentication, identity normalization, routing, and security policy enforcement. The gateway does not impose business logic, but provides authorization primitives that allow each service to evaluate permissions in an explicit, secure, and contextual manner.

The project is maintained as open source software, with its continuity based on governance, community collaboration, and ecosystem funding and acceleration initiatives — aspects that are independent of internal technical decisions.

Key Features

Modern and extensible API Gateway
Native support for multi-tenant environments
Authorization at multiple layers (gateway and downstream)
Identity context injection via Profile
Composable authorization primitives
Architecture compatible with market standards

Authorization Model

Mycelium's authorization model is one of its central pillars and is documented in detail in the file:

👉 Authorization

In summary:

The gateway applies declarative controls per route (coarse-grained)
Downstream services apply contextual authorizations (fine-grained)
The Profile acts as an active capability object, not just as an identity payload

Conceptual Structure

Client
  ↓
API Gateway (auth, routing, edge RBAC)
  ↓
Downstream Services (contextual FBAC)

This separation ensures low coupling, high expressiveness, and security decisions close to the resource.

Project Governance and Sustainability

Mycelium is an open and free project. Its maintenance and evolution are handled within the project's organizational scope, through:

Community collaboration
Institutional support
Funding and acceleration initiatives

These aspects do not influence or condition the technical authorization model, which remains neutral, explicit, and verifiable.

Getting Started

Prerequisites

Before installing Mycelium, ensure you have:

Rust (version 1.70 or higher) - Install Rust
Postgres (version 14 or higher) - Database for tenant and user management
Redis (version 6 or higher) - Caching layer
HashiCorp Vault (optional) - Recommended for production secret management
Docker (optional) - For containerized deployment

For detailed system dependencies and installation instructions, see the Installation Guide.

Installation

Install Mycelium using Cargo:

cargo install mycelium-api

Or using Docker:

docker pull sgelias/mycelium-api:latest

For complete installation instructions including database setup and Vault configuration, see the Installation Guide.

Quick Start

Initialize the database:

psql postgres://postgres:postgres@localhost:5432/postgres \
  -f postgres/sql/up.sql \
  -v db_password='your-password'

Configure Mycelium:

cp settings/config.example.toml settings/config.toml
# Edit config.toml with your settings

Start Mycelium:

SETTINGS_PATH=settings/config.toml myc-api

Verify it's running:
```
curl http://localhost:8080/health
```

For a complete quick start guide with minimal configuration, see Quick Start Guide.

Running Tests

Execute the test suite:

# Run all tests
cargo test

# Run with coverage
cargo tarpaulin --out Html

# Run specific tests
cargo test auth

For detailed testing instructions including integration tests and benchmarks, see Running Tests.

Documentation

📚 Online Documentation - Browse the complete documentation website

Alternatively, you can access documentation files directly in the docs/book/src/ directory:

Introduction - Overview and key features
Installation - Installation and setup
Quick Start - Get started quickly
Configuration - Configuration options
Deploy Locally - Local deployment with Docker
Authorization Model - Security and authorization
Downstream APIs - Configure routes and services
Running Tests - Testing guide

Project Status

Mycelium is under active development and open to contributions. Architectural discussions, improvement proposals, and conceptual reviews are welcome.

License

See the LICENSE file for details about the project's licensing.

Installing the myc-cli executable

Installing the `myc-cli` executable