Nasiko-Labs/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

Table of Contents

• What is Nasiko?
• Features
• Architecture
• Requirements
• Quick Start — Docker only (no Rust needed)
• Setup guides by operating system
• CLI — install & use
• Coding Agents & LLM Router
• Environment Variables
• Project Structure
• Troubleshooting
• Project Activity
• Documentation & Links
• Support
• Contributing
• License

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 — 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:

• OPENAI_API_KEY — your OpenAI key (used by the routing engine and injected into agents)
• ADMIN_PASSWORD — password for the bootstrap admin account

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.

• First build takes a few minutes (compiles Rust inside Docker) — subsequent builds are fast.
• Open http://localhost:8080 for the dashboard and log in with ADMIN_USERNAME / ADMIN_PASSWORD

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

   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
   

   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
   

   sudo usermod -aG docker "$USER"
   newgrp docker
   

   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
   

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

# 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"

# 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

# 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 | 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 | 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 -f | Stream (and follow) agent logs | | nasiko stop / start / restart / scale | Agent lifecycle | | nasiko rm --name | Terminate + deregister an agent (positional id only accepts a UUID) | | nasiko chat | 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.

Coding Agents & LLM Router

Nasiko can manage the coding-agent CLIs already installed on your machine — recording what they do, routing their LLM calls, or both. The two are independent opt-ins.

Supported: Claude Code, Codex, Cursor CLI, OpenCode.

Session reporting

nasiko agents discover           # DETECTED / CONNECTED / VERSION / CONFIG per agent
nasiko agents install     # install session-reporting hooks
nasiko agents uninstall 
nasiko agents sync               # flush queued session-turn events to the control plane

Auto-install also fires on nasiko connect / nasiko use / nasiko auth login, but only for agents with no existing install record — it never silently rebinds an already-installed agent to a new cluster. Rebind explicitly with nasiko agents install .

Each agent gets a Stop/session-idle hook. Completed turns are queued locally under ~/.nasiko/integrations/queue/ and delivered to POST /telemetry/coding-agent/events/batch, so a control plane that is briefly unreachable costs you nothing. Permanently-failed deliveries (after a cluster is deleted or renamed, say) land in ~/.nasiko/integrations/rejected/ and are safe to delete.

Ingested turns show up as chat sessions right away (nasiko sessions, nasiko history ). Traces, token counts, and cost additionally require CODING_AGENT_OTLP_ENDPOINT — see below.

Routing LLM calls through Nasiko

nasiko connect claude --config 
nasiko connect codex --config 
nasiko connect opencode --config 
nasiko disconnect         # reverse the settings/plugin changes
nasiko status             # show current binding

connect claude / connect codex point the agent's apiKeyHelper and *_BASE_URL at Nasiko, so each request mints a short-lived JWT via POST /api/agents/{id}/llm-token. Claude Code sends that credential in the x-api-key header rather than Authorization; the router accepts both.

connect opencode instead installs a JS plugin (~/.config/opencode/plugins/nasiko-llm-router.js) registering a nasiko provider and making nasiko/router the default model for new OpenCode sessions only — OpenCode fixes a session's model at creation time in its own database, so resuming an existing session will not route it. Start a new one, or pick "Nasiko Router" explicitly.

Inbound wire protocol and outbound provider are fully decoupled: `nasiko connect claude --config my-openai-config` routes Claude Code's Anthropic-format traffic to OpenAI.

~/.claude/settings.json and OpenCode's config are per-user, global files. Connecting an agent

affects every Claude Code / OpenCode process on the machine, not just the current project.

LLM config management

nasiko llm-config create --name  --provider  --model 
nasiko llm-config list
nasiko llm-config update  [--provider ...] [--model ...]
nasiko llm-config set-default 
nasiko llm-config attach  --agent      # attach to a deployed agent
nasiko llm-config detach --agent 
nasiko llm-config get                        # resolved routing config for an agent
nasiko llm-config providers                         # valid provider/model values + pricing

A config's model field is required for routing to work — list shows provider/? when it is unset.

Server configuration

| Variable | Purpose | |---|---| | AGENT_JWT_SECRET | Signs the short-lived per-request router JWTs. Empty ⇒ every router request is rejected with 401 (fail-closed). | | CODING_AGENT_OTLP_ENDPOINT | OTLP/HTTP JSON base endpoint for the telemetry outbox worker (the server appends /v1/traces and /v1/logs). Unset leaves ingested receipts pending and starts no worker, so coding-agent traces never reach Tempo/Loki. |

Environment Variables

Everything is env-driven through a single Config struct (config/src/lib.rs); required keys fail fast at startup. When running via docker compose, the infrastructure URLs (DATABASE_URL, REDIS_URL, S3_ENDPOINT, OTel/Tempo/Loki, agent network) are set automatically