Cloud Application API · Multi-Runtime Sidecar · Write Once, Run Anywhere
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.
Project status: This repository provides a buildable experimental gRPC runtime baseline. Runtime startup, metadata RPCs, and graceful shutdown are tested; actor methods return gRPC
UNIMPLEMENTEDwhile they remain scaffolding. HTTP interception, bindings, and SaaS integrations are roadmap items rather than production-ready features.
| Component | Description | Current Use |
|---|---|---|
| Capa SDK | Language-native Cloud Application APIs | Application integration |
| Capa Runtime | Optional gRPC sidecar | Metadata, lifecycle, and future extended APIs |
capa/
├── cmd/capa/ # Runtime entry point
├── pkg/ # Core packages
│ ├── actors/ # Actor API scaffolding
│ ├── grpc/ # gRPC API and server lifecycle
│ ├── proto/ # Generated Runtime API types
│ └── runtime/ # Core runtime lifecycle
├── docker/ # Docker configurations
├── spec/ # Runtime API specification
└── utils/ # Utility functions
Key Design Principles:
- Optional Sidecar: Capa Runtime is optional; SDK works independently
- Small Runtime Surface: Only implemented packages participate in builds
- Explicit Lifecycle: Startup failures propagate and shutdown is bounded
- Extensible API: Generated gRPC contracts provide the integration boundary
| Capability | Status | Notes |
|---|---|---|
| gRPC runtime server | ✅ Baseline | Starts on configured addresses and registers the Runtime API |
| Metadata API | ✅ Implemented | Stores and retrieves runtime metadata in memory |
| Graceful shutdown | ✅ Implemented | Stops on signals or the Shutdown RPC with a bounded timeout |
| Actor API | 🔬 Scaffolding | RPC contracts return gRPC UNIMPLEMENTED; persistence and execution are not implemented |
| HTTP interception | 🗺️ Roadmap | Not included in the current runtime |
| Bindings and SaaS | 🗺️ Roadmap | Not included in the current runtime |
While Capa SDK provides rich functionality, some capabilities require sidecar architecture:
- Actor Model: Requires persistent connections and scheduling
- Traffic Interception: Needs network-level control (iptables)
- Binding: Benefits from decoupled event processing
| Capability | SDK | Runtime | Notes |
|---|---|---|---|
| Cloud APIs | ✅ | — | Use the language SDK directly |
| Metadata | — | ✅ | Implemented by the gRPC runtime |
| Lifecycle shutdown | — | ✅ | Signal and RPC initiated |
| Actor | ❌ | 🔬 | Contract only; implementation is incomplete |
| Binding | ✅ | 🗺️ | Runtime support is a roadmap item |
| Traffic interception | ❌ | 🗺️ | Not included in the current runtime |
- Go 1.25 or higher with automatic toolchain selection enabled; this repository selects Go 1.26.5 for patched builds
- Docker (optional, for containerized deployment)
- Kubernetes (optional, for orchestrated deployment)
# Clone the repository
git clone https://github.com/capa-cloud/capa.git
cd capa
# Verify and build the runtime
go test ./...
go build -o capa ./cmd/capa
# Run locally
./capa --app-id example --port 3500# Build Docker image from the repository root
docker build -f docker/Dockerfile -t capa-runtime:latest .
# Run container
docker run -d \
--name capa-runtime \
-p 3500:3500 \
capa-runtime:latestapiVersion: 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
args: ["--listen-address=0.0.0.0", "--port=3500"]
ports:
- containerPort: 3500
---
apiVersion: v1
kind: Service
metadata:
name: capa-runtime
spec:
selector:
app: capa-runtime
ports:
- port: 3500
targetPort: 3500The runtime is configured with command-line flags:
| Flag | Default | Description |
|---|---|---|
--app-id |
capa-app |
Application identifier |
--env |
local |
Application environment |
--cloud |
local |
Cloud provider identifier |
--listen-address |
127.0.0.1 |
gRPC API listen address |
--port |
3500 |
gRPC API port |
--callback-port |
3501 |
Application callback port reserved for actor integration |
--shutdown-timeout |
10s |
Maximum graceful shutdown duration |
The gRPC contract is defined in
spec/proto/runtime/v1/runtime.proto.
The current executable registers the generated Runtime service and implements
metadata and shutdown behavior. Actor RPCs are present for compatibility but
return gRPC UNIMPLEMENTED until an actor runtime is available. The Shutdown
RPC also completes the process lifecycle; no additional operating-system signal
is required.
Capa Runtime is part of the Capa Cloud ecosystem:
| Project | Language | Description |
|---|---|---|
| capa-java | Java | Java SDK implementation |
| capa-go | Go | Go SDK implementation |
| cloud-runtimes-jvm | Java | JVM API specification |
| cloud-runtimes-golang | Go | Go API specification |
We welcome contributions to Capa Runtime!
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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 ./...
# Vet and build the binary
go vet ./...
go build -o capa ./cmd/capaThis 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