https://github.com/fertile-org/banyan
Banyan - Container orchestration you already know
https://github.com/fertile-org/banyan
container-orchestration deployment docker-compose monitoring observability orchestrator
Last synced: 4 months ago
JSON representation
Banyan - Container orchestration you already know
- Host: GitHub
- URL: https://github.com/fertile-org/banyan
- Owner: fertile-org
- License: apache-2.0
- Created: 2025-09-06T09:09:25.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T17:39:35.000Z (4 months ago)
- Last Synced: 2026-03-05T20:23:13.374Z (4 months ago)
- Topics: container-orchestration, deployment, docker-compose, monitoring, observability, orchestrator
- Language: Go
- Homepage: https://getbanyan.dev
- Size: 128 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Banyan
Container orchestration you already know.
Run containers across multiple servers with the Docker Compose syntax you already know.
Documentation ·
Quickstart ·
Roadmap ·
Development
SECURED BY
BUILT WITH
> **Under experiment.** Banyan is not yet production-ready. We encourage you to experiment, break things, and [share feedback](https://github.com/fertile-org/banyan/issues).
banyan-cli dashboard — monitor your entire cluster from the terminal
## From one server to many
You know Docker Compose. You write a `docker-compose.yml`, run `docker compose up`, and it works — on one machine.
Then you need more. More servers, more replicas, more availability. The usual next step involves weeks of learning, dozens of new concepts, and infrastructure that's heavier than your application.
**Banyan takes a different approach.** Same YAML syntax you already write, distributed across your servers. No new language to learn. No templating. No 50-page getting started guide.
## One manifest, production-ready
```yaml
name: my-app
services:
caddy:
image: caddy:latest
command: caddy reverse-proxy --from example.com --to api:8080
deploy:
placement:
node: gateway-* # ← pin to your public-facing servers
ports:
- "80:80"
- "443:443"
api:
build: ./api
deploy:
replicas: 3 # ← scale what you need
ports:
- "8080:8080"
environment:
- DB_HOST=db
db:
image: postgres:15-alpine
```
Same `services`, `build`, `ports`, `environment` you already know from Docker Compose. Add `deploy.replicas` to scale, `deploy.placement.node` to pin services to specific servers. One command to deploy: `banyan-cli up -f banyan.yaml`.
## What you get
- **The YAML you already know** — `services`, `build`, `image`, `ports`, `environment`, `depends_on`. Same fields, same structure, same muscle memory.
- **Three binaries, nothing else** — No package managers, no plugins, no Helm charts. Download `banyan-engine`, `banyan-agent`, and `banyan-cli`. That's the entire stack.
- **Built-in image registry** — Use `build:` in your manifest and Banyan builds, stores, and distributes images across your cluster. No Docker Hub account, no Harbor, no ECR setup.
- **Containers talk across servers** — Services on different machines communicate as if they were on the same network. Banyan handles the overlay network and DNS.
- **Live terminal dashboard** — `banyan-cli dashboard` opens a real-time TUI that shows engine health, agents, deployments, container status, and cluster events — all updating live. Navigate with keyboard shortcuts, drill into any agent or deployment, and use the command palette to jump between views. No Grafana setup, no browser, no YAML config. Your monitoring is one command away.
- **Open source, self-hosted** — Apache 2.0. No vendor lock-in, no usage-based pricing. Run it on your own servers.
## Who is Banyan for?
**Teams who've outgrown a single server but don't need — or don't want — Kubernetes.**
You might be a team of 5 who needs your API on 3 servers. Or a team of 50 who wants a lighter option for staging environments and internal tools. Either way, you want to write a YAML file and ship, not operate a platform.
Banyan handles the orchestration so you can focus on the software you're building.
## Install
```bash
# Engine node (control plane)
curl -sSL https://raw.githubusercontent.com/fertile-org/banyan/main/install.sh | sudo bash -s -- --role engine
# Worker nodes
curl -sSL https://raw.githubusercontent.com/fertile-org/banyan/main/install.sh | sudo bash -s -- --role agent
```
Or [build from source](https://getbanyan.dev/getting-started/installation/).
## Getting started
One-time setup (run once per machine):
```bash
# Control plane
sudo banyan-engine init # Generate keypair, configure etcd
sudo banyan-engine start # Starts the engine, etcd, and image registry
# Each worker
sudo banyan-agent init # Generate keypair, set engine address
# Copy agent's public key to engine: echo '' > /etc/banyan/whitelisted-keys/worker-1.pub
sudo banyan-agent start # Register and start accepting containers
# Your machine
sudo banyan-cli init # Generate keypair, set engine address
# Copy CLI's public key to engine: echo '' > /etc/banyan/whitelisted-keys/cli.pub
```
Then deploy — every time, one command:
```bash
banyan-cli deploy -f banyan.yaml
```
After the initial setup, deploying is always one command. See the [Quickstart](https://getbanyan.dev/getting-started/quickstart/) for a complete walkthrough.
## Architecture
```mermaid
graph TD
CLI[fa:fa-terminal banyan-cli] -->|gRPC| Engine
subgraph Engine[fa:fa-server banyan-engine]
Store[(fa:fa-database etcd)]
Registry[fa:fa-box-open Image Registry]
end
Engine -->|gRPC| Agent1
Engine -->|gRPC| Agent2
Engine -->|gRPC| AgentN
subgraph VPC[fa:fa-network-wired Banyan VPC]
subgraph G1[Gateway]
Agent1[fa:fa-cube banyan-agent]
C1{{fa:fa-box container: caddy-0}}
Agent1 ~~~ C1
end
subgraph A2[Worker 1]
Agent2[fa:fa-cube banyan-agent]
C2{{fa:fa-box container: api-0}}
C3{{fa:fa-box container: api-1}}
Agent2 ~~~ C2
Agent2 ~~~ C3
end
subgraph AN[Worker 2]
AgentN[fa:fa-cube banyan-agent]
C4{{fa:fa-box container: api-2}}
C5{{fa:fa-box container: db-0}}
AgentN ~~~ C4
AgentN ~~~ C5
end
end
CLI ~~~ Prom(fa:fa-chart-line Prometheus-compatible)
Engine -.-|/metrics| Prom
```
The **CLI** sends your manifest to the **Engine**, which stores state in etcd and schedules containers across **Agents**. Each Agent runs containerd and pulls images from the Engine's built-in registry. All gRPC communication is authenticated via public key whitelist and optionally encrypted through a WireGuard control tunnel (port 51821/UDP).
## Documentation
Full documentation at **[getbanyan.dev](https://getbanyan.dev/)**.
- [Installation](https://getbanyan.dev/getting-started/installation/)
- [Quickstart](https://getbanyan.dev/getting-started/quickstart/)
- [Manifest Reference](https://getbanyan.dev/reference/manifest/)
- [Multi-Node Setup](https://getbanyan.dev/guides/multi-node/)
- [CLI Reference](https://getbanyan.dev/reference/cli/)
- [Troubleshooting](https://getbanyan.dev/reference/troubleshooting/)
## Roadmap
See the [Roadmap](https://getbanyan.dev/roadmap/) — Prometheus metrics, resource-aware scheduling, auto-scaling, and more.
## Contributing
See the [Development Guide](./DEVELOPMENT.md) for project structure, build commands, and architecture.
## License
Apache License 2.0. See [LICENSE](./LICENSE) for details.