Cloud Application API · Multi-Runtime Sidecar · Write Once, Run Anywhere

Capa Java · Capa Python · Capa Go

Capa Runtime is the sidecar implementation of the Capa (Cloud Application API) ecosystem. It provides extended capabilities that complement the Capa SDK, enabling advanced features like traffic interception, Actor model, and external system bindings.

Capa Runtime works alongside Capa SDK implementations to provide a complete Multi-Runtime solution for cloud-native applications.

capa/
├── cmd/                    # Entry points and CLI commands
├── pkg/                    # Core packages
│   ├── actor/             # Actor runtime implementation
│   ├── binding/           # External system bindings
│   ├── proxy/             # Traffic proxy and interception
│   ├── runtime/           # Core runtime logic
│   └── saas/              # SaaS integrations
├── docker/                 # Docker configurations
├── spec/                   # API specifications
└── utils/                  # Utility functions

Key Design Principles:

• Optional Sidecar: Capa Runtime is optional; SDK works independently
• Extended Capabilities: Provides APIs that SDK cannot support
• Dual Mode: Supports both sidecar and proxyless modes
• Negotiation: Application negotiates with proxy to determine mode

⚠️ Warning: This feature affects the main traffic path. Use with caution in production.

Actor model is not suitable for SDK integration and is provided via runtime.

Binding provides loosely-coupled interaction with external systems.

While Capa SDK provides rich functionality, some capabilities require sidecar architecture:

1. Actor Model: Requires persistent connections and scheduling
2. Traffic Interception: Needs network-level control (iptables)
3. Binding: Benefits from decoupled event processing

• Go 1.18 or higher
• Docker (optional, for containerized deployment)
• Kubernetes (optional, for orchestrated deployment)

# Clone the repository
git clone https://github.com/capa-cloud/capa.git
cd capa

# Build the runtime
go build -o capa-runtime ./cmd

# Run locally
./capa-runtime --config ./config.yaml

# Build Docker image
docker build -t capa-runtime:latest .

# Run container
docker run -d \
  --name capa-runtime \
  -p 3500:3500 \
  -v $(pwd)/config:/config \
  capa-runtime:latest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: capa-runtime
spec:
  replicas: 1
  selector:
    matchLabels:
      app: capa-runtime
  template:
    metadata:
      labels:
        app: capa-runtime
    spec:
      containers:
      - name: capa-runtime
        image: capa-runtime:latest
        ports:
        - containerPort: 3500
---
apiVersion: v1
kind: Service
metadata:
  name: capa-runtime
spec:
  selector:
    app: capa-runtime
  ports:
  - port: 3500
    targetPort: 3500

Capa Runtime minimizes external dependencies. Instead of a dedicated control plane, it uses:

• Configuration Component: For dynamic configuration delivery
• Service Discovery: Built-in or via external registry

mode: sidecar
sidecar:
  port: 3500
  grpcPort: 50001
  metricsPort: 9090
  traffic:
    interception:
      enabled: true
      port: 80

mode: proxyless
proxyless:
  directConnection: true
  sdkEndpoints:
    - localhost:3500

The application negotiates with the proxy to determine the operating mode:

// Application requests mode preference
mode := runtime.NegotiateMode(
    runtime.WithPreference(runtime.SDKMode),
    runtime.WithFallback(runtime.SidecarMode),
)

// Initialize actor runtime
actorRuntime := runtime.NewActorRuntime()

// Register actor type
actorRuntime.RegisterActor("MyActor", &MyActor{})

// Invoke actor method
response, err := actorRuntime.Invoke(
    ctx,
    "MyActor",
    "actor-id-123",
    "DoWork",
    []byte("payload"),
)

// Initialize binding
binding := runtime.NewBinding("kafka-binding")

// Send to external system
err := binding.Send(ctx, &runtime.InvokeRequest{
    Data: []byte("message"),
    Metadata: map[string]string{
        "topic": "orders",
    },
})

// Receive from external system
binding.Receive(func(req *runtime.InvokeRequest) (*runtime.InvokeResponse, error) {
    // Process incoming message
    return &runtime.InvokeResponse{Data: []byte("ack")}, nil
})

Capa Runtime is part of the Capa Cloud ecosystem:

We welcome contributions to Capa Runtime!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

# Clone and build
git clone https://github.com/capa-cloud/capa.git
cd capa

# Download dependencies
go mod download

# Run tests
go test ./...

# Build binary
go build -o capa-runtime ./cmd

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Building the future of cloud-native applications with Multi-Runtime architecture

Capa Cloud · Documentation