voiyd

command module
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

Lightweight, event‑driven orchestration for container workloads
voiyd.io

Go Reference Release Go

Voiyd is a lightweight container orchestration platform with a central server and agent nodes. It lets you schedule and manage containers across many number of arbitrary Linux hosts using a simple CLI. It’s designed to be small, understandable, and easy to run on your own infrastructure.

Features

  • Central control plane: voiyd-server provides a gRPC/HTTP API and manages cluster state.
  • Node agent: voiyd-node runs on each worker node and integrates with containerd. More runtimes are beeing added.
  • Container management: Create, run, start, stop, update, and delete containers. Manage “containersets” as grouped workloads.
  • Volume management: Create and attach host-local volumes. Snapshot and template support (where configured).
  • Scheduling: Built-in scheduler for placing workloads on nodes. Horizontal scheduling utilities for multi-node clusters.
  • Event and log streaming: Event service for cluster events. Log service for streaming container logs.
  • Node management and upgrades: Node upgrade support and associated controllers.
  • Pluggable storage backends: BadgerDB-based repository implementation. In-memory repositories for testing.
  • CLI-focused: Use voiydctl to manage clusters.
  • Instrumentation: Metrics and tracing hooks in pkg/instrumentation.

Architecture Overview

Voiyd is an event‑driven system. When you issue a command with voiydctl (for example run), the CLI sends a request to the server. The server validates the request, updates cluster state, and emits an event (such as ContainerCreate).

Nodes are completely walled off from the outside: the server never connects to them. Instead, each voiyd-node establishes an outbound connection to the server, subscribes to the event stream, and reports its own status. As long as a node can reach the server, it can participate in the cluster—even if it is behind NAT, firewalls, or in a different network segment—because all communication is initiated from the node side.

  • Control plane: voiydtl-server
    • Exposes gRPC/HTTP APIs defined in api/.
    • Stores cluster resources via the repository layer.
    • State replication for redundancy is in development.
  • Node agent: voiyd-node
    • Runs on each node.
    • Establishes an outbound connection to the server and subscribes to events.
    • Manages containers using a runtime and reports status and metrics back to the server.
    • Can operate behind NAT/firewalls as long as it can reach the server.
  • CLI: voiyd
    • Talks only to the server and never connects directly to nodes.
    • Provides subcommands for create/get/apply/delete, logs, upgrade, etc.

Prerequisites

voiyd-server and voiydctl can run on pretty much any platform whereas voiyd-node requires Linux with the following requirements:

Getting Started

You can install voiyd either from source or using pre-built binaries from releases.

Install From Releases

  1. Go to releases.

  2. Download the binary for your platform.

  3. Make it executable and move it into your PATH

    chmod +x voiydctl voiyd-server voiyd-node
sudo mv voiydctl voiyd-server voiyd-node /usr/local/bin/

Build From Source

git clone https://github.com/amimof/voiyd.git
cd voiyd
make

To build a specific binary you may run make voiydctl, make node or make server. Use env variables to specify target os, architecture and binary name with GOOS, GOARCH and BINARY_NAME. For example:

GOOS=windows GOARCH=amd64 BINARY_NAME=voiyd-server-windows-amd64.exe make server

Alternatively, use go install directly:

go install github.com/amimof/voiyd/cmd/voiyd-node
go install github.com/amimof/voiyd/cmd/voiyd-server
go install github.com/amimof/voiyd

NOTE: Run make help for more information on all potential make targets

Quick Start

  1. Generate certificates. See instruction here. Alternatively you may use pre-generated development certificates under ./certs. These certificates are for testing purposes only!

  2. Start the server

    voiyd-server \
    --tls-key ./certs/server.key \
    --tls-certificate ./certs/server.crt \
    --tls-ca ./certs/ca.crt \
    --tls-host 0.0.0.0 \
    --tcp-tls-host 0.0.0.0

  3. Run any number of node instances

    voiyd-node \
    --tls-ca ./certs/ca.crt \
    --port 5743

  4. Create a voiydctl configuration

    voiydctl config init
voiydctl config create-server dev --address localhost:5743 --tls --ca ./certs/ca.crt

  5. Run a container

    voiydctl run victoria-metrics --image docker.io/victoriametrics/victoria-metrics:v1.130.0

License

voiyd is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Contributing

You are welcome to contribute to this project by opening PR's. Create an Issue if you have feedback

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
api
services/containers/v1
Package containers is a reverse proxy.
 Package containers is a reverse proxy.
services/containersets/v1
Package containersets is a reverse proxy.
 Package containersets is a reverse proxy.
services/events/v1
services/logs/v1
services/nodes/v1
Package nodes is a reverse proxy.
 Package nodes is a reverse proxy.
services/volumes/v1
Package volumes is a reverse proxy.
 Package volumes is a reverse proxy.
types/v1
cmd
voiyd-node command
voiyd-server command
voiydctl
Package cmd provides command line capabilities to build cli tool
 Package cmd provides command line capabilities to build cli tool
voiydctl/apply
Package apply provides ability to apply resources to the server
 Package apply provides ability to apply resources to the server
voiydctl/config
Package config provides ability to manage voiydctl configuration
 Package config provides ability to manage voiydctl configuration
voiydctl/create
Package create provides ability to create resources from the server
 Package create provides ability to create resources from the server
voiydctl/create/volume
Package volume provides command line features to create volume resources
 Package volume provides command line features to create volume resources
voiydctl/delete
Package delete provides ability to delete resources from the server
 Package delete provides ability to delete resources from the server
voiydctl/edit
Package edit provides ability to edit resources from the server
 Package edit provides ability to edit resources from the server
voiydctl/get
Package get provides ability to get resources from the server
 Package get provides ability to get resources from the server
voiydctl/log
Package log provides ability to log resources from the server
 Package log provides ability to log resources from the server
voiydctl/run
Package run provides ability to run resources
 Package run provides ability to run resources
voiydctl/start
Package start provides ability to start resources
 Package start provides ability to start resources
voiydctl/stop
Package stop provides ability to stop resources
 Package stop provides ability to stop resources
voiydctl/upgrade
Package upgrade provides ability to upgrade nodes
 Package upgrade provides ability to upgrade nodes
pkg
cache
client
Package client provides a client interface to interact with server APIs
 Package client provides a client interface to interact with server APIs
client/container/v1
Package v1 is a generated GoMock package.
 Package v1 is a generated GoMock package.
client/containerd
client/containerset/v1
client/event/v1
Package v1 provides a client for working with events
 Package v1 provides a client for working with events
client/log/v1
Package log provides a client interface to interact with logs
 Package log provides a client interface to interact with logs
client/node/v1
Package v1 is a generated GoMock package.
 Package v1 is a generated GoMock package.
client/volume/v1
Package v1 is a generated GoMock package.
 Package v1 is a generated GoMock package.
cmdutil
Package cmdutil provides helper utilities and interfaces for working with command line tools
 Package cmdutil provides helper utilities and interfaces for working with command line tools
consts
Package consts provides consts used throughout the system
 Package consts provides consts used throughout the system
controller
Package controller provides an interface and various types implementing system specific and agnostic controllers
 Package controller provides an interface and various types implementing system specific and agnostic controllers
controller/containerd
controller/containerset
controller/node
Package nodecontroller implemenets controller and provides logic for multiplexing node management
 Package nodecontroller implemenets controller and provides logic for multiplexing node management
controller/nodeupgrade
controller/scheduler
controller/volume
errors
Package errors provides convenient constructs to work with errors
 Package errors provides convenient constructs to work with errors
events
Package events provides interfaces and types for working with events
 Package events provides interfaces and types for working with events
instrumentation
labels
logger
Package logger provides interfaces and implementations for working with logs
 Package logger provides interfaces and implementations for working with logs
networking
node
protoutils
repository
Package repository provides interfaces for implementing storage solutions for types
 Package repository provides interfaces for implementing storage solutions for types
runtime
Package runtime provides an interface for container runtime environments as well as some builtin implementations such as containerd.
 Package runtime provides an interface for container runtime environments as well as some builtin implementations such as containerd.
scheduling
Package scheduling provides interface to implement workload schedulers
 Package scheduling provides interface to implement workload schedulers
server
Package server provides types that creates and runs server instances
 Package server provides types that creates and runs server instances
util
volume
Package volume provides an API for working with volumes on nodes
 Package volume provides an API for working with volumes on nodes
container
Package container provides the server implemenetation for the container service
 Package container provides the server implemenetation for the container service
containerset
event
Package event implements the event service
 Package event implements the event service
log
Package log implements the log service
 Package log implements the log service
node
Package node
 Package node
volume

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.