Skip to content
BranchesTags

Repository files navigation

Rune

Rune is a lightweight, powerful orchestration platform designed to simplify the deployment and management of services across environments. It's inspired by Kubernetes and Nomad but focuses on developer simplicity and minimal operational complexity.

Features

  • Simple deployment: Deploy services with a single command
  • Multi-service deployments: Runesets for complex application stacks with templating
  • Multi-environment: Seamlessly run services across development, testing, and production
  • Lightweight: Minimal resource footprint
  • Container-native: First-class support for containerized applications
  • Process-aware: Run and manage local processes when containers aren't needed
  • Dependency-aware: Automatically manage service dependencies
  • Multi-node: Scale across multiple nodes
  • Built-in security: Authentication, authorization, and encryption
  • Web dashboard: Embedded browser dashboard for live cluster ops — services, logs, exec, secrets, RBAC
  • Interactive debugging: Exec into running services for real-time debugging
  • Health monitoring: Built-in health checks and probes
  • Rollback support: Version history and instant rollbacks
  • Structured logging: Comprehensive logging with multiple outputs

Quick Start

Prerequisites

  • Go 1.19 or later
  • Docker (for container-based services)

Installation

Quick Install (Recommended)

# CLI (your machine) — latest release, no root needed
curl -fsSL https://get.runestack.io | sh

# Server (a node) — Docker + runed + systemd; latest release, requires root
curl -fsSL https://install.runestack.io | sudo sh

Both default to the latest release. Pin a version or tweak options by passing flags after -s --:

# Pin the CLI to a specific release, or install somewhere on your PATH
curl -fsSL https://get.runestack.io | sh -s -- --version v0.0.1-dev.116
curl -fsSL https://get.runestack.io | sh -s -- --install-dir ~/.local/bin

# Pin the server version / set ports
curl -fsSL https://install.runestack.io | sudo sh -s -- --version v0.0.1-dev.116 --http-port 7861

The one-liners are served from get.runestack.io / install.runestack.io, which front scripts/install-cli.sh and scripts/install.sh in this repo. You can always pipe those raw URLs directly instead.

From Source

# Clone and build
git clone https://github.com/runestack/rune.git
cd rune
make setup
make build

# Install from source
go install github.com/runestack/rune/cmd/rune@latest

# Verify installation
rune version

Upgrade runed

Scripted upgrade (recommended)

# Upgrade runed on the server to v0.0.1-dev.10 (keeps config/data)
curl -fsSL https://raw.githubusercontent.com/runestack/rune/master/scripts/install-server.sh \
| sudo bash -s -- --version v0.0.1-dev.10 --skip-docker

Manual binary swap

VER=v0.0.1-dev.10
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64 ;; aarch64|arm64) ARCH=arm64 ;; *) echo "Unsupported arch"; exit 1 ;; esac

sudo systemctl stop runed
curl -L -o /tmp/rune.tgz "https://github.com/runestack/rune/releases/download/$VER/rune_linux_${ARCH}.tar.gz"
sudo tar -C /usr/local/bin -xzf /tmp/rune.tgz rune runed
sudo systemctl start runed

Verify

runed --version
sudo systemctl status runed --no-pager | cat

First Run & Bootstrap

After installing the Rune server (runed), you need to bootstrap the system and create your first user. Here are the essential steps:

1. Start the Server

# Start the server; auto-discovers runefile.{toml,yaml,yml} in cwd or /etc/rune
runed

# Or with an explicit config path
runed --config=/path/to/runefile.toml

2. Bootstrap the System

From another terminal, bootstrap the system to create the initial admin user:

# Bootstrap the system and save the token
rune admin bootstrap > ~/rune_bootstrap_token.txt

# This creates the server-admin user and generates a bootstrap token

3. Login as Server Admin

Use the bootstrap token to authenticate as the server admin:

# Login using the bootstrap token
rune login server-admin --token-file ~/rune_bootstrap_token.txt

# Verify you're logged in
rune whoami
# Should show: server-admin

4. Create Additional Users

Now you can create additional users with appropriate policies:

# Create a regular user with admin policy
rune admin token create --name github-actions --policy readwrite --out-file github_actions_token.txt
rune admin token create --name user123 --policy admin --out-file user123_token.txt

# Create a user with limited permissions
rune admin user create developer --password=devpass
rune admin policy create developer-policy.yaml
rune admin token create --name developer --policy developer-policy --out-file dev_token.txt

5. Switch to Regular User (Optional)

# Login as the new user
rune login developer --password=devpass

# Or use the token
rune login developer --token-file dev_token.txt

# Verify the switch
rune whoami
# Should show: developer

Bootstrap Complete!

You now have a fully configured Rune system with:

  • ✅ Server running and accessible
  • ✅ Initial admin user (server-admin) created
  • ✅ Bootstrap token for initial access
  • ✅ Additional users and policies configured
  • ✅ Ready for service deployment

Important Security Notes:

  • Keep bootstrap tokens secure - they have full admin access
  • Delete bootstrap tokens after creating regular users
  • Implement least-privilege policies for production use

Dashboard

Runed ships an embedded web dashboard (enabled by default) for live cluster operations — services, instances, logs, exec, secrets, networking and RBAC. Open it, signed in with your CLI session and tunnelled over your authenticated connection — no exposed port, no SSH:

rune ui

For ports, the ui.* config (require_tls and friends), accessing a remote server, and rune ui --url for TLS-fronted deployments, see The web dashboard.

Core Concepts

Services

Services are the basic unit of deployment in Rune. They can be containers, processes, or any executable application.

# service.yaml
service:
  name: "api"
  image: "my-api:latest"
  ports:
    - 8080:80
  scale: 3
  health:
    liveness:
      type: http
      path: /healthz
      port: 8080

Runesets

Runesets are multi-service deployment packages that allow you to deploy complex application stacks as a single unit.

runeset/
├── runeset.yaml          # Main manifest
├── casts/                # Service definitions
│   ├── api.yaml         # API service
│   ├── database.yaml    # Database service
│   └── cache.yaml       # Cache service
├── values/               # Environment values
│   ├── dev.yaml         # Development
│   └── prod.yaml        # Production
└── templates/            # Template files

Namespaces

Rune supports namespaces for environment isolation and multi-tenancy.

# Deploy to specific namespace
rune cast service.yaml -n production

# List services in namespace
rune get services -n staging

Usage Examples

Basic Service Management

# Deploy a service
rune cast service.yaml

# Scale a service
rune scale api 5

# Check service status
rune status api

# View logs
rune logs api --follow

# Delete a service
rune delete api

Multi-Service Deployments

# Deploy entire runeset
rune cast runeset/

# Deploy with specific values
rune cast runeset/ --values=production

# Preview rendered YAML
rune cast runeset/ --render-only

Interactive Debugging

# Open an interactive shell (bash if present, else sh) — no command needed
rune exec api
rune exec -n prod web

# Simple commands inline
rune exec api ps aux

# Commands with flags: use '--' so rune doesn't try to parse them
rune exec api -- ls -la /app
rune exec api -- bash -c "echo $HOSTNAME"

# Set working directory and environment
rune exec api --workdir=/app --env=DEBUG=true -- python debug.py

Service Operations

# Restart service (bounce instances)
rune restart api

# Stop service (scale to 0)
rune stop api

# Check health status
rune health api

# Rollback to previous version
rune rollback api

Validation and Quality

# Validate YAML files
rune lint service.yaml
rune lint runeset/

# Check service dependencies
rune deps api

Authentication & Security

Rune provides built-in authentication and security features.

User Management

# Create admin user
rune admin user create admin --password=secret

# Create regular user
rune admin user create developer --password=devpass

# List users
rune admin user list

Policy Management

# policy.yaml
name: "developer-policy"
description: "Developer access policy"
rules:
  - resource: "services"
    actions: ["get", "logs", "exec"]
    namespaces: ["dev", "staging"]
# Create policy
rune admin policy create policy.yaml

# List policies
rune admin policy list

API Tokens

# Generate token for user
rune admin token generate --user=developer

# List tokens
rune admin token list

Authentication Flow

# Login interactively
rune login

# Login with credentials
rune login --username=developer --password=devpass

# Check current user
rune whoami

# Use token for API access
export RUNE_API_TOKEN="your-token-here"
rune get services

Configuration

Server Configuration (runefile.{toml,yaml})

The server configuration file contains registry authentication, Docker settings, and server options. Both TOML and YAML are supported; TOML is the canonical format for production deployments.

# Auto-discover the runefile from cwd or /etc/rune
runed

# Use an explicit config path
runed --config=/path/to/runefile.toml

Configuration locations (in order of precedence):

  1. --config flag - Explicitly specified file
  2. ./runefile.{toml,yaml,yml} - Local development override
  3. /etc/rune/runefile.{toml,yaml,yml} - System-wide production config

If none of these is found, runed exits with an error; production deployments must ship a runefile.

Example server configuration:

# runefile.yaml
server:
  grpc_address: ":7863"
  http_address: ":7861"

docker:
  registries:
    - name: "ecr-prod"
      registry: "123456789012.dkr.ecr.us-west-2.amazonaws.com"
      auth:
        type: "ecr"
        region: "us-west-2"

log:
  level: "info"
  format: "json"
  outputs:
    - "console"
    - "file:/var/log/rune.log"

Client Configuration ($HOME/.rune/config.yaml)

Client configuration manages connections to Rune servers:

# $HOME/.rune/config.yaml
current-context: production
contexts:
  production:
    server: "https://rune.company.com:7863"
    token: "your-auth-token"
    defaultNamespace: "production"
  development:
    server: "localhost:7863"
    token: "dev-token"
    defaultNamespace: "dev"

Client config locations:

  • $HOME/.rune/config.yaml - User's home directory
  • $RUNE_CLI_CONFIG - Environment variable override

CLI Configuration

Manage CLI settings and preferences:

# Set API server
rune config set api-server localhost:8080

# Get configuration
rune config get api-server

# List all settings
rune config list

CI/CD with GitHub Actions

Deploy services automatically using the Rune CLI in GitHub Actions:

# .github/workflows/rune-deploy.yml
name: Deploy to Rune
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to Rune
        run: |
          rune cast runeset/ --values=production

See the CI/CD guide on docs.runestack.io for complete setup instructions.

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/runestack/rune.git
cd rune

# Install development dependencies
make setup

# Build the project
make build

# Run tests
make test

# Run specific test types
make test-unit          # Unit tests only
make test-integration   # Integration tests only

# Code quality
make lint               # Run linting
make coverage-summary   # Test coverage report

Key Development Commands

# Build binaries
make build              # Build rune and runed
make install            # Install to $GOPATH/bin

# Development environment
make dev                # Start development environment
make proto              # Generate protobuf files

# Testing
make test               # All tests
make test-unit          # Unit tests
make test-integration   # Integration tests
make coverage-summary   # Coverage report

# Code quality
make lint               # Linting
make fmt                # Format code

Project Structure

rune/
├── cmd/                # Main binaries
│   ├── rune/          # CLI tool
│   └── runed/         # Server daemon
├── pkg/                # Core packages
│   ├── cli/           # CLI framework and commands
│   ├── api/            # API server and client
│   ├── orchestrator/   # Service orchestration
│   ├── runner/         # Service runners (Docker/Process)
│   ├── store/          # State persistence
│   ├── types/          # Core types and YAML parsing
│   ├── crypto/         # Security and encryption
│   ├── log/            # Structured logging
│   └── worker/         # Task execution framework
├── examples/            # Example services and runesets
└── test/                # Integration tests

Architecture

Rune follows a client-server architecture:

  • Control Plane (runed): Manages state, orchestrates services, provides APIs
  • CLI (rune): User interface for service management operations
  • Runners: Execute services (Docker containers or local processes)
  • Store: Persistent state using BadgerDB with future etcd support
  • Authentication: Built-in user management and API security

Data Flow

CLI → Client → API → Orchestrator → Store + Runner

Documentation

User-facing documentation lives at docs.runestack.io (source: runestack/docs).

Repo-local references:

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

  • Setting up your development environment
  • Code style and conventions
  • Testing guidelines
  • Pull request process

License

Rune is licensed under the Apache License, Version 2.0 — see LICENSE for the full text and NOTICE for attribution and trademark terms.

Apache-2.0 was chosen over a shorter permissive licence for three reasons that matter to anyone running this in production:

  • An explicit patent grant (§3), with termination for anyone who sues over patents in the software. A permissive licence that is silent on patents leaves that exposure open for you and for us.
  • Clear contributor terms (§5) — contributions are licensed under the same terms by default, so the provenance of the code you depend on is unambiguous.
  • Explicit trademark reservation (§6). The code is yours to use, modify, fork and redistribute. The name is not: "Rune" and the Rune marks are reserved, so a fork is always distinguishable from the project.

It is also the licence the infrastructure Rune sits beside uses — Kubernetes, containerd, Envoy, Prometheus, etcd — which keeps Rune inside the set of licences enterprise procurement already accepts.

Relicensed from MIT in 2026 while copyright was held solely by the author. Prior releases remain available under the MIT terms they shipped with; the change is not retroactive.

About

Rune is a lightweight, powerful container orchestration platform designed to simplify the deployment and management of services across environments.

docs.runestack.io

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages