# Integrations

Nucleus is the **permission algebra and enforcement kernel** — it doesn't own the sandbox, the network mesh, or the orchestrator. It integrates with each through clean port/adapter boundaries.

```
                        +-----------------------------------+
                        |        Your Orchestrator           |
                        |  (workstream, langchain, custom)   |
                        +----------------+------------------+
                                         | PodSpec + credentials.env
                                         v
+------------------+   +---------------------------+   +----------------------+
|   Network Mesh   |   |        NUCLEUS             |   |   Sandbox Runtime    |
|                  |   |                             |   |                      |
|  Tailscale       |<--+  portcullis (lattice)       +-->|  k8s Agent Sandbox   |
|  - WireGuard     |   |  nucleus-audit (scan)       |   |  - gVisor            |
|  - node identity |   |  tool-proxy (enforce)       |   |  - Kata Containers   |
|  - ACL tags      |   |  nucleus-identity (SPIFFE)  |   |  - SandboxWarmPool   |
|                  |   |  ck-kernel (constitutional)  |   |                      |
|  or: Cilium,     |   |                             |   |  or: Firecracker,    |
|  Calico, plain   |   |     Ports (in):             |   |  Docker+gVisor,      |
|  WireGuard       |   |       gRPC PodSpec submit   |   |  Colima              |
|                  |   |       MCP tool calls        |   |                      |
|                  |   |     Ports (out):             |   +----------------------+
|                  |   |       sandbox lifecycle      |
|                  |   |       network policy         |   +----------------------+
|                  |   |       audit log sink         |   |   Execution Policy   |
|                  |   |       identity attestation   |   |                      |
+------------------+   +---------------------------+   |  agentsh             |
                                                         |  - syscall intercept |
                                                         |  - file/net/proc     |
                                                         |  - approval gates    |
                                                         |  - YAML policies     |
                                                         |                      |
                                                         |  or: seccomp,        |
                                                         |  AppArmor, SELinux   |
                                                         +----------------------+
```

## Kubernetes Agent Sandbox

[`kubernetes-sigs/agent-sandbox`](https://github.com/kubernetes-sigs/agent-sandbox) is the Kubernetes SIG Apps standard for running AI agents in isolated pods. It provides the **sandbox runtime** — Nucleus provides the **permission algebra** that decides what the sandbox should allow.

**Integration point:** Nucleus generates the pod security context, network policy, and resource limits from a `PodSpec` that Agent Sandbox enforces via gVisor or Kata Containers.

```yaml
# Nucleus PodSpec -> Agent Sandbox CRD
apiVersion: agent-sandbox.sigs.k8s.io/v1alpha1
kind: AgentSandbox
spec:
  isolation: gVisor                    # or kata
  warmPool: pre-booted                 # sub-second cold start
  # Generated by nucleus from permission profile
  securityContext:
    capabilities:
      drop: [ALL]
    readOnlyRootFilesystem: true
  networkPolicy:
    egress:                            # from portcullis network_allow
      - to: [{ipBlock: {cidr: "140.82.112.0/20"}}]  # github.com
      - to: [{ipBlock: {cidr: "108.138.0.0/15"}}]   # crates.io
```

| Concern | Nucleus | Agent Sandbox |
|---------|---------|---------------|
| What the agent may do | Permission lattice decides | -- |
| How the sandbox is configured | Generates PodSpec | Enforces via gVisor/Kata |
| Network egress rules | Computes from `network_allow` | Applies as NetworkPolicy |
| Warm pool management | -- | SandboxWarmPool CRD |
| Uninhabitable state detection | Static + runtime | -- |
| Runtime syscall filtering | -- | gVisor kernel intercept |

## agentsh

[agentsh](https://www.agentsh.org/) provides **execution-layer policy enforcement** — intercepting file, network, and process operations at the syscall level. Where Nucleus decides permissions algebraically, agentsh enforces them at the OS boundary.

**Integration point:** Nucleus computes the effective permission set; agentsh enforces it as a syscall-level policy inside the sandbox.

```
Nucleus (what)                    agentsh (how)
+--------------------+            +---------------------+
| portcullis says:   |            | Policy enforcement:  |
|   read_files: Yes  |  ------>  |   file_read: allow   |
|   web_fetch: No    |  generate |   net_connect: deny   |
|   git_push: Ask    |  policy   |   proc_exec(git      |
|   run_bash: Scoped |            |     push): approve   |
+--------------------+            +---------------------+
```

**Layered defense:**

| Layer | Tool | What It Catches |
|-------|------|-----------------|
| 1. Static scan | `nucleus-audit` | Dangerous configs before deployment |
| 2. Lattice enforcement | `nucleus-tool-proxy` | Permission violations at the MCP/tool level |
| 3. Syscall enforcement | `agentsh` | `bash -c` indirection, symlink races, raw socket access |
| 4. VM isolation | Agent Sandbox / Firecracker | Kernel-level containment |

Layer 3 (agentsh) closes the `bash -c` bypass documented in [Known Gaps](../README.md#known-gaps) -- the command-level check Nucleus acknowledges as incomplete is enforced at the syscall level by agentsh.

## Tailscale + SPIFFE

[Tailscale](https://tailscale.com/) provides **encrypted mesh networking** with node-level identity. Nucleus's `nucleus-identity` crate provides **workload-level SPIFFE identity**. Together they cover both network transport and service authentication.

**Integration point:** Tailscale secures the network path between orchestrator and sandbox; SPIFFE SVIDs authenticate each agent workload within that mesh.

| Concern | Tailscale | SPIFFE (nucleus-identity) | Nucleus (portcullis) |
|---------|-----------|---------------------------|----------------------|
| Network encryption | WireGuard mesh | -- | -- |
| Node authentication | Machine keys + ACL tags | -- | -- |
| Workload authentication | -- | X.509 SVIDs, mTLS | -- |
| Service authorization | ACL policies (coarse) | -- | Capability lattice (fine) |
| Credential rotation | -- | Short-lived certs | Attenuation tokens |
| Audit | Connection logs | Identity attestation | Hash-chained action logs |

## Choosing Your Stack

| Deployment | Network | Sandbox | Policy | Identity |
|------------|---------|---------|--------|----------|
| **GitHub Actions** | GitHub runner network | `--local` (tool-proxy only) | Nucleus profiles | -- |
| **Single machine** | localhost / Tailscale | Docker + gVisor | Nucleus + agentsh | API keys |
| **k8s cluster** | Cilium / Calico / Tailscale | Agent Sandbox (gVisor/Kata) | Nucleus PodSpec | SPIFFE via SPIRE |
| **Multi-cloud** | Tailscale mesh | Agent Sandbox + Firecracker | Nucleus + attenuation tokens | SPIFFE + Tailscale ACLs |

Nucleus is the invariant across all four: the same permission lattice, the same scan, the same audit chain. The sandbox, network, and identity layers are pluggable adapters.
