Container Guidelines

Capability containers run inside the Selu Docker network alongside the orchestrator. To keep things secure and performant, follow these guidelines when building your container image.

Networking

• Your gRPC server must listen on port 50051. The orchestrator expects this and maps it automatically.
• Capabilities can make outbound HTTP/HTTPS requests to external APIs. There are no egress restrictions by default.
• Capabilities cannot communicate directly with other capability containers. All inter-capability coordination goes through the orchestrator via delegate_to_agent.
• The orchestrator connects to your container over the internal Docker bridge network. Do not bind to 127.0.0.1 — bind to 0.0.0.0 or [::].

Resource limits

The orchestrator enforces resource limits declared in your manifest.yaml. If you don’t declare limits, sensible defaults apply:

Resource	Default	Max
Memory	256 Mi	1 Gi
CPU	0.5 cores	2 cores
Timeout per invocation	30 s	120 s
Disk (ephemeral)	512 Mi	2 Gi

Caution

If your container exceeds its memory limit, Docker will kill it (OOMKill). The orchestrator will report a capability failure to the LLM. Size your limits generously during development and tighten them before publishing.

Image best practices

• Use minimal base images — python:3.12-slim, golang:1.22-alpine, or debian:bookworm-slim. Smaller images mean faster installs for users.
• Multi-stage builds — Compile in a build stage, copy only the binary/runtime into the final stage.
• Pin versions — Always pin base image tags and dependency versions for reproducibility.
• Non-root user — Run your process as a non-root user. Selu will flag images that run as root during marketplace review.

Example multi-stage Dockerfile:

Dockerfile

FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY . .
USER 1000
EXPOSE 50051
CMD ["python", "server.py"]

Security

• No host mounts — Capabilities cannot mount host directories. All file access is scoped to the container’s ephemeral filesystem.
• No privileged mode — Containers run unprivileged. Capabilities that need special Linux capabilities will be rejected from the marketplace.
• Secrets via environment variables — Use the env section in manifest.yaml to declare required credentials. The orchestrator injects them at startup from the user’s encrypted credential store. Never hard-code secrets.
• No inbound ports — Only port 50051 is exposed, and only to the internal Docker network. Capabilities are not accessible from outside the Selu stack.

Danger

Never bundle API keys, tokens, or secrets in your Docker image. Images published to the marketplace are publicly pullable. Use environment variables instead.

Health checks

Implement the HealthCheck RPC from capability.proto. The orchestrator calls it periodically (default every 30 s). If three consecutive checks fail, the orchestrator restarts the container.

You can also expose an HTTP health endpoint at /healthz for Docker’s built-in health check:

HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/healthz || exit 1

Next steps

See the gRPC Interface for the full proto contract, or walk through the Example: Weather Agent for a complete working capability.