https://github.com/eminwux/sbsh
🚂 sbsh brings Terminal-as-Code to your workflow, making terminal environments reproducible, persistent, and safe to share across your team.
https://github.com/eminwux/sbsh
devops devops-team devops-tools reproducible-environments shell-profiles sre-team terminal terminal-manager
Last synced: 24 days ago
JSON representation
🚂 sbsh brings Terminal-as-Code to your workflow, making terminal environments reproducible, persistent, and safe to share across your team.
- Host: GitHub
- URL: https://github.com/eminwux/sbsh
- Owner: eminwux
- License: apache-2.0
- Created: 2025-08-23T14:50:43.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-20T20:46:12.000Z (4 months ago)
- Last Synced: 2025-11-20T22:20:14.580Z (4 months ago)
- Topics: devops, devops-team, devops-tools, reproducible-environments, shell-profiles, sre-team, terminal, terminal-manager
- Language: Go
- Homepage:
- Size: 5.66 MB
- Stars: 38
- Watchers: 0
- Forks: 0
- Open Issues: 51
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# 🚂 sbsh: Terminal-as-Code for reproducible, persistent and shareable shell environments
sbsh brings _Terminal-as-Code_ to your workflow: define terminal environments declaratively with YAML manifests that can be version-controlled, shared, and reused across your team. Each profile specifies environment variables, lifecycle hooks, startup commands, and visual prompts, ensuring consistent setups across local machines, jump hosts, and CI/CD pipelines. Terminals survive network drops, supervisor restarts, and accidental disconnects, remaining discoverable and shareable for collaboration.
**Demo - Launch a Terraform production workspace: profile automatically configures environment, workspace, and shows red warning prompt**
## Quick Start
Get sbsh up and running in minutes.
### Install
```bash
# Set your platform (defaults shown)
export OS=linux # Options: linux, darwin, freebsd
export ARCH=amd64 # Options: amd64, arm64
# Install sbsh
curl -L -o sbsh https://github.com/eminwux/sbsh/releases/download/v0.6.0/sbsh-${OS}-${ARCH} && \
chmod +x sbsh && \
sudo install -m 0755 sbsh /usr/local/bin/sbsh && \
sudo ln -f /usr/local/bin/sbsh /usr/local/bin/sb
```
### Autocomplete
```bash
cat >> ~/.bashrc < # Attach to a terminal
$ sb detach # Detach from supervisor
$ sb get profiles # List available profiles
```
Works from any machine that can access the socket files.
## Profiles: Declarative Environment Manifests
YAML manifests define terminal environments declaratively, the essence of _Terminal-as-Code_. Profiles specify environment variables, lifecycle hooks (`onInit`, `postAttach`), startup commands, and visual prompts. Version-controlled and shared across teams, preventing mistakes like applying Terraform to the wrong workspace or using the wrong Kubernetes cluster.
### Profiles by Example
**Terraform production workspace:**
```yaml
apiVersion: sbsh/v1beta1
kind: TerminalProfile
metadata:
name: terraform-prd
spec:
shell:
env:
TF_VAR_environment: "prd"
prompt: '"\[\e[1;31m\]sbsh(terraform-prd) \[\e[1;32m\]\u@\h\[\e[0m\]:\w\$ "'
stages:
onInit:
- script: terraform workspace use prd
- script: terraform init
```
**Kubernetes development terminal:**
```yaml
apiVersion: sbsh/v1beta1
kind: TerminalProfile
metadata:
name: k8s-default
spec:
shell:
env:
KUBE_CONTEXT: default
KUBE_NAMESPACE: default
stages:
onInit:
- script: kubectl config use-context $KUBE_CONTEXT
postAttach:
- script: kubectl get pods
```
→ See [docs/profiles/README.md](docs/profiles/README.md) for detailed examples and reference.
→ See [docs/features.md](docs/features.md) for a complete overview of features and capabilities.
## How It Works
Terminals run independently from supervisors, defined by profiles and running persistently.
1. Profile defines environment: YAML manifest specifies env vars, commands, hooks, and prompts
2. Terminal runs independently: Shell environment continues even if supervisor exits
3. All I/O captured and logged: Complete audit trail stored for every environment
4. Metadata stored for discovery: Terminal information enables true session discovery
5. Shareable and attachable: Multiple people can attach to the same environment
6. Reattach anytime, from anywhere: Discover and connect to environments by name or ID
## A Tool for Developers & Operations Teams
For teams who need consistent, shareable shell environments. Infrastructure engineers, software developers, DevOps teams, SREs, and automation engineers.
- Infrastructure Engineers: Managing Kubernetes clusters, Terraform workspaces, and cloud resources
- Software Developers: Python, Go, Node.js, Rust development with team-shared configurations
- DevOps Teams: Collaborative debugging, shared infrastructure terminals, standardized CI/CD
- SREs & System Administrators: Persistent server management, incident response workflows
- Automation Engineers: API-driven terminal management, scripted operations, tool integration
## CI/CD Integration
Profiles work identically in local development and CI/CD pipelines. Define your environment once, use it everywhere.
Key benefits: reproducibility (same profile locally and in CI), debugging (persistent terminals for failed runs), version control (profiles in repo), structured logs (complete I/O capture), and team consistency (eliminate setup drift).
→ See [docs/cicd.md](docs/cicd.md) for detailed examples and best practices for GitHub Actions, GitLab CI/CD, and Jenkinsfile.
## Container Usage
Official Docker images for running persistent terminals in containerized environments. Quick deployment in Docker, Kubernetes, or any container orchestration platform.
```bash
docker pull docker.io/eminwux/sbsh:v0.6.0-linux-amd64
docker run -it --rm \
-v ~/.sbsh:/root/.sbsh \
docker.io/eminwux/sbsh:v0.6.0-linux-amd64 \
sbsh
```
Images are available for both `linux-amd64` and `linux-arm64` architectures.
→ See [docs/container.md](docs/container.md) for detailed documentation on container usage, volume management, Docker Compose examples, and Kubernetes integration.
## How sbsh Differs from screen and tmux
sbsh is designed for environment management and team collaboration. Key differences: declarative YAML profiles (not dotfiles), built-in discovery and multi-attach, lifecycle hooks, and terminals that survive supervisor crashes.
Unlike tmux or screen, sbsh has no central server or daemon process. Each terminal runs as an independent process with its own lightweight supervisor, so failures are isolated and do not affect other terminals.
→ See [docs/comparison.md](docs/comparison.md) for detailed comparison.
## Why sbsh Exists
Shell environments are still treated as ephemeral and manually configured. Once a shell closes or a connection drops, the environment and all its configuration dies with it. sbsh changes that by making shell environments first-class resources: defined by profiles and durable. Each terminal continues running even if the supervisor exits or restarts.
## Philosophy
sbsh follows the traditional Unix philosophy: build simple tools that do one thing well and compose naturally with others. It treats supervision not as orchestration or complexity, but as clarity, giving interactive work the same discipline that background services have enjoyed for decades. sbsh applies the same principles of Infrastructure-as-Code to interactive environments, turning terminals into reproducible, declarative, and shareable units of work.
As Ken Thompson once said, "One of my most productive days was throwing away 1,000 lines of code." sbsh embraces that mindset by keeping its design small, transparent, and essential: a single program that brings reproducibility, shareability, and persistence to shell environments.
## Status and Roadmap
sbsh is under active development, with a focus on correctness, portability, and clear abstractions before adding integrations.
→ See [ROADMAP.md](./ROADMAP.md) for work in progress, planned features, and the project roadmap.
## Contribute
sbsh is an open project that welcomes thoughtful contributions. The goal is to build a simple, reliable foundation for reproducible, shareable shell environments, not a large framework. Discussions, code reviews, and design proposals are encouraged, especially around clarity, portability, and correctness.
## License
Apache License 2.0
© 2025 Emiliano Spinella (eminwux)