nasiko README

The project's README from github.com/Nasiko-Labs/nasiko. As one markdown file: README.md.

Nasiko

Deploy, route, secure, and observe any A2A-speaking agent with a single command — no gateway, no sidecar, no glue code.

📚 Documentation  •  💬 Discord  •  🐛 Report a bug

GitHub stars GitHub forks Latest release License: Apache-2.0

Built with Rust Open issues Pull requests CI PRs Welcome

Table of Contents

What is Nasiko?

Running more than a couple of agents quickly turns into an operations problem: who calls whom, which key does each agent hold, what did that call cost, why did it fail?

Nasiko is a single control-plane process that sits in front of every agent and answers all of that. It terminates TLS, authenticates every request, and proxies all agent-to-agent traffic itself, so agents are never publicly reachable — every hop is a checkpoint for rate limits, ACLs, and tracing.

Different language, same A2A protocol — bring your own agents in Python, Rust, Go, or TypeScript. No proprietary agent format, no lock-in.

Nasiko Dashboard
Nasiko Dashboard — deploy agents, route traffic, manage tools, and watch traces.

Features

Feature What it does
Deploy anything that speaks A2A nasiko deploy builds, pushes to the embedded registry, and runs it. No external registry required.
Intelligent routing engine 3-stage pipeline — shortlist by embedding similarity, rerank on conversation context, then LLM final pick. Callers don't need to know your fleet.
Single ingress, always proxied Agents are never publicly reachable; every agent-to-agent call is proxied through the server.
MCP Gateway One permanent URL gives every agent a merged, permission-filtered view of Composio toolkits and custom MCP servers — without the agent holding the credentials.
LLM Router Agents get an OPENAI_BASE_URL + a short-lived identity token instead of a real key. The router resolves provider/model/key server-side. No agent or log ever sees a real API key.
Full observability Every dispatch and proxy hop emits a real OTel span -> one end-to-end trace. Token usage & cost are auto-collected from gen_ai.* attributes.
Flow guards Redis-backed cascade limits (depth, fan-out, token budget, timeout, cycle detection) stop runaway agent loops.
Encrypted secrets Per-agent secrets are AES-256-GCM encrypted at rest, injected only at deploy time.
Access control User to-agent ownership/grants and an agent-to-agent allowlist gate every proxy call, independently.
Embedded OCI registry Self-hosted, S3-backed registry with layer dedup — nasiko push / nasiko deploy need nothing external.
CLI-first, no lock-in nasiko new, run, chat, deploy. Bring your own LLM provider.

Architecture

Nasiko is a single process — there is no separate gateway. Every inter-agent call is proxied back through the server, the single chokepoint where flow limits, ACLs, and observability are enforced. Durable state lives in Postgres, Redis, and S3 (RustFS), with optional observability via Tempo / Loki / the OTel Collector.

flowchart LR
    subgraph Clients["Clients"]
        UI["Web Dashboard (embedded)"]
        CLI["nasiko CLI"]
    end

    subgraph CP["nasiko-server (single control-plane process)"]
        direction TB
        API["REST API (agents, builds, uploads)"]
        AUTH["Auth (session JWT, TLS, rate-limit, ACLs)"]
        OIDC["OIDC client (SSO)"]
        ROUTE["Routing engine (shortlist, rerank, select)"]
        PROXY["A2A Proxy (generic agent reverse-proxy)"]
        MCP["MCP Gateway (tools/list, tools/call, OAuth)"]
        LLM["LLM Router (OpenAI-compatible egress)"]
        OCI["Embedded OCI registry (/v2/*)"]
        FLOW["Flow guards (depth, fan-out, token budget, cycles)"]
        SECRETS["Secrets engine (AES-256-GCM)"]
        GITHUB["GitHub App integration"]
    end

    subgraph Infra["Backing services (Docker)"]
        PG[(Postgres)]
        RD[(Redis)]
        S3[(RustFS S3)]
        OTEL["OTel Collector"]
        TEMPO["Tempo"]
        LOKI["Loki"]
    end

    subgraph Agents["Agent containers (Docker runtime)"]
        A1["Agent A"]
        A2["Agent B"]
        A3["Agent C"]
    end

    UI --> API
    CLI --> API
    CLI -. "push / pull images" .-> OCI

    API --> ROUTE
    API --> GITHUB
    ROUTE --> FLOW
    OIDC --> AUTH
    SECRETS --> API

    AUTH -. gates .-> API
    AUTH -. gates .-> MCP
    AUTH -. gates .-> OCI
    AUTH -. gates .-> PROXY

    ROUTE -- "selected agent, direct call" --> Agents
    PROXY -. "proxied A2A calls (bypasses routing)" .-> A1
    PROXY -. "proxied A2A calls (bypasses routing)" .-> A2
    PROXY -. "proxied A2A calls (bypasses routing)" .-> A3
    OCI -- "image pull at deploy" --> Agents
    Agents -- "OPENAI_BASE_URL" --> LLM
    Agents -- "tools/list, tools/call" --> MCP

    OCI --> S3
    FLOW --> RD
    SECRETS --> PG
    AUTH --> PG
    CP --> OTEL --> TEMPO
    OTEL --> LOKI

Every request to an agent is either dispatched by the routing engine or proxied generically — both paths originate inside the server. Agents never receive a direct, public request, and both call back out into the LLM Router and MCP Gateway rather than holding real API keys or tool credentials.

Requirements

Component Minimum version Why
Docker Engine + Compose V2 Compose V2 plugin (the docker compose command — not the legacy standalone docker-compose v1 binary) docker-compose.yml uses the extended depends_on: condition: service_healthy syntax; the Docker-only path needs nothing else.
Rust 1.85+ (stable) The workspace targets edition = "2024" (see Cargo.toml), stabilized in Rust 1.85 — only needed for the CLI / Path B developer setup, not the Docker-only path.
A2A protocol Spec v1.0 exactly (latest upstream release: v1.0.1, Linux Foundation) Nasiko requires and hardcodes the A2A-Version: 1.0 header on every request; agents on older/pre-1.0 spec versions (e.g. 0.2.x, 0.3.0) are rejected with -32009 VersionNotSupported (see docs/A2A_PROTOCOL.md). Any agent speaking v1.0 works, regardless of its implementation language.

Quick Start — Docker only (no Rust needed)

The fastest way to run Nasiko requires only Docker (with Compose). The server builds itself from source inside Docker.

1. Clone and configure

git clone https://github.com/Nasiko-Labs/nasiko.git
cd nasiko
cp .env.example .env

Edit .env and set at minimum:

2. Start the platform

docker compose up -d

This builds the server image and starts the full stack: Postgres · Redis · RustFS (S3) · OTel Collector · Tempo · Loki · nasiko-server.

docker compose logs -f server   # follow server logs
docker compose down             # stop everything
docker compose up -d --build    # rebuild after pulling new changes

No Docker? Use the Developer / Rust setup below.

Setup guides by operating system

You have two supported paths:

Path Requires Best for
A. Docker-only Docker only Anyone who just wants to run the platform
B. Source / Rust Rust + just Contributors, developers, hot-reload

Path A — Docker-only

Windows
  1. Install Docker Desktop -> https://www.docker.com/products/docker-desktop/
  2. Open Docker Desktop and wait until the engine is running.
  3. In a terminal (PowerShell or Git Bash):
    git clone https://github.com/Nasiko-Labs/nasiko.git
cd nasiko
Copy-Item .env.example .env
# edit .env -> set OPENAI_API_KEY and ADMIN_PASSWORD
docker compose up -d
  4. Open http://localhost:8080 and log in.

Windows troubleshooting: see the Troubleshooting section (port conflicts, line endings, encryption key, WSL, Docker Desktop).

macOS
  1. Install Docker Desktop for Mac -> https://www.docker.com/products/docker-desktop/
  2. Open Docker Desktop until the engine is running.
  3. In Terminal:
    git clone https://github.com/Nasiko-Labs/nasiko.git
cd nasiko
cp .env.example .env
# edit .env -> set OPENAI_API_KEY and ADMIN_PASSWORD
docker compose up -d
  4. Open http://localhost:8080 and log in.

host.docker.internal resolves out of the box on Docker Desktop (macOS + Windows), so agents can reach the MCP gateway without extra setup.

Linux
  1. Install Docker engine + Compose plugin -> https://docs.docker.com/engine/install/
  2. Add your user to the docker group and re-login:
    sudo usermod -aG docker "$USER"
newgrp docker
  3. In a terminal:
    git clone https://github.com/Nasiko-Labs/nasiko.git
cd nasiko
cp .env.example .env
# edit .env -> set OPENAI_API_KEY and ADMIN_PASSWORD
docker compose up -d
  4. Open http://localhost:8080 and log in.

Linux note: native Docker does not provide host.docker.internal automatically. If agents report [Errno -2] Name or service not known, run Docker with --add-host host.docker.internal:host-gateway or set MCP_GATEWAY_PUBLIC_URL to the bridge IP (see Troubleshooting).

Toolchain setup — Rust, just, etc. (for the CLI / Path B)

Windows 
# 1. Rust (installs rustup + stable toolchain)
winget install --id Rustlang.Rustup -e
# (reopen your terminal, then verify)
rustc --version; cargo --version

# 2. `just` command runner + cargo-watch (after Rust is installed)
cargo install just cargo-watch

# 3. If you plan to build native Windows binaries, also install the C++ linkers:
winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Building the CLI does not require the C++ Build Tools — it uses a pure-Rust toolchain. The C++ linkers are only needed if native crates (e.g. ring) fail to link on the MSVC toolchain.

macOS 
# 1. Xcode Command Line Tools (provides the C toolchain/linker)
xcode-select --install

# 2. Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 3. `just` + cargo-watch
cargo install just cargo-watch
Linux (Debian/Ubuntu) 
# 1. Build dependencies (cc, OpenSSL)
sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev

# 2. Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 3. `just` + cargo-watch
cargo install just cargo-watch

# 4. Docker engine + compose (if not using Docker Desktop)
#    See https://docs.docker.com/engine/install/ubuntu/

After setup, verify everything:

rustc --version   && cargo --version
just --version
docker --version  && docker compose version

Path B — Developer / Rust setup

Requires Rust (rustup), just (cargo install just), and Docker.

# 1. Start infrastructure only (Postgres, Redis, RustFS, OTel stack)
just infra

# 2. Configure the server env
cp server/.env.example server/.env
# edit server/.env -> set OPENAI_API_KEY at minimum

# 3. Run the server natively (hot-reload)
just dev
# ...or without hot-reload:
just run

The server runs on http://localhost:8080. just dev auto-rebuilds on changes (needs cargo-watch).

Useful dev commands:

just check        # cargo check --workspace
just clippy       # lint (zero-warnings policy)
just test-unit    # fast hermetic unit tests (no infra needed)
just test         # unit + integration tests (needs: just infra)

Building from source:

cargo build --release -p nasiko          # CLI binary
cargo build --release -p nasiko-server   # Server binary

CLI — install & use

The CLI needs Rust to build from source (it is a separate cli/ crate). You also need Docker to build/deploy agent images.

Install the CLI

# from the repo root
cargo install --path cli/
# ...or build a standalone binary
cargo build --release -p nasiko

Add it to your PATH if it is not already (Cargo's bin dir: ~/.cargo/bin).

Deploy your first agent

nasiko connect http://localhost:8080
nasiko auth login                          # log in with ADMIN_USERNAME / ADMIN_PASSWORD
nasiko new openai my-agent && cd my-agent  # scaffold from a template
nasiko deploy .                            # build, push, and deploy
nasiko chat "Hello there"                  # talk to your agent (message must contain a space,
                                            # or use --agent: nasiko chat --agent my-agent "Hello")

You can also deploy agents directly from the dashboard UI — upload source, import from GitHub, or pull from the artifact registry.

Handy CLI commands

Command Description
nasiko connect <url> Register a control plane and switch to it
nasiko auth login Authenticate with the active cluster
nasiko new [template] [name] Scaffold a new agent project
nasiko build / nasiko run Build the agent image / build + run it locally
nasiko push / nasiko deploy <image> Push image / build-push-deploy to the cluster
nasiko upload [source] Upload source; the server builds it (no local Docker)
nasiko ps List running agents
nasiko logs <agent> -f Stream (and follow) agent logs
nasiko stop / start / restart / scale <n> Agent lifecycle
nasiko rm --name <agent> Terminate + deregister an agent (positional id only accepts a UUID)
nasiko chat <agent> Interactive or one-shot A2A chat
nasiko secrets set Configure encrypted per-agent secrets
nasiko mcp Manage MCP Gateway connectors and tool permissions
nasiko observe Observability: sessions, traces, spans, stats, FinOps
nasiko maf Multi-agent flow workflows (create/run/inspect)
nasiko registry Browse the artifact registry
nasiko github GitHub integration (status/repos/connect/disconnect/clone)

Run nasiko --help for the full, workflow-ordered command list.

Environment Variables

Everything is env-driven through a single Config struct (config/src/lib.rs); required keys fail fast at startup. When running via `docke

nasiko (Nasiko-Labs/nasiko)

oci
Searching Database…

9.5K ·GitHub
Nasiko
What is this?Nasiko is a single control-plane server that deploys, routes, secures, and observes AI agents built on the A2A protocol, acting as the one checkpoint every agent-to-agent call passes through.
Is this a gateway I add in front of my agents, or something I run instead of one?It replaces a gateway/sidecar setup entirely: Nasiko is one server process that proxies every agent-to-agent call itself, so there's no separate gateway container or glue code to maintain.
How do I get it running?Clone the repo, edit .env to set OPENAI_API_KEY and ADMIN_PASSWORD, then run the Docker Compose stack; it builds the server image and starts Postgres, Redis, RustFS (S3), the OTel Collector, Tempo, Loki and nasiko-server, after which you log into the dashboard.
What do I need installed before I can run it?Just Docker Engine with the Compose V2 plugin for the quick-start path. Building the CLI or running from source instead needs Rust 1.85+ (edition 2024) plus the 'just' command runner.
Will any A2A agent work with it out of the box?No — Nasiko hardcodes the A2A-Version: 1.0 header on every request, so agents built against older spec drafts like 0.2.x or 0.3.0 get rejected with a VersionNotSupported error, regardless of the language they're written in.
How does the MCP Gateway keep tool credentials safe?It gives every agent one permanent URL exposing a merged, permission-filtered view of Composio toolkits and custom MCP servers, without the agent ever holding the underlying credentials itself.
How does the LLM Router avoid exposing real API keys to agents?Agents are given an OPENAI_BASE_URL plus a short-lived identity token instead of a real key; the router resolves the actual provider, model, and key server-side, so no agent or log ever sees the real credential.
What stops one misbehaving agent from spawning a runaway loop?Redis-backed flow guards enforce cascade limits on call depth, fan-out, token budget, timeout, and cycle detection to stop runaway multi-agent chains.
Can agents be written in different programming languages?Yes — any agent that speaks the A2A protocol v1.0 works, so you can mix agents written in Python, Rust, Go, or TypeScript in the same fleet.
What are similar projects?gateway, go-micro, buzz, bifrost, litellm, production-agentic-rag-course, PilotDeck, trueforge
Which topics is it in?a2a-protocol, mcp-gateway, oci, agent-security, model-router, opentelemetry, api-gateway, llms, s3, redis, agent-orchestration, observability
Creator
Nasiko-Labs
Size
28.1 MB
Stars
9.5K
Updated
CommitOct 16Releasev1.0.0Feb 12
Age
8mo
Commits · 90 Days