tinycode-container

Single container image running tinycode (web mode) for deployment to OpenShift and Kubernetes. tinycode is a single Go binary — no Node.js, Bun, or separate plugin process required.

What is this?

This project packages the tinycode binary as a self-contained container image suitable for multi-tenant Kubernetes/OpenShift environments. The container runs tinycode's web mode, exposing an HTTP API and embedded web UI on port 4096.

The container interface (port, UID, health endpoints, volume mounts, environment variables) is documented in CONTAINER.md, which is the authoritative contract between this image and the tinycode-operator that deploys it.

Note: A bare container can only chat with the model — it has no project files to work on. To make tinycode useful on a cluster, give it context: clone a git repo (TINYCODE_GIT_REPO), enable cluster-admin mode (TINYCODE_CLUSTER_ADMIN=true), or mount a host path with existing code. See Environment Variables for the full list.

Quick Install

curl -fsSL https://raw.githubusercontent.com/bobbyjohnstx/tinycode-container/main/install.sh | sh

This installs a tinycode wrapper script that:

• Pulls the container image if not present
• Starts a named container with persistent volumes on first run
• Attaches to the existing container on subsequent runs (sub-second startup)
• Detects podman vs docker automatically

To uninstall: tinycode --uninstall

Prerequisites

• podman or docker (for running and local builds)
• kubectl or oc (for Kubernetes/OpenShift deployment)

Multi-Architecture Support

The container image is built for both linux/amd64 and linux/arm64. CI produces a multi-arch manifest, so podman pull or docker pull selects the correct architecture automatically.

Build Locally

# Build for the current architecture
podman build -f ContainerFile \
  -t quay.io/bjohns/tinycode-container:latest .

# Build for a specific architecture
podman build -f ContainerFile \
  --platform linux/arm64 \
  -t quay.io/bjohns/tinycode-container:latest .

The build downloads the tinycode release binary for the target platform and installs it into a UBI9 runtime image with a non-root user (UID 1001, GID 0).

Run Locally (Quick Test)

# Run the container in detached mode
podman run -d -p 4096:4096 quay.io/bjohns/tinycode-container:latest

# Open the web UI
open http://localhost:4096

For persistent storage during local testing:

podman run -d -p 4096:4096 \
  --name tinycode \
  -v tinycode-data:/home/tinycode/.local/share/tinycode \
  -v tinycode-config:/home/tinycode/.config/tinycode \
  quay.io/bjohns/tinycode-container:latest

Session Attach

Set the TINYCODE_SESSION_ID environment variable to attach to an existing session on container start:

podman run -d -p 4096:4096 \
  -e TINYCODE_SESSION_ID=my-session \
  quay.io/bjohns/tinycode-container:latest

Deploy to OpenShift

Base Deployment

# Deploy base resources (Deployment, Service, Route)
kubectl apply -k k8s/base

Deployment Variants

Ephemeral (no PVC — testing only):

kubectl apply -k k8s/overlays/ephemeral

Generic Kubernetes (Ingress instead of Route):

kubectl apply -k k8s/overlays/ingress

For production OpenShift deployments, consider using the tinycode-operator, which manages TinycodeInstance CRs and handles storage, routing, and SCCs automatically.

Credentials Setup

The tinycode web UI requires authentication. To set the password:

1. Copy the secret template:

   cp k8s/secrets/secret-template.yaml k8s/secrets/secret.yaml

2. Edit k8s/secrets/secret.yaml and set your desired password (base64-encoded).

3. Apply the secret:

   kubectl apply -f k8s/secrets/secret.yaml

Architecture

Base Image: Red Hat UBI9 (OpenShift-compatible) Port: 4096 (HTTP) User: UID 1001 (non-root), GID 0 (OpenShift arbitrary UID support via g=u) Health Probes: GET /global/health (unauthenticated, liveness + readiness) Persistence: PVC mounts for:

• /home/tinycode/.local/share/tinycode (SQLite DB, session history)
• /home/tinycode/.config/tinycode (user configuration)
• /projects (user workspace files, separate PVC)

Configuration Hierarchy:

User customizations should go in tinycode.jsonc (PVC-persisted) to survive image upgrades.

Load order (lowest to highest priority): config.json → tinycode.json → tinycode.jsonc

XDG Base Directories:

Variable	Value
XDG_DATA_HOME	/home/tinycode/.local/share
XDG_CONFIG_HOME	/home/tinycode/.config
XDG_STATE_HOME	/home/tinycode/.local/state
XDG_CACHE_HOME	/home/tinycode/.cache

Environment Variables:

For the complete environment variable reference, see CONTAINER.md.

CI/CD

The GitHub Actions workflow (.github/workflows/build-push.yaml) automatically builds and pushes multi-arch images to quay.io/bjohns/tinycode-container on every push to main:

• Platforms: linux/amd64, linux/arm64
• Tags: :latest and :<git-sha>
• Smoke test: Runs tinycode --version on both architectures
• Registries: Quay.io (primary), GitHub Container Registry (mirror)

Features

• GitOps Mode: Clone a git repository on container startup via TINYCODE_GIT_REPO, with optional auto-pull on restart
• vLLM Auto-Configuration: Set TINYCODE_VLLM_URL to auto-configure vLLM endpoint and model
• RHOAI/OpenShift Auto-Detection: Automatically detects Kubernetes environment
• Cluster-Admin Mode: Enable TINYCODE_CLUSTER_ADMIN=true to download oc CLI and access cluster management capabilities
• Swarm Tool: /swarm dispatches parallel agents as goroutines (no tmux needed — Go's native concurrency)
• Input Validation: TINYCODE_VLLM_MODEL is validated to prevent shell injection (alphanumeric, /, -, . only)
• Read-Only Root: Container filesystem can be mounted read-only for additional security
• Security Headers: Server includes standard security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.)

Known Limitations

• Health probes can use tcpSocket instead of GET /global/health if the health endpoint requires authentication in your deployment (see k8s/base/deployment.yaml comments).

Ecosystem

Project	Description
tinycode	Core binary — server, TUI, web UI, 23 agents, 32 plugins, 7 skills
tinycode-container	This repo — OCI container image
tinycode-operator	Kubernetes Operator for OpenShift
homebrew-tap	Homebrew formula for macOS/Linux

License

MIT — see LICENSE.