agent-sidecar

Governed AI agents that run as a sidecar next to your service. The agent is a sidecar of the service, not a service of its own.

agent-sidecar brings AgentSecOps to LLM agents: identity, policy, budgets, guardrails and audit, owned by the platform instead of by each app. Agents run on Claude, or on a built-in mock model for offline tests.

Naming. agentsc is the short name of agent-sidecar, used in all code: the sidecar is agentscd, the CLI is agentsc, the CA is embassy, the runtime is agentsc-runtime, charters use apiVersion: agentsc.io/v1alpha1, and identities look like spiffe://agentsc/ns/<ns>/svc/<svc>.

What you get

• Any language, no SDK. Your app calls its sidecar on localhost: HTTP on 127.0.0.1:3500 or gRPC on 127.0.0.1:50001.
• One YAML charter per service. Every tool call an agent makes is checked against it, including calls to other services. Model calls are bounded by its budgets.
• mTLS identity per service. Each service gets spiffe://agentsc/ns/<ns>/svc/<svc>. The called sidecar decides which peers and which of their agents may call.
• Budgets and guardrails. Tokens per model call, invocations per minute, cost per day, steps per run, input size, regex deny rules on input and output, and PII redaction of the agent's output.
• Prompt injection contained by design. Taint rules track what each run has read. After untrusted text (a ticket, a web page), the run can't call a tool that writes. After sensitive data, it can't call out to the internet. How it works.
• Good working habits, on by default. Every agent plans before its first tool call and checks each result, asks its caller when a decision blocks the task, and answers tersely at a level that suits who reads it. A lesson an agent learns must cite the steps of the run it rests on. The charter turns each practice off or tunes it. How it works.
• One JSONL audit line per action. The sidecar writes them to stdout (or to a file with audit.sink: file). Read them with kubectl logs or agentsc logs.

flowchart LR
  subgraph podA["pod: orders"]
    A["app (any language)"] -->|"HTTP or gRPC on localhost"| S["sidecar (agentscd)"]
    S ---|"gRPC and the model gateway, on unix sockets"| R["runtime (agentsc-runtime)"]
  end
  S -->|"model API (the sidecar holds the key)"| C["Claude"]
  subgraph podB["pod: inventory"]
    P["peer sidecar"] --> B["peer app"]
  end
  S -->|"mTLS, port 50002"| P

Quick start

You need Rust (cargo), protoc, uv, Go, python3 and curl. No Kubernetes and no API key.

git clone https://github.com/f8fvwgzc/agent-sidecar.git && cd agent-sidecar
make local-demo

The script starts two example apps (Go orders, FastAPI inventory), each with its own sidecar and real mTLS certificates. It makes three calls (allowed across services, denied admin call, blocked by a guardrail) and prints the audit trail. Without ANTHROPIC_API_KEY the demo runs on a mock model (it sets AGENTSC_MOCK_FALLBACK=1; elsewhere a missing key refuses Claude agents). Export the key first to use Claude. The full v0.2 platform (control plane, console, managed sidecars) runs without Docker with CHECK_ONLY=0 make platform-demo; the console is then at http://localhost:38088. With Docker, make compose-up runs the same stack plus an OpenTelemetry collector and Jaeger (set AGENTSC_CONSOLE_PORT, AGENTSC_ORDERS_PORT or AGENTSC_JAEGER_PORT if 8080, 8081 or 16686 are taken). On minikube (also needs Docker, minikube and kubectl), run make minikube-up build deploy demo.

Call an agent

Your app sends one HTTP request to its own sidecar:

curl -s localhost:3500/v1/agents/stock-analyst/invoke \
  -H 'content-type: application/json' \
  -d '{"input": "How many WIDGET-1 are in stock?"}'

The JSON response has status, output, usage, steps, request_id and trace_id. An agent that needs a decision from you answers with status: ok and a questions list; you answer in the context of your next call. A denied invocation returns 403. A budget limit (calls per minute, cost per day, or agent-call depth) returns 429. An unknown agent returns 404. A runtime or model error returns 502. Hitting max_steps or max_tokens_per_call also returns 502, with status: error. A tool call that is denied inside the run does not fail the request. It appears in steps with decision: deny.

A charter

apiVersion: agentsc.io/v1alpha1
kind: Charter
service: { name: inventory, namespace: shop, app_port: 8000 }
agents:
  - name: stock-analyst
    type: agent
    model: claude-opus-5-5            # or "mock"
    system: You answer questions about stock levels.
    tools:
      - name: get_stock
        description: Get stock for one SKU.
        type: service
        service: inventory            # its own app
        method: GET
        path: /stock/{sku}
    budgets: { max_tokens_per_call: 1024, max_calls_per_minute: 60, max_cost_usd_per_day: 2.0, max_steps: 4 }
guardrails: { pii_redact: true }
authz:
  default: deny
  callers:  [{ identity: local, agents: ["*"] }]
  services: [{ name: self-stock, identity: local, agent: stock-analyst, service: inventory, allow: ["GET /stock/*"] }]
audit: { sink: stdout }

Check a charter with cargo run -p agentsc-cli -- charter validate <file>.

Docs

Page	What it covers
Architecture	How it works: components, ports, request flow, identity, authz order.
Getting started	Run it on your machine and on minikube, step by step.
Creating agents	Write a charter, define agents and tools, call them from your app.
Microservices	Adopt it across many services, for a startup or an enterprise.
Monolith and monorepo	One service with many agents, and a monorepo layout.
Operations	Audit logs, the CLI, troubleshooting, production checklist, limitations.
LLM connection	The platform's LLM_* contract, and the standalone model gateway (agentsc-gateway): wire formats, tenants, own keys, budgets.
Decision records	Why HTTP/3 for the console, the response caches, the SQLite store and the default-on agent practices are built the way they are.
CONTRACT.md	Full reference: wire protocol, charter, authz order, audit record.

Status

This is a v1alpha1 MVP. It is not production-ready. The most important limits:

• The two Kubernetes paths differ. With the Helm chart, embassy's mutating webhook injects the sidecars into pods labelled agentsc.io/inject: "true", and each pod gets its own certificate from embassy (24 hours by default, renewed without a restart). The kustomize demo in deploy/ writes the agentscd container into each Deployment by hand and uses per-service certificates from a bootstrap Job, with no rotation and one CA per namespace.
• Budgets live in memory in each sidecar replica. They are not shared across replicas, and they reset when the sidecar restarts.
• The runtime's model calls go through the sidecar's model gateway, which holds the provider key and enforces the budgets. pii_redact only rewrites the agent's final output and the audit records. It does not change prompts sent to the model.
• In the kustomize demo the runtime is a child process in the sidecar's container. The Helm chart runs it as its own container, without the key.
• Charter changes apply without a restart (the sidecar reloads its file; embassy pushes to managed sidecars), except the restart-only fields such as service.name and the ports.
• No NetworkPolicy is shipped for your pods. The chart's NetworkPolicy covers embassy only.

More detail is in docs/operations.md and CONTRACT.md §11.

Contributing and security

See CONTRIBUTING.md to build, test and send a change. Report security problems privately, as SECURITY.md explains.

License

MIT