🟢 Static Container Builder

Expand your hub effortlessly. Build and deploy isolated static containers to securely add new agents and apps to your local server without dependency chaos.

Overview

The Static Container Builder is a build-and-deploy tool for creating hermetically sealed, read-only containers that run on your Companion Hub. It provides a simple workflow for packaging custom agents, scripts, web UIs, or third-party tools into containers that integrate cleanly with the Hub’s networking, storage, and agent runtime — without polluting your host system or creating dependency conflicts.

Containers built with the Static Container Builder are pinned at build time. Their file systems are immutable at runtime, eliminating whole classes of configuration drift and supply-chain risk that affect mutable containers.

Key Features

Hermetic builds — all dependencies are resolved and vendored at build time; no network access at runtime
Hub-native networking — automatically registers a *.ci.localhost hostname via the Gateway
Agent manifest — declare MCP tools, memory hooks, and capabilities in a single companion.yaml
Multi-arch builds — produces images for amd64 and arm64 from a single build command
Layer caching — uses the Tools Cache Mount for fast incremental rebuilds
Hub app store packaging — output format is compatible with Companion Hub’s app store manifest, so you can distribute privately or publicly

Use Cases

Package a custom Python agent with local LLM access into a Hub-deployable container
Isolate an experimental tool without risking your production Hub configuration
Distribute custom apps to other Hub users via a private Marketplace channel
Run static web UIs (dashboards, admin panels) as first-class Hub apps with proper authentication

Architecture


Source Directory
  ├── companion.yaml        (manifest)
  ├── Dockerfile (or auto)  (build spec)
  └── src/                  (application code)
         │
         ▼
  Static Container Builder CLI
         │  hermetic build
         ▼
  OCI Image (immutable layers)
         │
         ▼
  Companion Hub Registry  ──▶  Hub App Store (optional)
         │
         ▼
  Running Container
    ├── Gateway registration  (*.ci.localhost)
    ├── Memory hooks          (Digital Memory API)
    └── MCP tool endpoints    (Agent integration)

Manifest Format

Every app built with the Static Container Builder includes a companion.yaml:


name: my-custom-agent
version: 1.0.0
description: A custom local AI agent
icon: icon.png
 
ports:
  - 8080
 
hostname: my-agent   # accessible at http://my-agent.ci.localhost
 
memory:
  read: true          # can query Digital Memory
  write: false        # cannot write to Digital Memory
 
mcp:
  tools:
    - name: search_web
      endpoint: /mcp/tools/search_web
 
environment:
  - name: OLLAMA_HOST
    default: http://ollama.ci.localhost

Setup

Install the CLI

The Static Container Builder CLI ships with Companion Hub. If you need to install it manually:


curl -fsSL https://get.ci.computer/builder | sh

Verify the install:


ci-builder --version

Scaffold a new project


ci-builder init my-project
cd my-project

This creates:

- companion.yaml
- Dockerfile

Build the container


ci-builder build .

Add --platform linux/amd64,linux/arm64 for multi-arch output.

Deploy to Hub


ci-builder deploy --hub http://hub.ci.localhost

The container will appear in your Hub dashboard under Apps → Custom.

Usage

Incremental Rebuilds

The builder caches layers using the Tools Cache Mount. After the first build, subsequent builds only rebuild changed layers.


ci-builder build . --cache

Packaging for the Marketplace


ci-builder package . --output my-app.tar.gz

Upload the resulting archive to your private Marketplace channel or the public CI Marketplace.

Inspecting a Built Image


ci-builder inspect my-custom-agent:1.0.0

This shows the manifest, declared ports, memory permissions, and MCP tool endpoints.

Troubleshooting

Build fails with dependency resolution error The builder vendors all dependencies. If a package cannot be found, verify your requirements.txt / package.json uses pinned versions. Run ci-builder build . --verbose for detailed output.

Container not reachable at *.ci.localhost Ensure the Gateway is running in Hub. Check companion.yaml for correct hostname value. Hostnames must be lowercase alphanumeric with hyphens only.

MCP tools not visible to agents Confirm the container is running (ci-builder status) and the MCP endpoint returns a valid response at http://my-agent.ci.localhost/mcp/tools.

Multi-arch build fails on Apple Silicon Ensure Docker’s multi-platform emulation is enabled: docker run --privileged --rm tonistiigi/binfmt --install all.