stereOS

https://stereos.ai
Admin
stereOS is a platform that runs AI coding agents inside sandboxed Linux VMs with full isolation,...
Tokens:5,341
Snippets:68
Trust Score:3.1
Update:7 months ago
Show doc for...
Tokens:
Raw
### Setup and Build Commands (Shell)

Source: https://stereos.ai/development/contributing

Commands to clone the repository, set up the development environment using direnv, and build the project. Assumes Nix and direnv are installed.

```shell
git clone https://github.com/<your-username>/stereos
cd stereos
direnv allow

make help
make build
make testCopy
```

--------------------------------

### Go Constructor Pattern Example

Source: https://stereos.ai/development/contributing

An example demonstrating the recommended constructor pattern in Go for creating new instances of a VMManager. It initializes internal maps.

```go
func NewVMManager(imagePath string) *VMManager {
    return &VMManager{
        imagePath: imagePath,
        vms:       make(map[string]*VM),
    }
}
```

--------------------------------

### Go Test Example

Source: https://stereos.ai/development/contributing

An example of a standard Go test function for parsing configuration files. It demonstrates loading a TOML configuration and checking specific values.

```go
func TestConfigParsing(t *testing.T) {
    cfg, err := config.Load("testdata/valid.toml")
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if cfg.VM.Name != "test-vm" {
        t.Errorf("expected name 'test-vm', got '%s'", cfg.VM.Name)
    }
}
```

--------------------------------

### Install QEMU for Stereos AI Runtime

Source: https://stereos.ai/development/local-build

Provides installation commands for QEMU, a runtime dependency for Stereos AI, on different operating systems. QEMU is used for virtualization, with specific backends like HVF on macOS and KVM on Linux.

```shell
# macOS
brew install qemu

# Fedora / RHEL
sudo dnf install qemu-system-aarch64

# Ubuntu / Debian
sudo apt install qemu-system-arm
```

--------------------------------

### Booting and SSHing into OpenCode Agent (Shell)

Source: https://stereos.ai/guides/opencode

Commands to start ('mb up') and establish an SSH connection ('mb ssh') to the OpenCode agent. These are the initial steps to interact with the running agent.

```shell
mb up
mb ssh
```

--------------------------------

### Start Masterblaster Daemon (`mb serve`)

Source: https://stereos.ai/mb/config

Starts the Masterblaster daemon, which listens for CLI commands and manages VM lifecycle operations. It must be running before other commands can be used. The daemon listens on `~/.config/mb/mb.sock`.

```bash
mb serve
mb serve --verbose
```

--------------------------------

### Boot Sandbox (`mb up`)

Source: https://stereos.ai/mb/config

Boots a new sandbox using the `jcard.toml` configuration file in the current directory. If the Masterblaster daemon is not running, it will start automatically in the background.

```bash
mb up
mb up --config /path/to/jcard.toml
```

--------------------------------

### Pull stereOS Mixtape (VM Image)

Source: https://stereos.ai/index

Pulls a pre-built VM image, known as a mixtape, which contains the necessary agents to get started. For example, 'opencode-mixtape' is pulled here.

```bash
mb pull opencode-mixtape
```

--------------------------------

### Install masterblaster CLI

Source: https://stereos.ai/index

Installs the masterblaster CLI using a curl script. This is the initial step to manage stereOS AI agents.

```bash
curl -fsSL https://mb.stereos.ai/install | bash
```

--------------------------------

### Build Stereos AI Binary with Make

Source: https://stereos.ai/development/local-build

Clones the Stereos AI repository, enters the directory, allows direnv to load the Nix development shell, and provides commands to list available targets, build the binary, and run tests. The `direnv allow` command is a one-time setup.

```shell
git clone https://github.com/papercomputeco/stereOS
cd stereos

# direnv auto-enters the Nix dev shell
direnv allow  # first time only

make help     # list targets
make build    # build the binary
make test     # run tests
```

--------------------------------

### Minimal jcard.toml Configuration

Source: https://stereos.ai/reference/jcard-schema

This is a minimal example of a jcard.toml file. It specifies the mixtape image to use and basic agent configuration, including the harness and an initial prompt.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
prompt = "Hello world!"
```

--------------------------------

### Start stereOS Daemon

Source: https://stereos.ai/index

Starts the masterblaster daemon, which is responsible for managing the VM processes for AI agents. This command should be run in a separate terminal and kept running.

```bash
mb serve
```

--------------------------------

### Install and Configure direnv for macOS

Source: https://stereos.ai/development/local-build

Installs the direnv utility using Homebrew on macOS and configures the shell to automatically load direnv hooks. This is essential for managing the development environment for Stereos AI.

```shell
# macOS
brew install direnv

# Add to ~/.zshrc or ~/.bashrc
eval "$(direnv hook zsh)"   # or bash
```

--------------------------------

### jcard.toml with Advanced Agent Configuration

Source: https://stereos.ai/reference/jcard-schema

This example shows a more advanced jcard.toml configuration, including restart policies, maximum restarts, and a timeout for the agent. It also configures environment variables.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
prompt = "Fix the failing tests."
workdir = "/workspace"
restart = "on-failure"
max_restarts = 3
timeout = "1h"

[agent.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"
```

--------------------------------

### jcard.toml with Agent Environment Variables

Source: https://stereos.ai/reference/jcard-schema

This snippet demonstrates how to set environment variables for the agent process within the jcard.toml file. It shows an example of setting the ANTHROPIC_API_KEY.

```toml
[agent.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"
```

--------------------------------

### Git Branch Naming Convention (Shell)

Source: https://stereos.ai/development/contributing

Examples of Git branch naming conventions for different types of changes, such as features, fixes, documentation, and refactoring. This helps maintain a consistent commit history.

```shell
git checkout -b feat/my-feature
# or: fix/issue-description, docs/page-name, refactor/component-name
```

--------------------------------

### Configure and boot VM with agent

Source: https://stereos.ai/intro/overview

Creates a jcard.toml configuration file to specify the mixtape and agent, then boots the VM using 'mb up' and connects to it via SSH using 'mb ssh'.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
prompt = "Hello world!"
```

```bash
mb up
mb ssh
```

--------------------------------

### Initialize Sandbox Configuration (`mb init`)

Source: https://stereos.ai/mb/config

Creates a `jcard.toml` configuration file in the current directory. This file is used to customize sandbox settings. After editing, `mb up` can be used to boot the sandbox.

```bash
mb init
```

--------------------------------

### Configure and Run stereOS Agent

Source: https://stereos.ai/index

Sets up the agent configuration in a 'jcard.toml' file and then boots the VM. The 'jcard.toml' specifies the mixtape and agent details, including the prompt.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
prompt = "Hello world!"
```

```bash
mb up
```

--------------------------------

### Run Stereos AI Tests with Make

Source: https://stereos.ai/development/local-build

Executes the test suite for Stereos AI using the `make test` command. This command leverages standard Go testing practices to verify the functionality of the project.

```shell
make test
```

--------------------------------

### Production Build with Nix

Source: https://stereos.ai/development/local-build

Builds a production-ready binary for Stereos AI using Nix. This command creates a self-contained build artifact without relying on the development shell managed by direnv. The output binary is located at `./result/bin/mb`.

```shell
nix build
```

--------------------------------

### List Sandboxes (`mb list`)

Source: https://stereos.ai/mb/config

Lists all available sandboxes managed by Masterblaster.

```bash
mb list
```

--------------------------------

### Print Version Information (`mb version`)

Source: https://stereos.ai/mb/config

Prints the version information for the Masterblaster CLI.

```bash
mb version
```

--------------------------------

### SSH into Sandbox (`mb ssh`)

Source: https://stereos.ai/mb/config

Establishes an SSH connection into a running sandbox. You can specify a sandbox name or connect to the default one.

```bash
mb ssh
mb ssh my-sandbox
```

--------------------------------

### Project Structure Overview (Nix)

Source: https://stereos.ai/development/contributing

A hierarchical view of the stereos project's directory structure, highlighting key configuration files and directories for Nix, Go modules, and other components.

```nix
stereos/
├── flake.nix                  # Entry point — delegates to flake/ modules (flake-parts)
├── flake/                     # flake-parts modules (split flake.nix logic)
│   ├── devshell.nix           # Developer shell for direnv
│   ├── images.nix             # Image build targets (raw, qcow2, kernel-artifacts)
│   └── checks.nix             # CI verification builds
├── modules/                   # NixOS modules — the core of the OS
│   ├── default.nix            # Aggregator (imports all sub-modules)
│   ├── base.nix               # Core OS: filesystem, SSH, nix settings, hardening
│   ├── boot.nix               # Boot config + boot-time optimizations
│   ├── services/              # Service overrides (stereosd, agentd)
│   └── users/                 # User definitions (agent, admin)
├── profiles/                  # Composable configuration presets
│   ├── base.nix               # Shared foundation (imports image formats)
│   └── dev.nix                # Dev-only: SSH key injection, debug tools
├── mixtapes/                  # Mixtapes — spins with specific AI agents
│   ├── claude-code/
│   ├── opencode/
│   ├── gemini-cli/
│   └── full/
├── formats/                   # Image format definitions (raw, qcow2, kernel)
├── lib/                       # Shared Nix helpers (mkMixtape, SSH key logic)
├── cmd/                       # CLI entry points (mb)
├── internal/                  # Private Go packages
├── Makefile                   # Build and test targets
├── .envrc                     # direnv integration
└── go.mod                     # Go module definition
```

--------------------------------

### Connect and Manage VM Lifecycle

Source: https://stereos.ai/index

Provides commands to connect to the running VM via SSH and to clean up resources by shutting down and destroying the VM.

```bash
mb ssh
```

```bash
mb down
```

```bash
mb destroy
```

--------------------------------

### Manage VM lifecycle

Source: https://stereos.ai/intro/overview

Commands to manage the lifecycle of the sandboxed VM. 'mb down' stops the VM, and 'mb destroy' removes it entirely.

```bash
mb down
mb destroy
```

--------------------------------

### Manage Mixtapes (`mb mixtapes`)

Source: https://stereos.ai/mb/config

Manages locally available mixtape images. This includes listing available mixtapes and pulling new ones from the registry.

```bash
mb mixtapes ls
mb mixtapes pull opencode-mixtape
```

--------------------------------

### OpenCode Agent Configuration (TOML)

Source: https://stereos.ai/guides/opencode

Configuration for the OpenCode agent, specifying the mixtape, harness, prompt, working directory, restart policy, and environment variables like ANTHROPIC_API_KEY.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
prompt = "Analyze the project structure and write missing unit tests."
workdir = "/workspace"
restart = "on-failure"
max_restarts = 3

[agent.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"
```

--------------------------------

### Linting and Formatting Commands (Shell)

Source: https://stereos.ai/development/contributing

Commands to format Go code using gofmt and check for potential errors using go vet. These are essential steps before submitting code.

```shell
gofmt -w .
go vet ./...
```

--------------------------------

### Check Sandbox Status (`mb status`)

Source: https://stereos.ai/mb/config

Displays the current state of a sandbox, including its name, state, mixtape, resource usage, and SSH address. You can check a specific sandbox or all of them.

```bash
mb status
mb status my-sandbox
mb status --all
```

--------------------------------

### Checking and Attaching to OpenCode Agent Tmux Session (Shell)

Source: https://stereos.ai/guides/opencode

Commands to list active tmux sessions ('tmux ls') and attach to the agent's session ('tmux a'). These commands are used to monitor and interact with the agent once it's running.

```shell
sudo -u agent -- tmux -S /run/agentd/tmux.sock ls
sudo -u agent -- tmux -S /run/agentd/tmux.sock a
```

--------------------------------

### Interactive OpenCode Agent Configuration (TOML)

Source: https://stereos.ai/guides/opencode

TOML configuration for an interactive OpenCode session, omitting the 'prompt' field to enable direct user interaction. This allows for ad-hoc analysis and commands.

```toml
mixtape = "opencode-mixtape:latest"

[agent]
harness = "opencode"
workdir = "/workspace"
```

--------------------------------

### Exporting API Key (Shell)

Source: https://stereos.ai/guides/opencode

Command to export the ANTHROPIC_API_KEY environment variable on the host system before booting the OpenCode agent. This is necessary for the agent to authenticate with the Anthropic API.

```shell
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Run Tests (Shell)

Source: https://stereos.ai/development/contributing

Command to execute tests in the stereos project. This is part of the standard testing procedure.

```shell
make testCopy
```

--------------------------------

### Cleaning Up OpenCode Resources (Shell)

Source: https://stereos.ai/guides/opencode

Commands to stop ('mb down') and destroy ('mb destroy') OpenCode agent resources. This is used to clean up the environment after use.

```shell
mb down && mb destroy
```

--------------------------------

### Pull Mixtape Image (`mb pull`)

Source: https://stereos.ai/mb/config

Pulls a mixtape image from the registry. You can specify the image name and optionally a tag.

```bash
mb pull opencode-mixtape
mb pull opencode-mixtape:0.1.0
```

--------------------------------

### Stop Sandbox (`mb down`)

Source: https://stereos.ai/mb/config

Gracefully stops a running sandbox. This command sends a shutdown signal to `stereosd` within the VM, allowing it to unmount shared directories and sync filesystems before powering off. You can force the shutdown.

```bash
mb down
mb down my-sandbox
mb down --force
```

--------------------------------

### Destroy Sandbox (`mb destroy`)

Source: https://stereos.ai/mb/config

Removes a sandbox and all its associated on-disk resources, including the disk image, EFI variables, and state. The command attempts a graceful shutdown before destruction. Confirmation can be bypassed.

```bash
mb destroy my-sandbox
mb destroy --yes
mb destroy --force --yes
```

--------------------------------

### Detaching from Tmux Session (Keyboard Shortcut)

Source: https://stereos.ai/guides/opencode

Keyboard shortcut to detach from a tmux session without stopping the agent. This allows users to return to their host terminal while the agent continues to run.

```text
Ctrl-b then d
```
Tokens:
Raw